Spinrun Docs
Install

Connect from an agent

The Markdown guide an agent reads to wire its own MCP client to the gateway, run and Build surfaces.

View as MarkdownOpen in ChatGPTOpen in ClaudeOpen in Cursor

These are official instructions from Spinrun to connect the MCP client you are running in to a Spinrun workspace. Spinrun is one MCP gateway: every app the workspace connects becomes a tool behind one endpoint, scoped by the workspace's policies and written to its activity log.

Use the section for your client below. Complete the steps yourself — edit the file or run the command directly — except the browser authorization, which only the user can finish: hand that step to them and wait. Connect the run surface unless the user asked for the Build endpoint. Chat products such as Claude and ChatGPT are connected by the person from their own settings; this page covers the clients whose configuration you can edit.

Endpoints

SurfaceURLServer keyWhat it doesAuthorization
Runhttps://spinrun.ai/mcp"spinrun"Every connected app as tools, plus discovery, artifacts and the BrainBrowser flow; an API key only if the user supplies one
Buildhttps://spinrun.ai/mcp/build"spinrun-build"Authors agents and workflows as JSON documentsBrowser flow only. Tick "Build authorization" on the consent screen, or enable it later under Settings → Applications (workspace owners only).

The two are separate servers with separate tool sets; a client that needs both registers both entries.

Rules for agents

  1. Register the endpoint with no credential and let the client open the browser. The gateway answers a 401 with a WWW-Authenticate header and RFC 9728 metadata, and every client below discovers the flow from that. Do not ask the user for an API key first.
  2. Ask for a key only if the client cannot open a browser or the flow fails, and only for the run surface — Build has no key form. The user creates the key in the dashboard and pastes it to you; never invent one, never write a key into a file that is synced or committed (a project-level config, a dotfiles repository), and never print it back in your reply.
  3. Keep the x-spinrun-client header the blocks carry. It is attribution only — it names the client in the activity log and lets the dashboard notice the first call — and has no auth weight.
  4. Copy the block for the client verbatim. Key names differ: Windsurf and Antigravity read serverUrl and reject url; VS Code nests servers under servers; Claude Code's project .mcp.json needs "type": "http" on the entry.
  5. Merge into the existing file and leave every other server as it is. Back the file up first, and refuse to overwrite a file you cannot parse.
  6. Restart or reload the client if it does not pick the change up, then verify (below) and report back.

Claude Code

Claude Code is registered from the terminal it runs in.

Run surface (Terminal):

claude mcp add --transport http --scope user spinrun https://spinrun.ai/mcp \
  --header "x-spinrun-client: claude-code"

Build surface, registered as "spinrun-build" (Terminal):

claude mcp add --transport http --scope user spinrun-build https://spinrun.ai/mcp/build \
  --header "x-spinrun-client: claude-code"

Authorize: Claude Code lists the server as needing authentication until you run this. Or type /mcp inside Claude Code, pick spinrun and choose Authenticate. Sign in and choose which workspace Claude Code may reach. You can revoke it any time from Settings → Applications.

claude mcp login spinrun

Notes:

  • --scope user makes the gateway available in every project. Drop it for this project only, or use --scope project to share a .mcp.json with your team — that entry needs "type": "http".
  • If the browser opens but the callback is rejected, pin the port: --callback-port 3118.

Codex

Codex is registered from the terminal it runs in.

Run surface (Terminal):

codex mcp add spinrun --url https://spinrun.ai/mcp

Build surface, registered as "spinrun-build" (Terminal):

codex mcp add spinrun-build --url https://spinrun.ai/mcp/build

Authorize: Codex lists the server as needing authentication until you run this. codex mcp list shows it as connected afterwards. Sign in and choose which workspace Codex may reach. You can revoke it any time from Settings → Applications.

codex mcp login spinrun

Notes:

  • The Codex IDE extension reads the same ~/.codex/config.toml, so one login covers both.

