> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zode.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Give Claude Code, Codex, Cursor or any MCP client tools to make sandboxes and work in them with zode mcp.

`zode mcp` runs an MCP server on stdio. Your agent starts it as a subprocess and gets nine tools for sandboxes. It acts with your `zode` sign-in, in your workspace, with your plan's limits.

## Sign in first

The server reads the same credentials as the CLI: the API key saved by [`zode login`](https://docs.zode.dev/cli/overview#sign-in), or the API key in `ZODE_TOKEN` when set. With neither, it exits with `not signed in: run zode login first, then start your agent`.

## Add it to your agent

> [tab] Claude Code
>
> ```bash theme={null}
> claude mcp add zode -- zode mcp
> ```

> [tab] Codex
>
> ```bash theme={null}
> codex mcp add zode -- zode mcp
> ```

> [tab] Cursor
>
> Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:
>
> ```json theme={null}
> {
>   "mcpServers": {
>     "zode": {
>       "command": "zode",
>       "args": ["mcp"]
>     }
>   }
> }
> ```

To use an API key instead of your sign-in, for example on a shared machine, give the server `ZODE_TOKEN` in its environment. In the Cursor config, add `"env": { "ZODE_TOKEN": "zode_tok_..." }` next to `args`.

The server also sends the agent short instructions: work happens in `/workspace`, refer to sandboxes by name, fork to try two approaches, delete when done.

## Agent skill

A skill teaches Claude Code, Codex, Cursor and other agents when and how to use Zode: making sandboxes, forking for parallel work, snapshots, images and secrets. It is built from these docs, so it stays current.

```bash theme={null}
npx skills add https://docs.zode.dev
```

## Tools

Every `sandbox` parameter takes a sandbox name or `sbx_` id. Tools that return a sandbox return `name`, `id`, `status`, `size` and `region`.

| Tool | Parameters | Does |
| - | - | - |
| `sandbox_list` | none | Lists the workspace's sandboxes. |
| `sandbox_create` | `name`, `size`, `image`, `browser`, `desktop`, `git_repo`, `git_branch`, `pr_number` (all optional) | Makes a sandbox. See [sandbox\_create](#sandbox_create). Billed while running. |
| `sandbox_exec` | `sandbox`, `command`, `cwd`, `stdin`, `timeout_seconds`, `env` | Runs a shell command and returns its result. |
| `sandbox_read_file` | `sandbox`, `path` | Reads a text file, up to 256 KB. |
| `sandbox_write_file` | `sandbox`, `path`, `content` | Writes a text file, creating parent directories. |
| `sandbox_fork` | `sandbox`, `name` (optional) | Copies a sandbox: running processes, memory and disk. |
| `sandbox_stop` | `sandbox` | Hibernates it: memory and disk kept, compute billing stops. |
| `sandbox_start` | `sandbox` | Wakes a stopped sandbox where it left off. |
| `sandbox_delete` | `sandbox` | Deletes it and its disk. Cannot be undone. |

### sandbox\_create

| Parameter | Type | Notes |
| - | - | - |
| `name` | string | Lowercase letters, digits and dashes. Picked for you when empty. |
| `size` | string | `small`, `default`, `large` or `xlarge`. Left out, you get `small` (2 vCPU, 4 GB); the size named `default` is not the default. |
| `image` | string | A ready custom image of the workspace, by name or `img_` id. It sets the size, so leave `size` empty. |
| `browser` | boolean | Run Chrome, driven over CDP. Left out: the workspace default. |
| `desktop` | boolean | Run a Linux desktop. Left out: the workspace default. Not on the Free plan. |
| `git_repo`, `git_branch`, `pr_number` | string, string, integer | Labels for cost breakdowns. Nothing is cloned; use `sandbox_exec` for that. |

### sandbox\_exec

| Parameter | Type | Notes |
| - | - | - |
| `sandbox` | string | Required. |
| `command` | string | Required. Runs with `bash -lc` as root. |
| `cwd` | string | Working directory. Default `/workspace`. |
| `stdin` | string | Text fed to the command's stdin. stdin is closed after it. |
| `timeout_seconds` | integer | Kill the command after this long. Default 600, max 3600. |
| `env` | object | Extra variables for this command, such as API keys. |

It returns `exit_code`, `stdout`, `stderr`, `duration_ms`, and `timed_out` or `truncated` when they apply. Each stream is capped at 256 KB; past that, output is dropped and `truncated` is `true`. A timed-out command returns `exit_code` `-1`. For a long-running server, start it in the background (`nohup ... &`).

### Paths

`sandbox_read_file` and `sandbox_write_file` take an absolute path, or a path relative to `/workspace`. `sandbox_read_file` returns the file in `stdout`, with the same fields as `sandbox_exec`.

## Limits

* `sandbox_create` has no environment or spend-cap input. For those, use [`zode new`](https://docs.zode.dev/cli/sandboxes) with `--environment` or `--max-cost` and give the agent the name.
* The tools need a running sandbox for exec and files. A stopped one gives `demo is stopped; start it first`.
* Plan limits apply as in the CLI: on Free, at most 2 sandboxes run at once, and a workspace with no card and no credit cannot make sandboxes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.