# 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: the Sypnia engine (open source, self-hosted) and Sypnia Cloud (paid service). Status: at launch.  
Source: https://docs.sypnia.com/start/install-with-your-agent/

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](https://docs.sypnia.com/start/quickstart-self-host)), its ingest key, and an API token for the agent.

## Set it up

**Claude Code**

1. Add the Sypnia skills:
   ```bash
   claude plugin marketplace add sypnia/skills
   claude plugin install sypnia@sypnia
   ```
2. Connect the MCP server:
   ```bash
   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**

1. Add the Sypnia skills: In Cursor, open **Customize**, choose **From GitHub Repository** and import `sypnia/skills`.
2. Connect the MCP server:

   `.cursor/mcp.json`
   ```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**

1. Paste this prompt:
   ```text
   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](https://docs.sypnia.com/mcp/skills). Every way to connect the MCP server, and which token to give it, is in [Connect](https://docs.sypnia.com/mcp/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. `identify` belongs 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](https://docs.sypnia.com/concepts/projects-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](https://docs.sypnia.com/mcp/connect).

### 3. A problem makes the round trip

Follow [Your first problem](https://docs.sypnia.com/start/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](https://docs.sypnia.com/start/quickstart-cloud) or [Quickstart: self-host](https://docs.sypnia.com/start/quickstart-self-host).