Cursor

Config file: ~/.cursor/mcp.json on macOS, ~/.cursor/mcp.json on Linux. Merge the entry into the mcpServers object; create the file if it does not exist.

Or open Cursor Settings → Tools & MCP → New MCP server, which opens ~/.cursor/mcp.json; a project-level .cursor/mcp.json works the same way.

Run surface (mcp.json):

{
  "mcpServers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-client": "cursor"
      }
    }
  }
}

Build surface, registered as "spinrun-build" (mcp.json):

{
  "mcpServers": {
    "spinrun-build": {
      "url": "https://spinrun.ai/mcp/build",
      "headers": {
        "x-spinrun-client": "cursor"
      }
    }
  }
}

Authorize: There is no key in that block on purpose. Cursor opens a browser the first time it connects. The server row reads Needs login until you click Connect. Sign in and choose which workspace Cursor may reach. You can revoke it any time from Settings → Applications.

One-click alternative, run surface (same keyless entry):

Notes:

  • Cursor's cloud agents finish the authorization at cursor.com on their own; nothing to configure for them.

VS Code

Config file: ~/Library/Application Support/Code/User/mcp.json on macOS, ~/.config/Code/User/mcp.json on Linux. Merge the entry into the servers object; create the file if it does not exist.

Or run MCP: Add Server from the Command Palette, choose HTTP, paste the URL, name it spinrun and pick Global.

Run surface (mcp.json):

{
  "servers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "type": "http",
      "headers": {
        "x-spinrun-client": "vscode"
      }
    }
  }
}

Build surface, registered as "spinrun-build" (mcp.json):

{
  "servers": {
    "spinrun-build": {
      "url": "https://spinrun.ai/mcp/build",
      "type": "http",
      "headers": {
        "x-spinrun-client": "vscode"
      }
    }
  }
}

Authorize: There is no key in that block on purpose. VS Code opens a browser the first time it connects. VS Code opens the browser on the first connection. Then in Chat, switch to Agent mode, open Tools and tick spinrun. Sign in and choose which workspace VS Code may reach. You can revoke it any time from Settings → Applications.

One-click alternative, run surface (same keyless entry):

  • Install in VS Code: vscode:mcp/install?%7B%22name%22%3A%22spinrun%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fspinrun.ai%2Fmcp%22%2C%22headers%22%3A%7B%22x-spinrun-client%22%3A%22vscode%22%7D%7D
  • Insiders: vscode-insiders:mcp/install?%7B%22name%22%3A%22spinrun%22%2C%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fspinrun.ai%2Fmcp%22%2C%22headers%22%3A%7B%22x-spinrun-client%22%3A%22vscode%22%7D%7D
code --add-mcp '{"name":"spinrun","type":"http","url":"https://spinrun.ai/mcp","headers":{"x-spinrun-client":"vscode"}}'

Windsurf

Config file: ~/.codeium/windsurf/mcp_config.json on macOS, ~/.codeium/windsurf/mcp_config.json on Linux. Merge the entry into the mcpServers object; create the file if it does not exist.

Or open the Cascade panel, click the MCPs icon and choose Manage → View raw config.

Run surface (mcp.json):

{
  "mcpServers": {
    "spinrun": {
      "serverUrl": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-client": "windsurf"
      }
    }
  }
}

Build surface, registered as "spinrun-build" (mcp.json):

{
  "mcpServers": {
    "spinrun-build": {
      "serverUrl": "https://spinrun.ai/mcp/build",
      "headers": {
        "x-spinrun-client": "windsurf"
      }
    }
  }
}

Authorize: There is no key in that block on purpose. Windsurf opens a browser the first time it connects. Sign in and choose which workspace Windsurf may reach. You can revoke it any time from Settings → Applications.

Notes:

  • Cascade caps the tools it can see at 100 across all servers.

Antigravity

