MCP server

moatbox serves a remote MCP server. An agent on your laptop or in your CI can use it to drive spaces: start agent runs, follow them, run commands, read and write files, and save or restore snapshots.

https://app.moatbox.dev/api/mcp

The transport is Streamable HTTP. Each JSON-RPC message is one POST.

Authentication

The server accepts an API key and nothing else:

Authorization: Bearer mbx_…

A dashboard browser session does not work here. A request with no key, or a key moatbox does not know, gets 401 with WWW-Authenticate: Bearer realm="moatbox". An expired key gets 401 with code api_key_expired.

Create the key in Settings → API keys (see API keys). Give it only what the agent needs:

• read-only lets the agent look and change nothing. Reading a space or its files still wakes the space when it sleeps.
• operate adds runs, commands and file writes in existing spaces.
• ci adds creating, waking and forking spaces.

Limit the key to the spaces or environments the agent should touch. A space key (MOATBOX_SPACE_KEY inside a space) also works and reaches only its own space.

Tools

tools/list returns only the tools your key may call. A tool whose route needs an action the key lacks stays hidden. A space key, for example, never sees create_space.

Each tool's input schema sets additionalProperties: false. Tools that take a space name it with space, the slug that list_spaces shows. File paths are absolute and sit under /workspace or /home/agent, with no .. in them.

The server marks tools with MCP annotations so your client can decide what to confirm:

• readOnlyHint: true: list_spaces, get_space, list_runs, get_run, get_run_timeline, get_command, list_files, read_file, list_pending_approvals, list_snapshots.
• destructiveHint: true: run_command, write_file, restore_snapshot.

The key's creator still needs the right team role. Creating and forking spaces, and saving snapshots, need an owner or admin behind the key.

Results

A tool call returns MCP text content. moatbox calls its own HTTP API for each tool and passes back the response body:

{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [{"type": "text", "text": "{\"spaces\":[…]}"}],
    "isError": false,
    "structuredContent": {"spaces": […]}
  }
}

• If the API succeeds with a JSON object, the result also carries the whole object as structuredContent.
• When the API answers with status 400 or above, isError is true and the text starts with the status, for example HTTP 403: {"error":"this API key may not run","code":"api_key_action_forbidden"}.
• A missing required argument returns isError: true with <name> is required. An argument the tool does not define returns unknown argument <name>.
• An unknown tool name returns JSON-RPC error -32602.

Each call goes through the same checks as the HTTP API. A call that changes something adds an api_key.write entry to the team's audit log, like any other write the key makes.

Limits

The routes behind most tools cap their own body at 64 KiB. write_file uses the streaming upload route, so its content can use most of the 8 MiB. The whole JSON-RPC request counts toward that limit, including the envelope and JSON escaping.

Protocol

initialize answers with the version the client asked for when it is one of the three initialize versions, and 2025-11-25 otherwise. After that, send MCP-Protocol-Version on each request. Without it moatbox assumes 2025-03-26. An unsupported version gets 400 with JSON-RPC error -32022 and data.supported listing the versions moatbox accepts.

On 2026-07-28, each request carries its version in params._meta["io.modelcontextprotocol/protocolVersion"]. moatbox then checks the headers against the body: MCP-Protocol-Version must equal that version, Mcp-Method must equal the method, and on tools/call Mcp-Name must equal the tool name (plain or in =?base64?…?= form). A mismatch gets 400 with JSON-RPC error -32020.

moatbox refuses requests that a browser sends from another site (403).

What the server leaves out

The MCP server covers day-to-day work in spaces. These stay in the HTTP API or the dashboard:

• deleting spaces,
• approving or denying held actions (a person decides in the dashboard; see Approvals),
• API keys, webhooks, environments and team settings,
• SSH, the desktop and tailnet access,
• copying files between spaces, deleting snapshots, resets.

Client setup

Keep the key out of config files: put it in an environment variable, here MOATBOX_API_KEY, and reference the variable.

export MOATBOX_API_KEY=mbx_…

Claude Code

Add the server from the command line:

claude mcp add --transport http moatbox https://app.moatbox.dev/api/mcp \
  --header "Authorization: Bearer $MOATBOX_API_KEY"

Your shell expands the variable, so the key itself goes into the config. The default local scope keeps that config to you and the current project. To share the server through the project's .mcp.json without the key, write the file by hand; Claude Code expands ${VAR} in url and headers:

{
  "mcpServers": {
    "moatbox": {
      "type": "http",
      "url": "https://app.moatbox.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${MOATBOX_API_KEY}"
      }
    }
  }
}

Codex

Add the server to ~/.codex/config.toml, or to .codex/config.toml in a trusted project:

[mcp_servers.moatbox]
url = "https://app.moatbox.dev/api/mcp"
bearer_token_env_var = "MOATBOX_API_KEY"
default_tools_approval_mode = "writes"

bearer_token_env_var names the variable Codex sends as the bearer token. With writes, Codex asks you before it calls any tool that moatbox does not mark read-only.

Codex cannot ask you when it runs with approval_policy = "never", as in an unattended job, so it refuses the tools moatbox marks destructive: run_command, write_file and restore_snapshot. To let it call them, set default_tools_approval_mode = "approve" for the server. Codex then calls every moatbox tool without asking, so give that server a key with only the actions the job needs. To approve a single tool, set tools.<tool>.approval_mode instead.

Cursor

Add the server to ~/.cursor/mcp.json, or .cursor/mcp.json in a project:

{
  "mcpServers": {
    "moatbox": {
      "url": "https://app.moatbox.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MOATBOX_API_KEY}"
      }
    }
  }
}

Cursor reads ${env:MOATBOX_API_KEY} from your environment.

Any other client

Point a Streamable HTTP client at https://app.moatbox.dev/api/mcp with the Authorization header. You can also call the server with curl:

curl -X POST https://app.moatbox.dev/api/mcp \
  -H "Authorization: Bearer $MOATBOX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "run_command", "arguments": {"space": "<space>", "command": "git status"}}}'

The initialize response includes server instructions that tell the agent where to start: list_spaces first, start_run to hand over a task, get_run and get_run_timeline to follow it.