MCP server

This page shows you how to connect an MCP client to Impello, how it signs in, and which tools it gets. The Impello MCP server lets an agent create, inspect, run commands in and kill your team's sandboxes, and read its templates, usage and billing, without the SDK.

Connect URLs

The server speaks the Streamable HTTP transport at two URLs.

Use the read-only URL for an agent that should watch sandboxes and spend but never start, change or kill anything.

Sign in

A client signs in one of two ways: OAuth, or an Impello API key.

OAuth

Clients that support MCP OAuth (Claude Code, Claude Desktop, Cursor and Codex) find it on their own. A request without a credential gets a 401 whose WWW-Authenticate header points at /.well-known/oauth-protected-resource, and that document points at /.well-known/oauth-authorization-server. The client registers itself dynamically, so there is no client ID to create.

1. The client opens a browser and you sign in to the dashboard.
2. You pick the team the client may act for. A grant is for one team.
3. A consent screen shows the scopes the client asked for. Allow or deny.
4. The client receives a token and connects.

Each grant gets its own team API key, kept on the server and never shown to the client. To revoke a grant, open dashboard.impello.ai/keys and disconnect the client under Connected MCP clients. Its tokens stop working at once, and its key is deleted.

API key

Send an Impello API key from dashboard.impello.ai/keys as a bearer token:

Authorization: Bearer imp_...

An API key acts for its team with both scopes. See API keys.

Configure your client

# OAuth: the first tool call opens the browser to sign in.
claude mcp add --transport http impello https://dashboard.impello.ai/api/mcp

# API key
claude mcp add --transport http impello https://dashboard.impello.ai/api/mcp \
  --header "Authorization: Bearer imp_..."

For the read-only server, use https://dashboard.impello.ai/api/mcp/readonly in any of these.

Tools

Every tool declares its annotations (readOnlyHint, destructiveHint, idempotentHint), so a client can ask before a write and warn before a destructive call.

Read tools

All read tools need mcp:read, and all are read-only and idempotent.

Write tools

Write tools need mcp:write, and are only on the full URL.

read_file and write_file handle text only, up to 1 MiB. A binary file comes back as a VALIDATION error whose suggestion says what to do instead.

Build a template

build_template returns as soon as the build starts. Poll get_build_status until it is ready, read get_build_logs if it ends in error, then start a sandbox from the name:

{ "name": "build_template", "arguments": {
  "name": "jq-box",
  "fromTemplate": "base",
  "steps": [
    { "type": "USER", "user": "root" },
    { "type": "RUN", "command": "apt-get update && apt-get install -y jq" }
  ]
} }

{ "name": "get_build_status", "arguments": { "templateId": "...", "buildId": "..." } }

{ "name": "create_sandbox", "arguments": { "template": "jq-box" } }

A step is { "type": "RUN", "command", "user"? }, { "type": "ENV", "key", "value" }, { "type": "WORKDIR", "path" } or { "type": "USER", "user" }. COPY is not supported here, because it needs a file upload: write the file in a RUN step with a heredoc, or write_file into a sandbox and snapshot_sandbox it.

Results

Every tool declares an outputSchema. A result carries structuredContent that matches it, plus a one-line text summary for clients that only show text.

Pagination

Every list tool takes cursor and limit, both optional, and returns items and nextCursor. limit is 1 to 100 and defaults to 20; get_sandbox_logs allows up to 1000. nextCursor is null on the last page.

{ "items": [], "nextCursor": "..." }

A cursor is opaque: pass it back as it came. It is only valid with the same filters it was issued for. Send it with different filters and the call fails with INVALID_CURSOR; call again without a cursor to start from the first page.

Errors

A tool error comes back with isError: true and one text block holding a JSON object with code, message and suggestion. It carries no structuredContent, so it never fails a client's outputSchema check. The suggestion is written for the agent to act on.

{
  "code": "NOT_FOUND",
  "message": "...",
  "suggestion": "Check the id; list the resources first to see which exist."
}

Limits

Each team gets 120 tool calls per minute. A call beyond that fails with RATE_LIMITED. Plan limits and credit apply as for any other call; see Limits and pricing.

Every call is logged with the tool, the team, its duration and its result code.

Next: Templates.