Docs

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.

Applies to EngineCloud At launch

View as Markdown
On this page
  1. Set it up
  2. What the agent will do
  3. Which key goes where
  4. Check it afterwards
  5. The app sends
  6. The agent can read
  7. A problem makes the round trip
  8. If you prefer to do it by hand

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

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

Two things are installed, and they do different jobs:

What it isWhat it is for
The Sypnia skillsInstructions 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 serverA 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 shouldYou should see
1Choose 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.
2Call 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.
3Set 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.
4Upload 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.
5Run 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. identify belongs in one place, where your app knows who signed in.

Which key goes where

KeyStarts withWho gets itWhere it lives
Ingest keyspk_Your appIn code or a public environment variable. It can only send.
API token with read, and replay if the agent should watch replayssps_Your coding agent, through MCPIn the agent’s own configuration, never in the repository.
API token with adminsps_Your build, to upload source mapsIn 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

  1. The app sends

    Run your app, click something, and filter the browser’s Network tab by ingest.

    You should see
    A POST to …/v1/ingest/events answered 200, within 10 seconds.
  2. The agent can read

    Ask your agent: «What is failing in my development environment?»

    You should see
    The 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.
  3. A problem makes the round trip

    Follow Your first problem: break something on purpose, then ask your agent to fix it.

    You should see
    The 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.

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