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.
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
-
Add the Sypnia skills
claude plugin marketplace add sypnia/skills claude plugin install sypnia@sypnia -
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».
Cursor
-
Add the Sypnia skills
In Cursor, open Customize, choose From GitHub Repository and import
sypnia/skills. -
Connect the MCP server
.cursor/mcp.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
-
Paste this prompt
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
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/mcpFor a self-hosted engine with the local server, add
--env SYPNIA_BASE_URL=https://sypnia.example.combefore--transport.You should seeClaude Code confirms that it added the serversypnia.
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:
{
"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
Write the configuration
Create
.cursor/mcp.jsonin your project, or~/.cursor/mcp.jsonto have Sypnia in every project.Sypnia Cloud:
.cursor/mcp.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 { "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"toenv.
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:
{
"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 of a problem into it.
Check that it works
Ask your agent:
What is failing in production?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 |
| 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: 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.