Docs

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

View as Markdown
On this page
  1. The short way
  2. Which server
  3. Connect your client
  4. Add the server
  5. Check it
  6. Write the configuration
  7. Set the token
  8. Check it
  9. Check that it works
  10. Options of the local server
  11. When it does not work
  12. Next

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.

The short way

Claude Code

  1. Add the Sypnia skills

    claude plugin marketplace add sypnia/skills
    claude plugin install sypnia@sypnia
  2. Connect the MCP server

    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».

What the skills do

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.

ServerAddressUse it when
Remote, Sypnia Cloudhttps://mcp.sypnia.com/mcpYour project is on Sypnia Cloud. Nothing to install
Remote, your engine<your base URL>/mcpYou self-host. The engine serves it next to the API
Local (@sypnia/mcp)A program on your machine, over stdioYour 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:

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

    A self-hosted engine:

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

    The local server:

    Terminal
    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

    Terminal
    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
{
  "mcpServers": {
    "sypnia": {
      "type": "http",
      "url": "https://mcp.sypnia.com/mcp",
      "headers": {
        "Authorization": "Bearer ${SYPNIA_API_TOKEN}"
      }
    }
  }
}

To remove the server: claude mcp remove sypnia.

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.

VariableFlagDefaultMeaning
SYPNIA_API_TOKENNoneNone, requiredThe API token
SYPNIA_BASE_URL--base-url <url>https://api.sypnia.comYour engine’s base URL, without /v1
SYPNIA_PROJECT--project <id or slug>NoneOnly with a credential that sees several projects
SYPNIA_MCP_READ_ONLY--read-onlyfalsetrue removes resolve_problem

When it does not work

What you seeWhyWhat to do
401 unauthorizedThe token is missing, mistyped, revoked or expiredCreate a new token and update the configuration. Check there is exactly one space after Bearer
The server connects and lists no toolsThe client is talking to the wrong addressThe URL must end in /mcp
403 wrong_credentialYou used an ingest key (spk_…)Use an API token (sps_…)
Works from your laptop, not from a cloud agentYour self-hosted engine is not reachable from thereExpose the engine, or run the local server where it can reach it
resolve_problem is missingThe server is read-onlySee Security
Answers are about the wrong appThe token belongs to another projectEach token is one project. Add one server per project, each under its own name, for example sypnia-shop and sypnia-blog

Next

  • Skills: let your agent set Sypnia up and fix problems the same way every time.
  • Examples: three sessions, from the question to the fix.
  • Tools reference: every tool and what it returns.

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