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.
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 |
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.
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.
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:
{
"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}:
{
"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:
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
- Create a new token.
- Put it in the configuration and restart the client.
- Revoke the old one: in the app, with
sypnia token revoke <token id>, or withDELETE /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.