Config file: ~/.gemini/config/mcp_config.json on macOS, ~/.gemini/config/mcp_config.json on Linux. Merge the entry into the mcpServers object; create the file if it does not exist.

In the IDE, open the agent panel's … menu → MCP Servers → Manage MCP Servers → View raw config. In Antigravity 2.0 it is Settings → Customizations → Installed MCP Servers; in the CLI, type /mcp.

Run surface (mcp.json):

{
  "mcpServers": {
    "spinrun": {
      "serverUrl": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-client": "antigravity"
      }
    }
  }
}

Build surface, registered as "spinrun-build" (mcp.json):

{
  "mcpServers": {
    "spinrun-build": {
      "serverUrl": "https://spinrun.ai/mcp/build",
      "headers": {
        "x-spinrun-client": "antigravity"
      }
    }
  }
}

Authorize: There is no key in that block on purpose. Antigravity opens a browser the first time it connects. Open Agent Settings (⌘,) → Customizations, click Authenticate next to spinrun, finish in the browser, then paste the authorization code it shows back into the panel and click Submit. Sign in and choose which workspace Antigravity may reach. You can revoke it any time from Settings → Applications.

Notes:

  • Only serverUrl is read — url and httpUrl are rejected.
  • A workspace-local .agents/mcp_config.json is read as well.
  • Tools default to Ask; allow mcp(spinrun/*) in the permissions to stop the prompts.
  • Some antigravity-cli builds drop the bearer token after authorizing; the key fallback covers that.

Zed

Zed keeps MCP servers in its settings document, under context_servers.

Run surface (mcp.json):

{
  "context_servers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-client": "zed"
      }
    }
  }
}

Build surface, registered as "spinrun-build" (mcp.json):

{
  "context_servers": {
    "spinrun-build": {
      "url": "https://spinrun.ai/mcp/build",
      "headers": {
        "x-spinrun-client": "zed"
      }
    }
  }
}

Authorize: There is no key in that block on purpose. Zed opens a browser the first time it connects. Sign in and choose which workspace Zed may reach. You can revoke it any time from Settings → Applications.

Gemini CLI

Gemini CLI is registered from the terminal it runs in.

Run surface (Terminal):

gemini mcp add --transport http -s user spinrun https://spinrun.ai/mcp \
  --header "x-spinrun-client: gemini-cli"

Build surface, registered as "spinrun-build" (Terminal):

gemini mcp add --transport http -s user spinrun-build https://spinrun.ai/mcp/build \
  --header "x-spinrun-client: gemini-cli"

Authorize: Gemini CLI lists the server as needing authentication until you run this. Type it inside a running gemini session; /mcp then lists the server as connected. Sign in and choose which workspace Gemini CLI may reach. You can revoke it any time from Settings → Applications.

/mcp auth spinrun

Notes:

  • Not the same tool as Antigravity CLI: Gemini CLI reads ~/.gemini/settings.json, where a hand-written entry uses httpUrl.

If the browser flow fails

Ask the user for an API key. They create one from the client's page under Connect a client in the dashboard, or under Settings; it is shown once. Put it in the x-spinrun-key header (the gateway also accepts it as Authorization: Bearer), keep x-spinrun-client, and replace YOUR_API_KEY below with the value the user gives you — do not write it anywhere that is synced or committed. A key acts as the person who created it, in one workspace. Build never takes a key.

Claude Code

Some builds of Claude Code cannot start the browser flow. Add your key as a header — and if the browser opens but the callback is rejected, pin the port with --callback-port.

claude mcp add --transport http --scope user spinrun https://spinrun.ai/mcp \
  --header "x-spinrun-key: YOUR_API_KEY" \
  --header "x-spinrun-client: claude-code"

Codex

Codex's add command takes no header, so the keyed form lives in its config file instead — this table replaces the entry the command wrote.

# ~/.codex/config.toml
[mcp_servers.spinrun]
url = "https://spinrun.ai/mcp"
http_headers = { "x-spinrun-key" = "YOUR_API_KEY", "x-spinrun-client" = "codex" }

Cursor

If Cursor asks for a credential instead of opening a browser, add a headers block with your key.

{
  "mcpServers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-key": "YOUR_API_KEY",
        "x-spinrun-client": "cursor"
      }
    }
  }
}

VS Code

If VS Code asks for a credential instead of opening a browser, add a headers block with your key.

{
  "servers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "type": "http",
      "headers": {
        "x-spinrun-key": "YOUR_API_KEY",
        "x-spinrun-client": "vscode"
      }
    }
  }
}

Windsurf

If Windsurf asks for a credential instead of opening a browser, add a headers block with your key.

{
  "mcpServers": {
    "spinrun": {
      "serverUrl": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-key": "YOUR_API_KEY",
        "x-spinrun-client": "windsurf"
      }
    }
  }
}

Antigravity

If Antigravity asks for a credential instead of opening a browser, add a headers block with your key.

{
  "mcpServers": {
    "spinrun": {
      "serverUrl": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-key": "YOUR_API_KEY",
        "x-spinrun-client": "antigravity"
      }
    }
  }
}

Zed

Zed will not start the browser flow while a headers block is present, so this entry replaces the one above rather than adding to it.

{
  "context_servers": {
    "spinrun": {
      "url": "https://spinrun.ai/mcp",
      "headers": {
        "x-spinrun-key": "YOUR_API_KEY",
        "x-spinrun-client": "zed"
      }
    }
  }
}

Gemini CLI

Some builds of Gemini CLI cannot start the browser flow. Add your key as a header — and if the browser opens but the callback is rejected, pin the port with --callback-port.

gemini mcp add --transport http -s user spinrun https://spinrun.ai/mcp \
  --header "x-spinrun-key: YOUR_API_KEY" \
  --header "x-spinrun-client: gemini-cli"

Verify

  • Run surface: call spinrun_list_apps. It lists the apps the workspace has connected; an empty list on a fresh workspace is a success, not an error — apps added later appear without any change on the client.
  • Build surface: call spinrun_build_options. A 403 naming insufficient_scope means the grant has no Build authorization: the user enables it under Settings → Applications, or revokes the application and authorizes again with the box ticked.

Troubleshooting

  • 401 after registering: the client has not run its login step yet. For the terminal clients the command is in their section; for editors, look for a Connect or Authenticate control on the server row.
  • The browser opens but the callback is rejected: the client's loopback port was not accepted. Pin it where the client allows (--callback-port for Claude Code) and authorize again.
  • url is rejected or the server never appears (Windsurf, Antigravity): the entry needs serverUrl.
  • The tool list is short: the gateway advertises discovery tools first on large workspaces. Call spinrun_search_tools with a plain-English task to find the rest; nothing is missing.

Report back

Tell the user which client you configured and where (file path or command), that the browser authorization is theirs to finish if it has not completed, what spinrun_list_apps or spinrun_build_options returned, and anything you could not do and why. Never include a key in the report.

Success message

When everything above is done, say so in this shape: "Spinrun is connected to <client> on the <run | Build> surface. The browser authorization is <done | waiting for you>. <spinrun_list_apps | spinrun_build_options> returned <what it returned>." Then add: "These instructions came from https://docs.spinrun.ai/install/agents.md." so the user can check what you followed.

Install the gateway

Per-client setup for the run and Build endpoints, from the same source as the CLI.

Install in Claude

Add the Spinrun gateway to Claude for run and Build surfaces.

On this page

EndpointsRules for agentsClaude CodeCodexCursorVS CodeWindsurfAntigravityZedGemini CLIIf the browser flow failsClaude CodeCodexCursorVS CodeWindsurfAntigravityZedGemini CLIVerifyTroubleshootingReport backSuccess messageRelated