Docs

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 EngineCloud At launch

View as Markdown
On this page
  1. The token
  2. Where the token goes
  3. Keep it out of your repository
  4. Several projects
  5. Rotate or revoke a token
  6. Errors
  7. Not 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

KindAPI token, sps_ and 40 characters
Scope it needsread. Nothing more
What it reachesOne project. A token belongs to exactly one
Where to create itSypnia 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

ConnectionHow 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
{
  "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.

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:

Terminal
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 answersMeaning
401 unauthorizedNo token, or one that is unknown, revoked or expired
403 wrong_credentialAn ingest key (spk_…) was sent. The MCP server only takes API tokens
403 forbiddenThe token has no read scope
429 rate_limitedThe 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.

Sections

Start hereWhat Sypnia is, how it works, what is open source and what is the paid cloud, and the two ways to get your first problem in plain words.ConceptsThe ten ideas Sypnia is made of, each defined precisely, from a project and its keys to problems, traces and alerts.SDKsHow your app sends data to Sypnia. One SDK for the browser, one for Node, one for Next.js, and the OpenTelemetry intake for every other backend.The agentHow Sypnia analyses a problem, what it writes, what it sends to a model and what it never does.MCP and skillsConnect your coding agent to Sypnia so it can ask what is failing in production, read what it needs to fix it, and set Sypnia up for you.API referenceThe Sypnia HTTP API: one API for the open-source engine and for Sypnia Cloud, with every endpoint, parameter, response and error.CLI referenceThe sypnia command: how to install it, the variables it reads, what its exit codes mean, and where each command is documented.Self-hostingWhat you run when you host the Sypnia engine yourself, what you need, what it costs, and what you do not get compared with Sypnia Cloud.How the engine is builtThe whole Sypnia engine on one page, from a click in your app to the sentence your coding agent reads, with the design rules and the code that holds them.Sypnia CloudHow the paid service works, from organizations and roles to plans, limits, billing, where your data lives, the GitHub App and support.Privacy and securityWhat Sypnia collects from your app and its users, what it never collects, how masking works, how to delete data, and how the service is protected.LicensingWhich licence covers each part of Sypnia, what you may do with it, how the name may be used, and the terms of a contribution.GuidesStep-by-step recipes for the common ways to use Sypnia, from apps made with AI builders and Next.js on Vercel to Supabase, source maps in CI, alert e-mails from your own engine, and moving from Sentry.ReferenceThe pages you look things up in, from the event schema and the glossary to what is planned, the changelog and the common questions.
↑↓ to move↵ to openEsc to close