ParallelSandbox MCP server

parallelsandbox-mcp

stdio adapter for the ParallelSandbox MCP server. It exposes the same tools as https://mcp.parallelsandbox.com/mcp (sandbox, logs), forwarding every call with your API key, and implements sandboxsync and sandboxpull locally: an agent can upload its working directory into a box without committing, and write files from the box back to its machine. Get an API key (psbx_…) in the app: https://app.parallelsandbox.com → Account → API keys.

Use

PARALLELSANDBOX_API_KEY=psbx_... npx parallelsandbox-mcp

Claude Code:

claude mcp add parallelsandbox -e PARALLELSANDBOX_API_KEY=psbx_... -- npx -y parallelsandbox-mcp

Any other MCP client: run the command above as a stdio server.

If you never need sandboxsync or sandboxpull, you can skip this package and connect directly (over plain HTTP those two tools return an error, because they read and write files on your machine):

claude mcp add --transport http parallelsandbox https://mcp.parallelsandbox.com/mcp --header "Authorization: Bearer psbx_..."

Environment

sandbox_sync

{"id": "", "localPath": "/abs/path/to/repo", "dest": "repo"} syncs localPath into /work/ on the box. Pass an absolute path: a relative one resolves against this adapter's working directory (where your MCP client started it), which is not necessarily the agent's. In a git working tree it takes the tracked files plus the untracked files .gitignore does not exclude, asks the box which of them differ from what is already in dest, and uploads only those, so syncing after an edit sends just that edit. A file changed inside the box counts as different and gets the local version back. Outside git it uploads the whole directory, excluding node_modules, .git, dist, build, coverage, .venv and similar. Files deleted locally stay in the box.

sandbox_pull

{"id": "", "path": "", "localPath": "/abs/path/on/your/machine"} downloads a file or a directory from the box. A directory arrives as a tar.gz and is extracted into localPath (pass "extract": false to keep the archive); a file is written to localPath. Relative paths resolve the same way as for sandbox_sync.

Which conversation is using a box

Each time the adapter starts it picks a random id and sends it as X-Psbx-Agent on every call. After the first tool call it reports to /v1/agents//heartbeat once a minute, and when its conversation closes (stdin ends, or SIGTERM, SIGINT or SIGHUP) it reports /v1/agents//leave. The app uses this to tell a box the AI is still working in from one whose conversation was closed without sandboxreview or sandboxstop; a conversation killed outright (no leave) counts as gone three minutes after its last heartbeat. Nothing else is sent: no prompt, no transcript.

Timeouts

sandboxtakeover blocks until a person hands the box back, up to 30 minutes; the adapter waits 31 minutes for it and 65 minutes for other calls (a foreground sandboxexec runs at most 60 minutes).

Shortened. The full README is on GitHub.