# Connect your agent

Claude Code, Claude Desktop, Cursor and other agents can answer questions about your projects through ShipVitals' MCP server: "What expires this month?", "What broke since the last deploy?", "Which project lost money last month?". The agent reads with a workspace API token, read only, and never sees more than the token allows. This guide covers making the token, adding the server to each agent, checking it works, and what the agent can ask.

## Make a token

Your agent needs a workspace API token. Owners, admins and editors can make one; [API tokens](api-tokens.md) covers who can make what, the list of tokens, and revoking one.

1. Open **Settings** in the sidebar, then **API**, and press **Create token**. ShipVitals may ask you to **Confirm it's you** first.
2. Under **Name**, type something you'll recognise later, like "Claude Code on my laptop". **Access** is **Read only**: an agent can't change anything.
3. Choose the **Projects** the agent may read, and tick **Include amounts** only if it should see revenue, costs and other money. Without amounts, answers leave them out and say "Amounts hidden for this token."
4. Press **Create token**. "This is the only time you'll see it." Press **Copy token**.

Under the token, **Connect your agent with it** shows the setup below with your token already filled in, so you can go straight on.

## Add it to your agent

1. Open **Settings** → **API**, and press **Connect your agent** in the line "Use a token with Claude Code, Claude Desktop, Cursor or another agent:".
2. Paste the token under **API token**. It stays in this page and fills the snippets.
3. Pick your agent's tab: **Claude Code**, **Claude Desktop**, **Cursor** or **Other (HTTP)**. Each shows the exact snippet, with **Copy snippet**, and a line under it saying where it goes.

### Claude Code

Run this in a terminal, with your token in place of `sv_api_…`:

```
claude mcp add --transport http shipvitals https://shipvitals.com/api/mcp --header "Authorization: Bearer sv_api_…"
```

Then run `/mcp` in Claude Code: ShipVitals shows as connected. Add `--scope user` to use it in every project.

### Claude Desktop

1. In Claude Desktop, open **Settings** → **Connectors** → **Add custom connector**.
2. Name it **ShipVitals**, and give it the server URL `https://shipvitals.com/api/mcp`.
3. Under **Request headers**, add `Authorization` with the value `Bearer sv_api_…` (your token).
4. Save, and turn the connector on in a chat.

### Cursor

Put this in `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for every project:

```
{
  "mcpServers": {
    "shipvitals": {
      "url": "https://shipvitals.com/api/mcp",
      "headers": {
        "Authorization": "Bearer sv_api_…"
      }
    }
  }
}
```

### Other (HTTP)

For any other agent, the server speaks MCP over Streamable HTTP at `https://shipvitals.com/api/mcp`. POST JSON-RPC to it with the token as a bearer header and `Accept: application/json, text/event-stream`. It is stateless: there is no session to keep, and GET and DELETE answer 405.

Agents sign in with the token in a header. MCP's OAuth sign-in isn't offered yet.

## Check it works

On **Connect your agent**, with your token pasted, press **Test it** (without a token, it says "Paste a token first."). ShipVitals lists the server's tools with the token and says, for example, "Connected · 10 tools · read-only · 3 projects". If it says "ShipVitals didn't accept that token", check the whole token was pasted; if it was revoked or has expired, make a new one. "Too many requests with this token" means it made more than 60 requests in the last minute.

In **Settings** → **API**, each token's row says when it was last used and from which agent, like "Last used 2 minutes ago from claude-code".

## What your agent can ask

**Try asking** on the setup page gives five questions that work on your workspace. The agent picks among ten tools, all read only:

| Tool | What it answers |
|---|---|
| `list_projects` | The projects the token reads, with their names and ids. |
| `portfolio_summary` | The portfolio's net profit, MRR, costs, health and next expiry, and each project's figures, for a period. |
| `project_summary` | One project's figures for a period, against the period before. |
| `explain_metric` | How one figure is worked out, as its Explain sheet shows it: the formula with its numbers, what it's made of, its sources and how fresh they are. |
| `costs_by` | Costs by provider, service or project for a period, largest first. |
| `revenue` | Net revenue, MRR and its movements, and each project's share. |
| `expiring` | Renewals and expiries due within a window (30 days unless asked), soonest first. |
| `health` | Failing checks, uptime, CI, and each project's release verdict with why. |
| `incidents` | Open incidents, or those resolved in a period. |
| `changes_since_deploy` | What happened to a project since a deploy: incidents, release verdict changes, later deploys, and what is failing now. |

Periods are the dashboard's: the last 7, 30 or 90 days, the last 12 months, month, quarter or year to date, or a custom range. The default is the last 30 days. Each answer is short text with figures written as the app writes them, and ends with a link back into ShipVitals.

Names in answers (projects, checks, renewals, deploys) are in double quotes: they're what people typed, and the agent is told to treat them as data, never as instructions.

## Limits

A token makes up to 60 requests a minute, shared between the REST API and the MCP server. To stop an agent, revoke its token in **Settings** → **API**: it stops working at once, and **Undo** brings it back within 10 seconds (see [Revoke a token](api-tokens.md#revoke-a-token)).

Scripts read the same figures through the REST API with the same kind of token: see [Call the REST API](api-tokens.md#call-the-rest-api).
