MCP Tools Reference
The 12 MCP tools exposed at POST /mcp (Streamable HTTP) and over stdio. Transport, authentication, retry semantics, and the connection shapes are covered in the MCP server guide; HTTP-equivalent semantics (timeouts, background-exec lifecycle, concurrency, size caps) in the Agent API Reference. This page is the tool catalog: every tool’s input schema, result shape, and error behavior.
Tools
| Tool | Backing call | Purpose |
|---|---|---|
execute | /agent/execute | Run code in a SandFS sandbox (sync or background). |
file_read | /agent/file (read) | Read file bytes. |
file_write | /agent/file (write) | Write text or base64 binary content. |
file_stat | /agent/file (stat) | File/directory metadata. |
file_list_dir | /agent/file (list_dir) | Directory listing with recursion. |
file_mkdir | /agent/file (mkdir) | Create a directory (parents created). |
file_remove | /agent/file (remove) | Remove a file or directory. |
file_rename | /agent/file (rename) | Rename/move. |
exec_status | /agent/exec/status | Poll a background exec’s status + log tail. |
exec_kill | /agent/exec/kill | Kill a background exec. |
list_sandfs | /agent/sandfs | List the agent’s SandFS instances. |
sandswap_guide | (server-side text) | Return the server instructions on demand (call once before heavy use if initialize did not provide them). |
All tools resolve the caller’s agent from the request’s API key and go through the same handler pipeline as the HTTP API — file and exec operations always run inside a microVM, never on the gateway host. sandfs_id is required on every per-sandfs tool; there is no auto-resolution.
tools/list is built per agent: when the agent has SandFS instances, every tool schema’s sandfs_id property carries their ids as an enum, and the execute description appends the instance list (name, id, description) plus the abort contract and the live sync-exec cap. The HTTP transport sets Cache-Control: max-age=60 on tools/list responses.
Input schemas
Argument types are JSON types; integer-valued arguments also accept a numeric string, boolean arguments must be JSON booleans, and unknown arguments are ignored. sandfs_id is a string naming one of the agent’s SandFS instances.
execute
| Argument | Type | Required | Meaning |
|---|---|---|---|
sandfs_id | string | yes | Target SandFS. |
code | string | yes | Code or command to execute. |
language | string | yes | python, shell, node, etc. |
timeout | integer | no | Sync-exec timeout in seconds; 0 = default. Values above the live sync cap are clamped and the command is killed at the cap. |
background | boolean | no | Start a background exec and return an exec_id immediately. |
lease_duration | integer | no | Background-exec hold in seconds (absolute run-time cap; polls do not extend it). 0 = the gateway’s configured background-lease cap. |
File tools
| Tool | Arguments |
|---|---|
file_read | sandfs_id (required), path (required, relative to /workspace), offset (integer, default 0), length (integer; 0 = up to the single-read cap) |
file_write | sandfs_id (required), path (required), data (string, text content), data_base64 (string; when non-empty, decoded and takes precedence over data), append (boolean; writes at the end), mode (integer; 0 = default) |
file_stat | sandfs_id (required), path (required) |
file_list_dir | sandfs_id (required), path (required), depth (integer; 0 = flat) |
file_mkdir | sandfs_id (required), path (required), mode (integer; 0 = default) |
file_remove | sandfs_id (required), path (required), recursive (boolean) |
file_rename | sandfs_id (required), path (required), new_path (required) |
A file-tool path is relative to the sandbox workspace. A leading / is re-based onto /workspace; the sandbox root itself is reachable only through execute (for example cat /README.md).
Background exec and discovery
| Tool | Arguments |
|---|---|
exec_status | sandfs_id (required), exec_id (required) |
exec_kill | sandfs_id (required), exec_id (required) |
list_sandfs | none |
sandswap_guide | none |
Results
Every successful tools/call returns content[0].text holding a JSON document (or the guide text for sandswap_guide):
| Tool | content[0].text |
|---|---|
execute | {"stdout","stderr","exit_code","exec_id","status","exec_duration_ns","sandlot_duration_ns","gateway_duration_ns"}. status is done/timed_out for sync execs and running for background ones. |
file_read | UTF-8 content: {"ok":true,"data":<text>,"is_text":true,"size":<bytes>}; binary content: {"ok":true,"data_base64":<base64>,"is_text":false,"size":<bytes>}. |
file_write | {"ok":true,"size":<bytes written>} |
file_stat | The warden’s metadata object: {"name","path","file_type","size","mode","modified_time"} (file_type is file/dir/symlink). |
file_list_dir | {"entries":[{…metadata…}, …]} |
file_mkdir, file_remove, file_rename | {"ok":true} |
exec_status | {"status","exit_code","stdout","stderr"}; status is running/done/killed/not_found/expired, and stdout/stderr are the captured log tails. |
exec_kill | {"status"} — killed, not_found (idempotent: the exec is not in the registry), or expired. |
list_sandfs | {"sandfs_list":[{"sandfs_id","name","description","template","created_at","status"?}]} — status is present only for a non-active instance (template swap or deletion in progress). |
sandswap_guide | The rendered server instructions (plain text). |
A file_stat/file_list_dir payload that is not valid JSON is returned as {"ok":true,"data":<text>} / {"ok":true,"entries":<text>} respectively (defensive fallback; the warden always emits JSON).
Tool-level errors
Tool failures are not JSON-RPC errors: the response is a tools/call result with isError: true and the message in content[0].text. Three shapes appear there:
- Structured resilience refusal — JSON with
error,error_code,retryable, andretry_after_ms(for exampleNO_AVAILABLE_SANDBOX,SHED_REBALANCE,OWNERSHIP_CONFLICT). Onretryable: true, retry the SAME request afterretry_after_ms; do not modify the request body. - Named client-class refusal — JSON with
error,error_code,http_status,retryable:false. Currently the wire-size gates:EXEC_TOO_LARGE(wrapped command over the stream message limit) andFILE_TOO_LARGE(file data or read length over the single-op cap) andFILE_PATH_TOO_LONG(apath/new_pathabove PATH_MAX−1). These are refused before anything reaches the node stream. - Plain text — validation and application failures: an unknown tool (
unknown tool: <name>), a missing required argument (sandfs_id is required,exec_id is required), invalid base64 indata_base64, or a file operation’s application error (<action>: <message>, e.g. file not found).
A load-shed refusal is special on the HTTP transport: it is written as a raw 503 with Retry-After and Connection: close (not an isError result), so the client closes the connection and re-resolves the sandfs DNS name to reach a peer that can claim it. The stdio transport, which cannot emit HTTP statuses, surfaces the same condition as a JSON-RPC -32001 error.
JSON-RPC error codes
| Code | Meaning |
|---|---|
-32700 | Parse error (malformed JSON body). |
-32600 | Method not allowed (non-POST request) / request body too large (> 50 MB). |
-32601 | Method not found. Supported methods: initialize, ping, tools/list, tools/call. |
-32602 | Invalid params (tools/call params do not decode into a tool call). |
-32001 | Missing/invalid API key (also returned when the key does not resolve on initialize/tools/list/tools/call); on HTTP, an ownership conflict for a request that already arrived redirected (X-Sandswap-Redirected: 1, the anti-loop); on stdio, the encoding of an ownership redirect (redirect to <owner-url>) or a load-shed refusal. |
The HTTP transport expresses an ownership redirect as a real 307 to the owner gateway’s /mcp and marks the response with X-Sandswap-Redirected: 1; a request that arrives carrying that header is never redirected again. Authentication is per request — the server is stateless (no Mcp-Session-Id), and an initialize call is answered (echoing the client’s protocol version, default 2025-03-26) only for compatibility with older clients.
Server instructions and the instruction file
Two channels serve the same overall Sandswap guide, rendered at serve time:
- the
instructionsfield of theinitializeresult; - the
sandswap_guidetool (for stateless clients that skip the handshake).
The built-in default is compiled into the gateway. Operators replace or extend it with -mcp-instructions-file (YAML mcp.instructions_file) pointing at a markdown file:
- Size/content bounds: at most 1 MB; a missing, unreadable, oversized, or empty-after-trim file falls back to the built-in default with a warning and never blocks startup.
- Missing file: when the gateway can write the target directory it materializes the built-in default at startup (atomic create-if-missing; an existing file is never overwritten). In production the gateway deliberately cannot write its config directory, so the deploy tooling materializes the file with its own privileges instead (bare-metal root generate-once; Kubernetes
gateway-mcp-instructionsConfigMap). - Hot reload: edits apply without a restart through the gateway’s shared config-reload watcher (fsnotify, ~200 ms debounce, parent-dir watch — so vim’s write-temp-and-rename and kubelet’s ConfigMap symlink swap both reload). The reload validates the same size/content bounds. A file that disappears mid-flight keeps the last good text; a re-save reloads normally. Changing the configured path requires a restart.
- Placeholders:
andare substituted with the live-max-exec-timeout-secand-sticky-msvalues (hot-reload aware), so the agent-visible numbers always equal the enforced ones. Custom files may omit them (served verbatim) or use them.gateway -print-mcp-instructionsprints the compiled default for inspection; it is not a required step in any flow.
Limits
| Limit | Value | Behavior |
|---|---|---|
| HTTP request body | 50 MB | JSON-RPC -32600 “request body too large” (aligned with /agent/file so a 16 MB binary write fits base64-inflated). |
| Single FileOp payload | gRPC max message size − 64 KiB (16 MiB − 64 KiB by default) | FILE_TOO_LARGE structured refusal before any stream write; split the write or page the read with offset. |
| Sync exec runtime | live -max-exec-timeout-sec (default 180 s) | A larger timeout is clamped and the command killed at the cap; use background:true for longer work. |
| Background exec runtime | live -max-background-lease-sec (default 1 h) | lease_duration is the absolute cap; status polls do not extend it. |