SpuntoSpunto/Docs

MCP Server

Point any MCP client — Claude Code, Cursor, your own agent — at Spunto and let it drive projects, workspaces and commands.

Spunto ships an MCP (Model Context Protocol) server at POST /mcp. It exposes the platform as a set of tools an AI agent can call directly: find a project, spawn a workspace, run commands in it, read the output. No SDK to write, no REST API to teach.

https://spunto.net/mcp

Authentication is the same as the REST API: an API key sent as a Bearer token. There is no separate OAuth flow.

1

Create an API key

From Account Settings → API keys, create a key scoped to what the agent should be able to do. projects:read + workers:read gives a read-only agent; add workers:write to let it create workspaces and workers:exec to let it run commands.

2

Add the server to your client

With Claude Code:

claude mcp add --transport http spunto https://spunto.net/mcp \
  --header "Authorization: Bearer spk_your_key"

Or, in any client that reads an mcp.json:

{
  "mcpServers": {
    "spunto": {
      "type": "http",
      "url": "https://spunto.net/mcp",
      "headers": { "Authorization": "Bearer spk_your_key" }
    }
  }
}
3

Ask for something

"List my Spunto projects", "spin up a workspace on project X and run the test suite there" — the agent picks the tools itself.

Note

The endpoint is also shown, with a copy button, in the MCP server card of Account Settings.

ToolWhat it does
searchOne search across projects, workspaces, deployments, services and nodes — the shortest path from a name to an id
list_organizationsOrganizations the token can act in
list_projects, get_projectProjects and their configuration
list_workers, get_workerWorkspaces: state, branch, public URLs
create_worker, start_worker, stop_worker, delete_workerWorkspace lifecycle
run_commandRun a shell command in a workspace — waiting for it, or in the background
get_command, list_commands, cancel_commandFollow, list and cancel those commands
get_worker_logs, get_worker_git_status, list_worker_ports, list_worker_terminalsObserve a workspace
list_nodes, list_deploymentsCompute nodes and shipped services

Two conveniences worth knowing: orgId is optional everywhere (an API key belongs to exactly one organization), and the workspace tools accept a workerId on its own — the project is looked up for you.

search / list_projects        → find the project
create_worker                 → get a sandbox
get_worker  (until "ready")   → wait for setup to finish
run_command                   → do the work
get_command                   → read the result
delete_worker                 → clean up

Anything longer than a minute — a build, a test suite, an agent run — should use run_command with background: true and then poll get_command. The command runs inside the workspace and keeps going regardless of what the client does; see Running commands.

An MCP client can do exactly what its API key could already do over REST, and nothing more. Every tool call is re-dispatched through the API's own routes with the caller's token, so the same scope and organization checks apply:

  • a key without workers:exec gets a "missing scope" error from run_command;
  • a key scoped to one organization cannot read another, even by passing orgId explicitly;
  • revoking the key stops the MCP session immediately.

Tip

Scope the key to the narrowest set the agent actually needs. It's the only thing standing between an autonomous agent and the rest of your organization.

The server is stateless Streamable HTTP: no Mcp-Session-Id, no server-initiated stream. GET /mcp and DELETE /mcp answer 405 with a JSON-RPC error explaining that — clients should just POST. Responses are plain JSON (Content-Type: application/json), so send Accept: application/json, text/event-stream and handle either.

PreviousAPI Keys