# Authentication

> Which token the MCP server takes, the scope it needs, where the token goes in each kind of connection, and how to keep it safe.

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

For agents: How the Sypnia MCP server authenticates: an API token (sps_) with the read scope, sent as an Authorization Bearer header to the remote server or as SYPNIA_API_TOKEN to the local one; one token is one project; no OAuth at launch.

**\[Engine]** **\[Cloud]** The MCP server uses the same credential as the HTTP API: an API token. There is no separate account or password for it, and no sign-in window.

## The token

|                    |                                                                                                                                                                                                          |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Kind               | API token, `sps_` and 40 characters                                                                                                                                                                      |
| Scope it needs     | `read`. Nothing more                                                                                                                                                                                     |
| What it reaches    | One project. A token belongs to exactly one                                                                                                                                                              |
| Where to create it | Sypnia Cloud: in the app, under the project's settings. Self-hosted: `sypnia token create --name "My agent" --scopes read`, or [`POST /v1/tokens`](https://docs.sypnia.com/api/projects-keys-and-tokens) |

`read` is enough for all ten tools, including `resolve_problem`: marking a problem resolved is one of the reversible marks a `read` token may make. See [the scopes](https://docs.sypnia.com/api/overview-and-authentication).

Do not give an agent a token with `admin`. The server does not use it, and the token in your agent's configuration could then be used directly against the API to revoke keys or delete data. Do not use the root token of a self-hosted engine either.

> **Note: Give each agent its own token**
>
> Name the token after who uses it: «Cursor, Ana's laptop». The name appears on every problem the agent resolves (`resolved_by: mcp:Cursor, Ana's laptop`), and you can revoke one agent without touching the others.

## Where the token goes

| Connection                                  | How the token is sent                                                                                        |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| Remote server (Sypnia Cloud or your engine) | In the `Authorization` header of every request: `Authorization: Bearer sps_…`                                |
| Local server (`@sypnia/mcp`)                | In the environment variable `SYPNIA_API_TOKEN`. The local server then sends it to the API in the same header |

The remote server does not store the token. It checks it with the engine on each request and uses it to read your project, exactly as the API would.

## Keep it out of your repository

A token in a committed file is a leaked token. Both clients can read it from the environment instead.

**Claude Code**

In a shared `.mcp.json`, write `${SYPNIA_API_TOKEN}` and set the variable on each person's machine:

`.mcp.json`

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

A server you add for yourself, without `--scope project`, is stored in your own settings, not in the repository.

**Cursor**

In `.cursor/mcp.json`, write `${env:SYPNIA_API_TOKEN}`:

`.cursor/mcp.json`

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

**Any agent**

If your client cannot read the environment in its configuration, keep that configuration file out of version control, or use the local server and set `SYPNIA_API_TOKEN` in the environment the client starts it with.

## Several projects

One token is one project, so one connection is one project. To work with two projects, add the server twice under two names, each with its own token:

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

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

Your agent then sees `sypnia-shop.problems` and `sypnia-blog.problems`, and cannot mix them up.

## Rotate or revoke a token

1. Create a new token.
2. Put it in the configuration and restart the client.
3. Revoke the old one: in the app, with `sypnia token revoke <token id>`, or with `DELETE /v1/tokens/{token_id}`.

A revoked token is refused within one minute. If a token may have leaked, revoke it first.

## Errors

| The server answers     | Meaning                                                                                |
| ---------------------- | -------------------------------------------------------------------------------------- |
| `401 unauthorized`     | No token, or one that is unknown, revoked or expired                                   |
| `403 wrong_credential` | An ingest key (`spk_…`) was sent. The MCP server only takes API tokens                 |
| `403 forbidden`        | The token has no `read` scope                                                          |
| `429 rate_limited`     | The token made more than 600 requests in a minute. The agent should wait and try again |

## Not at launch

Signing in through the browser (OAuth), where the client opens a page and you approve it, is not available at launch. The token in the header is the only way.
