# MCP server

> Give Claude Code, Codex or Cursor its own Linux sandboxes over MCP. No API key needed; your agent signs you up with your email and a 6-digit code.

URL: https://prized.dev/docs/sandboxes-mcp
Updated: 2026-11-11

`@prized/sandbox-mcp` is an [MCP](https://modelcontextprotocol.io) server for [sandboxes](https://prized.dev/docs/sandboxes). Install it once, and your agent can run code, move files and fork machines in every session.

## 1. Install [#1-install]

**Claude Code**

```bash
claude mcp add --scope user prized-sandbox -- npx -y @prized/sandbox-mcp
```

**Codex**

```bash
codex mcp add prized-sandbox -- npx -y @prized/sandbox-mcp
```

**Cursor**

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "prized-sandbox": {
      "command": "npx",
      "args": ["-y", "@prized/sandbox-mcp"],
      "env": { "PRIZED_MCP_LOCAL_DIRS": "${workspaceFolder}" }
    }
  }
}
```

Restart the agent after installing. It needs Node.js 20 or later. Any other MCP client runs `npx -y @prized/sandbox-mcp` over stdio.

## 2. Ask your agent [#2-ask-your-agent]

```text title="Prompt"
Sign me up for Prized, then run my tests in a sandbox.
```

* **New to Prized:** the agent signs you up with your email address. Prized emails you a 6-digit code; give it to the agent. Your new account comes with the [free credit](https://prized.dev/docs/billing#free-credit), no card ([Agent sign-in](https://prized.dev/docs/agent-sign-in)).
* **Already on Prized:** run `prized login` once ([install the CLI](https://prized.dev/docs/quickstart#2-install-the-cli) first if you need it), and the server uses that login. Or give it a key as `PRIZED_API_KEY` ([Configuration](#configuration)).

## What your agent can do [#what-your-agent-can-do]

| Tool | What it does |
| --- | --- |
| `sign_up`, `verify` | Make you a new account from your email and the emailed code. Offered only while the server has no key. |
| `create_sandbox` | Start a sandbox from `prized-base-v1` (Python, Node.js, git) or `prized-agent-v1` (adds Claude Code and Codex). |
| `run_command` | Run a shell command; returns the exit code, stdout and stderr. |
| `write_file`, `read_file` | Write or read a file in the sandbox. |
| `upload`, `download` | Copy files between your project and the sandbox. A directory in a git repository sends what git would commit, so `.env` and `node_modules` stay home. `download` never writes into `.git`, not even through a symbolic link, and refuses files that make a tool on your machine run commands (such as `.claude/settings.json`, `.husky/` or `.envrc`) unless you set `PRIZED_MCP_ALLOW_CONFIG_FILES=1` and the call sets `allow_config_files`. It says when a downloaded `package.json` changes the scripts. Neither tool ever moves SSH keys, the `prized` CLI's login, or saved credentials such as `.netrc`, and `upload` leaves behind a file in which it finds the server's own key as plain text (UTF-8 or UTF-16) or in base64 of either (line-wrapped or not); it does not look inside compressed files or for the key in hex. |
| `fork_sandbox` | Copy a sandbox, memory and running processes included, into live copies to try things in parallel. |
| `pause_sandbox`, `resume_sandbox` | Pause (only storage bills) and resume where it stopped. |
| `list_sandboxes`, `delete_sandbox` | List the sandboxes this install made; delete one. |

Each tool but `read_file` (and `sign_up` and `verify`) also answers with structured content, described by its `outputSchema`, for a client or script to read without parsing the text.

## The key [#the-key]

* **Where it comes from:** `PRIZED_API_KEY` if set, else the `prized` CLI's login on your machine.
* **Where sign-up keeps it:** where `prized login` does, `~/.config/prized/cp.token`, readable only by you. Later sessions and the CLI use it; no tool ever shows it to the agent.
* **What it can do:** sandboxes and boxes, never secrets, for 90 days. The first time you sign in at prized.dev, you keep or revoke it ([The key](https://prized.dev/docs/agent-sign-in#the-key)).

## Defaults [#defaults]

* **Idle sandboxes pause** after 15 minutes; the next call resumes them.
* **Paused ones are deleted** 7 days after they pause.
* **Everything it makes is labelled** `created-by=prized-sandbox-mcp` and `prized-mcp-scope=<id>`, an id kept on your machine beside the `prized` CLI's login (`~/.config/prized/sandbox-mcp-scope`).
* **Its tools use only what this install made.** They use only sandboxes with this install's `prized-mcp-scope` id, so an agent misled by something it read does not touch your other sandboxes, or another machine's, through these tools. Set `PRIZED_MCP_ALL_SANDBOXES=1` to let them use every sandbox.
* **That guards the tools, not the key.** Whoever holds the key, including an agent with a shell on your machine, reaches every sandbox in the workspace through the API or the CLI, and can create one carrying an install's id (every sandbox it made shows it). Keep sandboxes an agent must never reach in another workspace.
* **On the free credit**, sandboxes run within the [free tier](https://prized.dev/docs/sandboxes#free-tier).

## Configuration [#configuration]

| Variable |  |
| --- | --- |
| `PRIZED_API_KEY` | Optional. A key from [https://prized.dev/dashboard/workspace/api-keys](https://prized.dev/dashboard/workspace/api-keys) with **Full access**, or **Custom** with **Sandboxes: Write**, in the server's environment in your client's MCP config. |
| `PRIZED_MCP_LOCAL_DIRS` | Folders `upload` and `download` may use, separated like `PATH`; `off` for none. Default: the folder the agent starts the server in, unless that is your home folder. |
| `PRIZED_MCP_ALL_SANDBOXES` | Set to `1` to let the tools use every sandbox in the workspace, not only the ones this install made. Off by default. |
| `PRIZED_MCP_ALLOW_CONFIG_FILES` | Set to `1` to let `download` write files that make a tool on your machine run commands, such as `.claude/settings.json` or git hooks, when the agent asks with `allow_config_files`. While it is on, the agent decides each file, so turn it off again when you are done. Off by default. |

## Troubleshooting [#troubleshooting]

| Symptom | What to do |
| --- | --- |
| The agent has no Prized tools | Restart it. In Claude Code, `claude mcp list` shows whether the server connected. |
| "This server has no Prized key" | Ask the agent to sign you up, or run `prized login`. |
| "already has a Prized account" | Sign-up only makes new accounts: run `prized login`, then ask again. |
| Codex stops a tool after 60 seconds | Add `tool_timeout_sec = 3600` and `startup_timeout_sec = 60` under `[mcp_servers.prized-sandbox]` in `~/.codex/config.toml`. |
| No `upload` or `download` | The server started in your home folder or `/`: set `PRIZED_MCP_LOCAL_DIRS` to your project. |
