Install with your coding agent
Let Claude Code, Cursor or any coding agent add Sypnia to your project, what it will change, the exact prompt for agents without skills, and what to check afterwards.
This page is for anyone who would rather not edit the code by hand. Your coding agent can add Sypnia to your project for you. It works the same for Sypnia Cloud and for a self-hosted engine: the agent asks which one you use.
At the end you will have: the SDK installed and started in your project, source maps uploaded by your build, your agent connected to Sypnia so it can read problems, and a first check that events arrive.
You need: a project (on Sypnia Cloud, create it in app.sypnia.com; on your own engine, see the self-host quickstart), its ingest key, and an API token for the agent.
Set it up
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.
Two things are installed, and they do different jobs:
| What it is | What it is for | |
|---|---|---|
| The Sypnia skills | Instructions your agent loads when a task needs them: sypnia-setup adds Sypnia to a project, sypnia-fix fixes a problem Sypnia reported. Open source, MIT. | The agent sets Sypnia up correctly the first time, instead of guessing from memory. |
| The MCP server | A connection from your agent to your Sypnia project. | The agent can ask «what is failing in production?» and read the problem, the trace and the session itself. |
What each skill may touch, and how to update or remove it, is in Skills. Every way to connect the MCP server, and which token to give it, is in Connect.
An agent that has neither skills nor MCP can still do the setup: the Any agent tab is a prompt that points it at these docs, which every agent can read as plain text.
What the agent will do
Whichever way you start it, a correct setup is these five things. Read the agent’s diff against this list before you accept it.
| # | The agent should | You should see |
|---|---|---|
| 1 | Choose the SDK that fits: @sypnia/next for Next.js, @sypnia/browser for any other web app, @sypnia/node for a Node server. Install it with your project’s package manager. | One new dependency in package.json, two if the project has a frontend and a Node backend. |
| 2 | Call init once, where the app starts, with the key read from an environment variable. | A line like project: import.meta.env.VITE_SYPNIA_PROJECT_KEY, and the variable in .env. For Next.js: withSypnia in next.config.ts and two small instrumentation files. |
| 3 | Set environment so that only your real domain reports as production, and release to the short git commit. | Both in the init options, or left to withSypnia, which sets them itself. |
| 4 | Upload source maps in your build and keep them out of what is published, with the API token read from a secret called SYPNIA_API_TOKEN. | A step in your build or CI. No token in the code. |
| 5 | Run a first check and tell you where to look. | The request to look for in the browser’s Network tab, and where the first session appears. |
And three things it must not do:
- Put an API token (
sps_…) in the code or in a public variable. Only the ingest key (spk_…) is public. If you see a token in the diff, reject it and revoke the token. - Turn masking off or try to record typed input. There is no option for it, and no reason to look for one.
- Add calls all over your code. Errors, clicks, page views and requests are captured without them.
identifybelongs in one place, where your app knows who signed in.
Which key goes where
| Key | Starts with | Who gets it | Where it lives |
|---|---|---|---|
| Ingest key | spk_ | Your app | In code or a public environment variable. It can only send. |
API token with read, and replay if the agent should watch replays | sps_ | Your coding agent, through MCP | In the agent’s own configuration, never in the repository. |
API token with admin | sps_ | Your build, to upload source maps | In your CI’s or host’s secrets. |
Create the two tokens separately, so you can revoke one without stopping the other. See Projects, environments, keys and tokens.
Check it afterwards
The agent can read
Ask your agent: «What is failing in my development environment?»
You should seeThe agent calls Sypnia and answers with a list of problems, or says there are none. An error about authorization means the token is missing or wrong: see Connect.A problem makes the round trip
Follow Your first problem: break something on purpose, then ask your agent to fix it.
You should seeThe problem appears within 2 minutes, the agent reads it, proposes the change, and after your review the problem is resolved.
If you prefer to do it by hand
The same setup, step by step: Quickstart: Sypnia Cloud or Quickstart: self-host.