Skip to content
Guides

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 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
    list_projects
    What it answers
    The projects the token reads, with their names and ids.
  • Tool
    portfolio_summary
    What it answers
    The portfolio's net profit, MRR, costs, health and next expiry, and each project's figures, for a period.
  • Tool
    project_summary
    What it answers
    One project's figures for a period, against the period before.
  • Tool
    explain_metric
    What it answers
    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.
  • Tool
    costs_by
    What it answers
    Costs by provider, service or project for a period, largest first.
  • Tool
    revenue
    What it answers
    Net revenue, MRR and its movements, and each project's share.
  • Tool
    expiring
    What it answers
    Renewals and expiries due within a window (30 days unless asked), soonest first.
  • Tool
    health
    What it answers
    Failing checks, uptime, CI, and each project's release verdict with why.
  • Tool
    incidents
    What it answers
    Open incidents, or those resolved in a period.
  • Tool
    changes_since_deploy
    What it answers
    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).

Scripts read the same figures through the REST API with the same kind of token: see Call the REST API.