# Install with your coding agent

> Connect Claude Code, Cursor, VS Code, Codex or Windsurf to the Whisperr MCP server so your agent installs the SDK and checks that events arrive.

This page shows how to connect your coding agent to Whisperr so that it installs the SDK in your repository and checks that real events arrive. Use it if you work in Claude Code, Cursor, VS Code, Codex, Windsurf or another agent that supports remote MCP servers.

If your agent cannot add an MCP server, give it the [setup guide](/setup/) instead.

## What is the Whisperr agent kit?

The [Whisperr agent kit](https://github.com/WhisperrAI/whisperr-agent-kit) connects your agent to the Whisperr MCP server and adds three skills:

| Skill                   | What it does                                                                                                                                                                                                                                                                                                  |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `whisperr-install`      | Detects your stack, installs the Whisperr SDK at the latest version, adds init, identify and reset, push tokens and push-open tracking, links RevenueCat, Superwall or Adapty, wires your required events, builds before and after (no new errors), registers new events, and waits until real events arrive. |
| `whisperr-insights`     | Answers retention questions (“how many users are at risk, and why?”) from your live Whisperr data. Changes apply when you ask; risky ones wait for your confirmation in the chat.                                                                                                                             |
| `whisperr-keep-in-sync` | Checks every code change that touches tracked events, so a refactor does not silently stop an event.                                                                                                                                                                                                          |

The `whisperr-install` skill supports Swift/iOS, React Native/Expo, Flutter, web (React, Next.js, any JavaScript app) and Node. For Python, PHP and .NET, it follows the SDK quickstarts in these docs.

Whisperr decides what to track. Your agent does the code work and proves it with real events.

## Which MCP address do I use?

Whisperr has two MCP addresses. Both use Streamable HTTP and OAuth 2.1.

| Address                            | Tools                                             | Used by                                                         |
| ---------------------------------- | ------------------------------------------------- | --------------------------------------------------------------- |
| `https://mcp.whisperr.net/install` | Install tools only                                | The Whisperr dashboard and the install commands on this page    |
| `https://mcp.whisperr.net/mcp`     | Every tool: install, data and dashboard questions | The agent kit, and agents that answer questions about your data |

To install Whisperr, use `/install`, the address the dashboard shows. If you also want the agent to answer questions about your data, use `/mcp` instead: replace `/install` with `/mcp` in the commands below.

The first tool call opens a browser sign-in. You pick your Whisperr app and approve its scopes:

| Scope             | Allows                                                                                                                                                                                                                                                                                     |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data:read`       | Read the workspace: integration requirements and received events, users (pseudonymous, contacts masked), interventions, messages and settings. Never secrets, keys or delivery addresses.                                                                                                  |
| `install:write`   | Register and validate event definitions, send isolated test events, report deployments, and request provider connections that a person approves in the browser. Owners and admins only.                                                                                                    |
| `changes:propose` | Make workspace changes, such as pausing an intervention or editing knowledge. Changes apply at once. Risky ones, such as sending to real people, deleting, revoking keys or invitations, removing members and changing roles, run only after an owner or admin confirms them in the agent. |

### How long does the sign-in last?

Every sign-in gives your agent a refresh token, whether or not it asks for `offline_access`. An access token lasts 15 minutes (`expires_in: 900`). Your agent renews it at the token endpoint with `grant_type=refresh_token`, without asking you to sign in again. Whisperr accepts `offline_access` but does not repeat it in the granted `scope`. The sign-in ends after 30 days without use, and one year after you approved it at the latest.

## Connect your agent

**Claude Code**

Plugin with the MCP server and the three skills. In a Claude Code session:

```text
/plugin marketplace add WhisperrAI/whisperr-agent-kit
/plugin install whisperr@whisperr
```

Or from your shell:

```bash
claude plugin marketplace add WhisperrAI/whisperr-agent-kit
claude plugin install whisperr@whisperr
```

Restart the session, run `/mcp`, select `whisperr` and sign in.

The plugin uses `/mcp`. MCP server only, without the skills:

```bash
claude mcp add --transport http whisperr https://mcp.whisperr.net/install
```

**Cursor**

[Add Whisperr to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=whisperr\&config=eyJ1cmwiOiJodHRwczovL21jcC53aGlzcGVyci5uZXQvaW5zdGFsbCJ9) opens Cursor and adds the MCP server. Or add it to your Cursor MCP configuration by hand:

`mcp.json`

```json
{
  "mcpServers": {
    "whisperr": { "url": "https://mcp.whisperr.net/install" }
  }
}
```

Cursor opens the sign-in in your browser the first time it connects.

For the skills and the rule, copy these from the agent kit into your repository: `rules/whisperr.mdc` to `.cursor/rules/whisperr.mdc`, and the `skills/` folders to `.cursor/skills/`.

**VS Code**

[Install Whisperr in VS Code](https://vscode.dev/redirect/mcp/install?name=whisperr\&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.whisperr.net%2Finstall%22%7D) (GitHub Copilot agent mode). Or from your shell:

```bash
code --add-mcp '{"name":"whisperr","type":"http","url":"https://mcp.whisperr.net/install"}'
```

Then start the server from the MCP view in VS Code and sign in.

**Codex**

Plugin with the MCP server (`/mcp`) and the three skills:

```bash
codex plugin marketplace add WhisperrAI/whisperr-agent-kit
codex plugin add whisperr@whisperr
```

MCP server only:

```bash
codex mcp add whisperr --url https://mcp.whisperr.net/install
codex mcp login whisperr
```

The login command opens your browser to sign in.

**ChatGPT**

To ask about your data in ChatGPT, turn on developer mode and add `https://mcp.whisperr.net/mcp` as a custom MCP connection.

**Windsurf**

Devin Local agent:

```bash
devin mcp add whisperr https://mcp.whisperr.net/install
```

Legacy Cascade agent: add this to `mcp_config.json` (`~/.config/devin/mcp_config.json`; older Windsurf installs use `~/.codeium/windsurf/mcp_config.json`):

`mcp_config.json`

```json
{
  "mcpServers": {
    "whisperr": { "serverUrl": "https://mcp.whisperr.net/install" }
  }
}
```

**Other clients**

Any MCP client that supports remote HTTP servers with OAuth:

```json
{
  "mcpServers": {
    "whisperr": { "type": "http", "url": "https://mcp.whisperr.net/install" }
  }
}
```

To use the skills in another agent, copy the `skills/` folders from the agent kit to the place where your agent loads skills.

The Whisperr dashboard shows the same setup for Claude Code, Cursor, VS Code and Codex, with the `/install` address. During setup it is on **Home → Connect your code → Your coding agent**. After setup it is in **Integrations → Your code → Coding agent**, where owners can also disconnect a connected agent.

## Install Whisperr

Ask your agent:

```text
Install Whisperr in this app and verify that events arrive.
```

The agent reads your event plan from Whisperr, installs the SDK, wires the events, builds the app and asks you to run it. While you sign in and use the app, it checks the received events every 15 seconds, for up to 10 minutes. Events that need real time to happen, such as renewals, can stay “waiting”; the agent marks them “verify after release”.

The agent follows the same rules as the SDK quickstarts:

- The publishable key (`wpk_…`) goes in client code. The server key (`wrk_…`) stays in server secrets. Whisperr tools never return keys, so the agent asks you to create one in **Settings → API keys**. Every workspace can create keys, also before the trial starts.
- `first_name` is the only name trait. Email goes only as a channel. Client code sends the user’s email choice as `optedIn` when the app knows it. Whether that opts the address in depends on your answer to **Does your signup get permission to email users?**
- When the repository has a backend, the agent confirms email consent there with the server key. When it does not, your consent answer decides. See [Contact consent](/concepts/consent/).
- `identify()` runs after sign-up, after login, and on every app start when a user is signed in. `reset()` runs on logout.
- With RevenueCat, Superwall or Adapty, that SDK’s login call gets the same user ID as `identify()`. See [RevenueCat](/integrations/revenuecat/), [Superwall](/integrations/superwall/) and [Adapty](/integrations/adapty/).
- No new compiler or analyzer errors.

## Ask about your data

With the `/mcp` server connected, ask questions such as:

- “How many users are at risk this week, and why?”
- “Which tracked events stopped arriving?”
- “Pause the win-back intervention.” The agent pauses it and tells you the result.
- “Send me a test push.” The agent shows what it will send and to whom, and sends it only after you confirm. Clients with their own confirmation prompt ask you there.

Entering credentials, provider sign-ins, team invitations and confirming a catalog feed still happen in the browser. For these, the agent gives you a link. Billing is in Settings > Billing.

## Rules for your repository

Agents follow short, always-loaded rules better than on-demand skills. Copy the block for your agent from the agent kit into your repository, then replace the `<…>` placeholders with your SDK package, version, init file and key variable:

| Agent                               | File in your repository       | Source in the agent kit                                                                                                     |
| ----------------------------------- | ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| Codex, Cursor, Copilot, most agents | `AGENTS.md`                   | [`snippets/AGENTS.md`](https://github.com/WhisperrAI/whisperr-agent-kit/blob/main/snippets/AGENTS.md)                       |
| Claude Code                         | `CLAUDE.md`                   | [`snippets/CLAUDE.md`](https://github.com/WhisperrAI/whisperr-agent-kit/blob/main/snippets/CLAUDE.md)                       |
| Cursor                              | `.cursor/rules/whisperr.mdc`  | [`rules/whisperr.mdc`](https://github.com/WhisperrAI/whisperr-agent-kit/blob/main/rules/whisperr.mdc)                       |
| Windsurf                            | `.windsurf/rules/whisperr.md` | [`snippets/windsurf-whisperr.md`](https://github.com/WhisperrAI/whisperr-agent-kit/blob/main/snippets/windsurf-whisperr.md) |

The `whisperr-install` skill offers to add this block for you.

## How do I install with an AI app builder?

Lovable, Bolt, Rork and other app builders that cannot add an MCP server use a short prompt and the [setup guide](/setup/) instead. In the dashboard, open **Home → Connect your code**, choose **Copy prompt**, and pick your platform. Click **Add an app key** to put a new app key in the prompt (owners and admins), or create one in **Settings → API keys** with the kind **App**. Copy the prompt and paste it into the tool. It starts with:

```text
Install Whisperr in this app: follow https://docs.whisperr.net/setup.md
```

The next lines carry your app key, the platform, your answer to **Does your signup get permission to email users?**, your app’s main action and the events Whisperr already uses, when Whisperr knows them. The agent reads the setup guide for everything else. Then run the app, sign up, use its main action and log out, so that each event arrives once.

After setup, the prompt is in **Integrations → Your code → Your app**: choose **Copy a prompt**, click **Copy prompt**, and use **Get an app key** to create the key on the API keys page.

The same prompt is in the agent kit as [`snippets/copy-prompt.md`](https://github.com/WhisperrAI/whisperr-agent-kit/blob/main/snippets/copy-prompt.md), to fill by hand. Any agent can also start from the setup guide alone: `https://docs.whisperr.net/setup.md`. Replit also accepts a custom remote MCP server: use `https://mcp.whisperr.net/install`.

## What does the agent send to Whisperr?

Tool arguments only: event definitions (code, name, property schema), synthetic test events, deployment identifiers such as a commit SHA, and your questions about your data. Test events never create live users. Whisperr tools never return delivery addresses (email, phone, push tokens), API keys or secrets. See the [privacy policy](https://whisperr.net/privacy/).

## Common questions

### What is the difference between https://mcp.whisperr.net/mcp and https://mcp.whisperr.net/install?

/install has only the tools a coding agent needs to add Whisperr to an app. The dashboard and the install commands on this page use it. /mcp has every Whisperr tool: install, data and dashboard questions. The agent kit uses /mcp. Both work, but a sign-in for one does not work on the other.

### Can my agent change my Whisperr workspace?

Yes, when you ask it to. A write tool such as set_intervention_status makes the change when the agent calls it. Risky changes, such as sending a message to a real person, deleting, revoking keys or changing your team, change nothing on the first call: the agent shows the exact summary and runs it only after an owner or admin confirms, in the chat or in the client's own confirmation prompt.

### Who can register events through the agent?

Registering events and reporting deployments need the install:write scope, which only workspace owners and admins can grant.

### Does the agent kit run code on my machine?

No. The kit contains only text: manifests, skills, rules and images. Your agent runs the commands the skills describe, such as package installs and builds, under your own approval settings.

### Can the agent read my users' email addresses or my API keys?

No. Whisperr tools never return delivery addresses (email, phone, push tokens), API keys or secrets. User data comes back pseudonymous, with contacts masked.

Source: https://docs.whisperr.net/agents/