MCP server
Updated
Give Claude Code, Codex or Cursor your Prized boxes, and sandboxes of its own, over MCP. No API key needed; your agent signs you up with your email and a 6-digit code.
On this page10
@prized/mcp is an MCP server for your boxes and for sandboxes. Install it once, and in every session your agent can run commands and move files on your boxes, and run code, move files and fork machines in sandboxes.
1. Install
claude mcp add --scope user prized -- npx -y @prized/mcpRestart the agent after installing. It needs Node.js 20 or later. Any other MCP client runs npx -y @prized/mcp over stdio.
Had @prized/sandbox-mcp? It is this server under its old name. Remove the prized-sandbox entry (claude mcp remove prized-sandbox in Claude Code) and add prized as above; it keeps your key and the sandboxes the old one made.
2. Ask your agent
Run my tests on my box mango.- 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, no card (Agent sign-in).
- Already on Prized: run
prized loginonce (install the CLI first if you need it), and the server uses that login. Or give it a key asPRIZED_API_KEY(Configuration).
What your agent can do
sign_up and verify make you a new account from your email and the emailed code; they are offered only while the server has no key.
Boxes
| Tool | What it does |
|---|---|
list_boxes | List the boxes your key can see, each marked usable or not by these tools (Box defaults). |
create_box | Create a box. Spends money: a box bills while awake (Billing). A Nano unless the agent asks for another size, never a GPU box, and it pauses after 120 idle minutes unless the agent sets another window. |
run_on_box | Run a shell command on your box; returns the exit code, stdout and stderr, for up to 600 seconds. A paused box wakes first, which spends money. |
write_box_file, read_box_file | Write or read a file of up to 1 MiB. Neither wakes a paused box. |
pause_box, resume_box | Pause a box (only its disk bills) and wake it (spends money). |
No tool deletes a box: do that from the dashboard or with prized box delete. To move a Claude Code conversation onto a box, run prized teleport in its folder (Move Claude Code to the cloud).
Sandboxes
| Tool | What it does |
|---|---|
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 read_box_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
- Where it comes from:
PRIZED_API_KEYif set, else theprizedCLI's login on your machine. - Where sign-up keeps it: where
prized logindoes,~/, readable only by you. Later sessions and the CLI use it; no tool ever shows it to the agent..config/ prized/ cp.token - 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).
Box defaults
- The box tools use only your own boxes: the ones you own and the ones this server created. Teammates' boxes are listed but never touched, so an agent misled by something it read does not run commands on a teammate's machine through these tools. A key limited to some boxes uses every box it sees. Set
PRIZED_MCP_ALL_BOXES=1to let them use every box the key can see. - Telling which boxes are yours needs a key that can read the team (Workspace: Read, which Full access,
prized loginand agent sign-in keys have); with any other, only boxes this server created are usable. - That guards the tools, not the key. Whoever holds the key, including an agent with a shell on your machine, reaches every box the key can through the API or the CLI. Keep boxes an agent must never reach in another workspace, or give the server a key limited to some boxes.
Sandbox 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-mcpandprized-mcp-scope=<id>, an id kept on your machine beside theprizedCLI'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-scopeid, so an agent misled by something it read does not touch your other sandboxes, or another machine's, through these tools. SetPRIZED_MCP_ALL_SANDBOXES=1to let them use every sandbox. - That guards the tools, not the key. Whoever holds the key 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.
Configuration
| Variable | |
|---|---|
PRIZED_API_KEY | Optional. A key from https://prized.dev/dashboard/workspace/api-keys with Full access, or Custom with Boxes: Write and Workspace: Read for the box tools and Sandboxes: Write for the sandbox tools, 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_BOXES | Set to 1 to let the box tools use every box the key can see, teammates' included, not only your own. Off by default. |
PRIZED_MCP_ALL_SANDBOXES | Set to 1 to let the sandbox 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
| 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. |
| "This Prized key cannot use boxes" | The key was made for sandboxes only: make one with Boxes: Write and Workspace: Read, or run prized login. |
| "is not one of your boxes" | The box is a teammate's. Set PRIZED_MCP_ALL_BOXES=1, or give the server a key limited to the boxes it may use. |
| "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] in ~/.codex/config.toml. |
No upload or download | The server started in your home folder or /: set PRIZED_MCP_LOCAL_DIRS to your project. |