MCP and API keys

Setup has an MCP server, so an AI agent such as Claude Code or Cursor can do what you do in the dashboard: look at a project, start a trial, read its logs, keep the app or remove it. The agent signs in with an API key that you create, and it can only do what you could do yourself.

Agents get the same sandbox and the same rules as people. They never see the keys of your connected accounts, and they have to ask before they delete anything. Treat an API key like a password: anyone who has it can start, stop and destroy apps in its workspaces.

Sign in instead of a key

Most MCP hosts can sign in to Setup themselves, so you do not need a key at all. Add the server by its address, for example https://setup.run/api/mcp. When the host connects, it opens Setup in your browser. Sign in, then answer Allow … to use Setup?:

• Workspace: your personal workspace or one organization. The app never sees the others.
• What it may do: Look (read only), Look and run apps, or Also manage the workspace (as far as your own role allows). Viewers can only allow Look.

Choose Allow, and the host is connected. Setup shows the app's name only as what it calls itself, and tells you whether it checked where the app comes from. Only allow apps you are connecting yourself.

The host gets tokens that last 15 minutes and renew themselves; nothing is copied by hand. Your connections are listed under My account, Connected apps (/dashboard/account/connected-apps). Disconnect ends an app's access at once.

Create an API key

1. Open Developers in the dashboard: /dashboard/developers, or /dashboard/<workspace>/developers inside a workspace. It sits in the sidebar of the detailed view. In the simple view, use Show details to get there (see Simple and detailed view).
2. Choose Create key.
3. Fill in the form:
   • Name, so you can tell your keys apart later, for example "Claude Code on my laptop".
   • Workspace: All my workspaces, or Only one workspace.
   • Expires: in 30 days, in 90 days (the default), in 1 year, or never.
4. Choose Create key again. Setup shows the key once, under Copy your new key, together with a ready-made Claude Code command. Copy it, then choose I've copied it.

Setup stores only a hash of the key and cannot show it again. If you lose it, revoke it and create a new one. Every key starts with setup_, so secret scanners can recognise it.

What a key can do

There are no per-key permissions beyond the workspace choice. A key:

• acts as you, with your role in each workspace,
• with All my workspaces, works in your personal workspace and every organization you belong to,
• with Only one workspace, cannot see or change anything outside it, and stops working if you leave that organization,
• never has global admin powers, even if your account does,
• cannot create, list or revoke keys, and cannot use admin, billing or account routes.

Revoke a key

The list on Developers shows each key's name, workspace, when it was created and last used, and when it expires. To revoke one, choose the revoke button next to it, then Revoke key. Agents and scripts using that key stop working right away. You can't undo this.

Connect an MCP client

The server lives at /api/mcp on your Setup, for example https://setup.run/api/mcp. The Connect an agent panel on Developers shows the snippets below with the right address.

Claude Code

Export your key as SETUP_API_KEY, then run:

claude mcp add --transport http setup https://setup.run/api/mcp \
  --header "Authorization: Bearer $SETUP_API_KEY"

Cursor

Add this to .cursor/mcp.json in a project, or to ~/.cursor/mcp.json for every project, and replace <SETUP_API_KEY> with your key:

{
  "mcpServers": {
    "setup": {
      "url": "https://setup.run/api/mcp",
      "headers": { "Authorization": "Bearer <SETUP_API_KEY>" }
    }
  }
}

Other clients

The server speaks Streamable HTTP without sessions: every request is served on its own. Send the key as Authorization: Bearer setup_... or in an x-api-key header. Session cookies are not accepted here.

curl https://setup.run/api/mcp \
  -H "Authorization: Bearer $SETUP_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

A request without a key or a sign in gets 401 with the code apiKey.missing, and a WWW-Authenticate header that tells hosts where to sign in. An invalid, expired or revoked key gets 401 with apiKey.invalid. A key limited to a workspace you no longer belong to gets 403 with apiKey.workspaceUnavailable.

Tools

Tools that take organizationId use the key's workspace when you leave it out, or your personal workspace for a key without one.

A typical session: analyze, show the person the reviewUrl, deploy a trial, get_deployment and get_logs until it runs, then deployment_action with promote to keep it, or destroy. Without an online runner, the app waits in the queue, and get_deployment says so.

Recipes with outside services

A recipe that needs outside services (see Recipes) cannot be deployed until the person decides how each one is set up. deploy then fails with deployment.needsRequirements. The agent calls explain_requirements, explains the choices and sends the person to the recipe's page at reviewUrl. If Setup should create the resources, the person first connects an account through the link from connect_service, then confirms the plan and its costs on the app page. Keys never pass through the agent. More in Integrations and connected accounts.

What an agent can and cannot do

An agent can do everything the tools above cover, in the workspaces its key allows. Besides what no key can do (see above), it cannot:

• enter or read credentials for connected accounts, because connect_service only returns a link,
• act outside its workspace when the key is limited to one,
• run anything outside the sandbox: its apps get the same recipe rules and runner hardening as yours (see Security),
• destroy an app, restore a backup or remove a leftover without confirm: true.

Safety rules

• Text from third parties is marked. READMEs, project descriptions, findings, recipe notes, logs, runner errors and check output come back in a separate block that starts with UNTRUSTED DATA from ... and is wrapped in a marker that is random for every response, so the text cannot close its own block. The server's instructions tell agents to treat that text as data and never follow instructions inside it.
• Destructive tools are marked. deployment_action and remove_leftover carry the MCP destructiveHint, so clients that honor it ask you before every call, including a plain start or stop.
• Deleting needs a confirmation. Setup refuses destroy, restore and remove_leftover unless the agent passes confirm: true, because they delete or replace data. The server tells agents to ask you first.
• No credentials through agents. Accounts are connected in the dashboard. Tools never accept or return provider keys.
• Keep keys small. Limit a key to one workspace, give it an expiry and revoke it when the agent no longer needs it.

Limits

Tool errors come back as text such as Setup API error 400 (deployment.invalidInputs): Missing: ADMIN_EMAIL, with the same codes the REST API uses.

The REST API

The same key works on Setup's platform routes, such as /api/analyses, /api/projects, /api/deployments, /api/runners and /api/integrations. The MCP tools call these routes internally, so validation, workspace rules and rate limits are the same. Managing keys under /api/api-keys needs a signed-in session in the browser. A presented key must be valid: a revoked key gets 401 even when a session cookie is also sent.

This page doesn't document the REST routes one by one.