# Connect

> Connect Claude Code, Cursor or any other MCP client to the Sypnia MCP server, remote or local, with the exact command or snippet for each.

Applies to: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/mcp/connect/

For agents: Exact commands and config snippets to connect the Sypnia MCP server: Claude Code (claude mcp add), Cursor (.cursor/mcp.json), other clients; remote Streamable HTTP at https://mcp.sypnia.com/mcp, self-hosted <base URL>/mcp, local stdio with npx @sypnia/mcp.

**\[Engine]** **\[Cloud]** This page is for anyone who uses a coding agent that speaks MCP.

**At the end you will have:** your coding agent connected to Sypnia, answering «what is failing in production?» with real data from your project.

**Before you start** you need an API token with the `read` scope. Create one in the app (Sypnia Cloud), or with `sypnia token create --name "My agent" --scopes read` (self-hosted). See [Authentication](https://docs.sypnia.com/mcp/authentication).

## The short way

**Claude Code**

1. Add the Sypnia skills:
   ```bash
   claude plugin marketplace add sypnia/skills
   claude plugin install sypnia@sypnia
   ```
2. Connect the MCP server:
   ```bash
   claude mcp add --transport http sypnia \
     https://mcp.sypnia.com/mcp \
     --header "Authorization: Bearer YOUR_API_TOKEN"
   ```

Then say: «Set up Sypnia in this project».

**Cursor**

1. Add the Sypnia skills: In Cursor, open **Customize**, choose **From GitHub Repository** and import `sypnia/skills`.
2. Connect the MCP server:

   `.cursor/mcp.json`
   ```json
   {
     "mcpServers": {
       "sypnia": {
         "url": "https://mcp.sypnia.com/mcp",
         "headers": {
           "Authorization": "Bearer ${env:SYPNIA_API_TOKEN}"
         }
       }
     }
   }
   ```

Then say: «Set up Sypnia in this project».

**Any agent**

1. Paste this prompt:
   ```text
   Read https://docs.sypnia.com/llms.txt and follow the quickstart it points to. Add Sypnia to this project: install @sypnia/browser, call init() with my project key (ask me for it), and tell me how to check that the first session arrived.
   ```

An agent with no skills or MCP support can still read every page: each one is plain Markdown at its address plus `.md`.

The rest of this page is the same thing in full: every client, a self-hosted engine, and the local server.

## Which server

There are three ways to reach the same ten tools. Pick one.

| Server                    | Address                               | Use it when                                                                                                                    |
| ------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Remote, Sypnia Cloud**  | `https://mcp.sypnia.com/mcp`          | Your project is on Sypnia Cloud. Nothing to install                                                                            |
| **Remote, your engine**   | `<your base URL>/mcp`                 | You self-host. The engine serves it next to the API                                                                            |
| **Local** (`@sypnia/mcp`) | A program on your machine, over stdio | Your client only supports stdio, or your engine is not reachable from where the client connects. It calls the HTTP API for you |

The remote servers speak Streamable HTTP and take the token in the `Authorization` header. The local one needs Node.js 20 or later and takes the token from an environment variable.

## Connect your client

**Claude Code**

### 1. Add the server

Run one of these in your project's directory.

Sypnia Cloud:

```bash
claude mcp add --transport http sypnia \
  https://mcp.sypnia.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

A self-hosted engine:

```bash
claude mcp add --transport http sypnia \
  https://sypnia.example.com/mcp \
  --header "Authorization: Bearer YOUR_API_TOKEN"
```

The local server:

```bash
claude mcp add --env SYPNIA_API_TOKEN=YOUR_API_TOKEN --transport stdio sypnia \
  -- npx -y @sypnia/mcp
```

For a self-hosted engine with the local server, add `--env SYPNIA_BASE_URL=https://sypnia.example.com` before `--transport`.

**You should see:**Claude Code confirms that it added the server `sypnia`.

### 2. Check it

```bash
claude mcp list
```

**You should see:**`sypnia` is listed as connected. Inside a session, `/mcp` shows the server and its tools.

By default the server is added for you, in this project. Add `--scope user` to have it in every project, or `--scope project` to share it with your team through a `.mcp.json` file at the root of the repository. In that file, take the token from the environment so it is never committed:

`.mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "type": "http",
      "url": "https://mcp.sypnia.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

To remove the server: `claude mcp remove sypnia`.

**Cursor**

### 1. Write the configuration

Create `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` to have Sypnia in every project.

Sypnia Cloud:

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "url": "https://mcp.sypnia.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

A self-hosted engine: the same, with `"url": "https://sypnia.example.com/mcp"`.

The local server:

`.cursor/mcp.json`

```json
{
  "mcpServers": {
    "sypnia": {
      "command": "npx",
      "args": ["-y", "@sypnia/mcp"],
      "env": {
        "SYPNIA_API_TOKEN": "${env:SYPNIA_API_TOKEN}"
      }
    }
  }
}
```

For a self-hosted engine with the local server, add `"SYPNIA_BASE_URL": "https://sypnia.example.com"` to `env`.

### 2. Set the token

`${env:SYPNIA_API_TOKEN}` reads the token from your environment, so the file is safe to commit. Set the variable where Cursor starts, for example in your shell profile:

```bash
export SYPNIA_API_TOKEN=YOUR_API_TOKEN
```

Then restart Cursor.

### 3. Check it

Open **Customize** in Cursor's sidebar.

**You should see:**`sypnia` is listed with its tools, and its toggle is on. The same toggle switches the server off without removing it.

**Any agent**

Any MCP client can connect. Give it one of these, in whatever form its configuration takes.

**A remote server** (Streamable HTTP):

| Setting | Value                                                                     |
| ------- | ------------------------------------------------------------------------- |
| URL     | `https://mcp.sypnia.com/mcp`, or `<your base URL>/mcp` when you self-host |
| Header  | `Authorization: Bearer YOUR_API_TOKEN`                                    |

**A local server** (stdio):

| Setting     | Value                                                                                       |
| ----------- | ------------------------------------------------------------------------------------------- |
| Command     | `npx`                                                                                       |
| Arguments   | `-y @sypnia/mcp`                                                                            |
| Environment | `SYPNIA_API_TOKEN=YOUR_API_TOKEN`, and `SYPNIA_BASE_URL=<your base URL>` when you self-host |

Many clients read a JSON file of this shape:

```json
{
  "mcpServers": {
    "sypnia": {
      "command": "npx",
      "args": ["-y", "@sypnia/mcp"],
      "env": { "SYPNIA_API_TOKEN": "YOUR_API_TOKEN" }
    }
  }
}
```

A client that only supports the older HTTP+SSE transport cannot reach the remote server: use the local one.

An agent with no MCP support can still use Sypnia: copy [the prompt](https://docs.sypnia.com/agent/the-prompt) of a problem into it.

## Check that it works

Ask your agent:

```text
What is failing in production?
```

**You should see:**

The agent calls the tool `health` (your client may ask you to allow it) and answers from your project's data. With nothing wrong, it says so. Clients show the call under the server's name: `sypnia.health`, `sypnia:health` or `mcp__sypnia__health`.

## Options of the local server

`@sypnia/mcp` reads these. Flags win over variables.

| Variable               | Flag                     | Default                  | Meaning                                           |
| ---------------------- | ------------------------ | ------------------------ | ------------------------------------------------- |
| `SYPNIA_API_TOKEN`     | None                     | None, required           | The API token                                     |
| `SYPNIA_BASE_URL`      | `--base-url <url>`       | `https://api.sypnia.com` | Your engine's base URL, without `/v1`             |
| `SYPNIA_PROJECT`       | `--project <id or slug>` | None                     | Only with a credential that sees several projects |
| `SYPNIA_MCP_READ_ONLY` | `--read-only`            | `false`                  | `true` removes `resolve_problem`                  |

## When it does not work

| What you see                                   | Why                                                 | What to do                                                                                                                  |
| ---------------------------------------------- | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `401 unauthorized`                             | The token is missing, mistyped, revoked or expired  | Create a new token and update the configuration. Check there is exactly one space after `Bearer`                            |
| The server connects and lists no tools         | The client is talking to the wrong address          | The URL must end in `/mcp`                                                                                                  |
| `403 wrong_credential`                         | You used an ingest key (`spk_…`)                    | Use an API token (`sps_…`)                                                                                                  |
| Works from your laptop, not from a cloud agent | Your self-hosted engine is not reachable from there | Expose the engine, or run the local server where it can reach it                                                            |
| `resolve_problem` is missing                   | The server is read-only                             | See [Security](https://docs.sypnia.com/mcp/security)                                                                        |
| Answers are about the wrong app                | The token belongs to another project                | Each token is one project. Add one server per project, each under its own name, for example `sypnia-shop` and `sypnia-blog` |

## Next

- [Skills](https://docs.sypnia.com/mcp/skills): let your agent set Sypnia up and fix problems the same way every time.
- [Examples](https://docs.sypnia.com/mcp/examples): three sessions, from the question to the fix.
- [Tools reference](https://docs.sypnia.com/mcp/tools-reference): every tool and what it returns.
