> For the complete documentation index, see [llms.txt](https://docs.ai.neevcloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-mcp-server.md). # Sandbox MCP Server ![Diagram: Claude Code, Cursor and your own agent connect with a bearer API key to one sandbox MCP URL, which offers run, lifecycle and undo tools and routes each connection to its own sandbox: api-fix ready, ui-review paused, run-4821 new. Egress, CPU and memory are not tools the agent can call.](https://1980728309-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSqquJG2zKVZ5l1Sd5aQy%2Fuploads%2Fgit-blob-70fa861ff477a2152b4024f9aa3cfceb54086f92%2Fmcp.jpg?alt=media) The sandbox MCP server gives any MCP-capable agent, such as Claude Code, Cursor, Codex or one you built, a NeevCloud sandbox as native tools. You connect it with one URL and one API key. You don't install a CLI, run a bridge process or configure a per-sandbox endpoint. ## The Endpoint ``` https://mcp.sandboxes.as-south-1.ai.neevcloud.com/mcp ``` The region in the hostname matches the sandbox's `region`. The server speaks MCP over Streamable HTTP and holds no session, so there's nothing to keep alive between calls. | Header | Value | | ---------------- | ------------------------------------------------------------------------------------------------------------- | | `Authorization` | `Bearer sk-nc-…`, your project [API key](/getting-started/create-api-key.md). `x-api-key: sk-nc-…` also works | | `x-sandbox-name` | The name of the sandbox this connection works in. Omit it and the name is `default` | **One URL for every sandbox.** The tools never take a sandbox id. The `x-sandbox-name` header chooses the sandbox, so pointing an agent at a different sandbox means changing one header, not the URL. ## Let Your Agent Set It Up The quickest path is to have your coding agent configure the connection itself. The only credential it needs is a project API key: no Personal Access Token, no sign-in and no CLI. You need [Node.js](https://nodejs.org/) 22.20 or later, because the agent uses `npx` to install the setup skill. Check with `node --version`. ### 1. Create an API Key Create a project [API key](/getting-started/create-api-key.md) (`sk-nc-…`) in the console, choosing **Sandboxes** as its **Resource Type**. A key created for another resource type is refused by the MCP server. Keep the key to hand for the next step. ### 2. Put the Key in Your Environment The agent reads the key from an environment variable named `NEEV_API_KEY`, so it never has to be pasted into chat or written into an agent config file. {% tabs %} {% tab title="macOS" %} macOS uses zsh by default. Open your shell profile in a plain-text editor such as `nano`: ```bash nano ~/.zshrc ``` Add this line, with your key in place of `sk-nc-...`, then save with **Ctrl+O** and exit with **Ctrl+X**: ```bash export NEEV_API_KEY="sk-nc-..." ``` Open a **new** terminal window and check that it's set, without printing it: ```bash [ -n "$NEEV_API_KEY" ] && echo "NEEV_API_KEY is set" || echo "NEEV_API_KEY is not set" ``` {% endtab %} {% tab title="Linux" %} Open your shell profile in a text editor, such as `nano`. For bash that's `~/.bashrc`; for zsh use `~/.zshrc` instead: ```bash nano ~/.bashrc ``` Add this line, with your key in place of `sk-nc-...`, and save the file: ```bash export NEEV_API_KEY="sk-nc-..." ``` Open a **new** terminal and check that it's set, without printing it: ```bash [ -n "$NEEV_API_KEY" ] && echo "NEEV_API_KEY is set" || echo "NEEV_API_KEY is not set" ``` {% endtab %} {% tab title="Windows" %} In PowerShell 7.1 or later, save the key as a user environment variable. You're prompted for it, so it isn't kept in your command history: ```powershell $key = Read-Host "NeevCloud API key" -MaskInput [Environment]::SetEnvironmentVariable("NEEV_API_KEY", $key, "User") Remove-Variable key ``` On Windows PowerShell 5.1, which has no `-MaskInput`, add it instead from **Start > Edit environment variables for your account > New**, with the name `NEEV_API_KEY` and your key as the value. Only programs started afterwards see the new variable. Close your terminal app completely, including any other open tabs, then open it again from the Start menu and check that it's set, without printing it: ```powershell if ($env:NEEV_API_KEY) { "NEEV_API_KEY is set" } else { "NEEV_API_KEY is not set" } ``` If you run your agent inside WSL, follow the Linux tab in your WSL shell instead. {% endtab %} {% endtabs %} Your profile now holds the key in plain text, like any other credential file on your machine. Keep it out of anything you share or commit. ### 3. Start Your Agent from That Terminal An agent only sees variables that were set before it started. Start it from the new terminal, in the project you want to work in: {% tabs %} {% tab title="Claude Code" %} ```bash cd my-project claude ``` {% endtab %} {% tab title="Codex" %} ```bash cd my-project codex ``` {% endtab %} {% tab title="Cursor" %} ```bash cd my-project cursor . ``` Launching Cursor from this terminal means it starts with `NEEV_API_KEY` set. If the `cursor` command is missing, run **Shell Command: Install 'cursor' command** from Cursor's command palette. {% endtab %} {% endtabs %} ### 4. Paste the Prompt Paste this prompt into the agent: ```md Connect this agent to a NeevCloud sandbox over MCP. Install or update the neev-sandbox-mcp skill and follow it. MCP is all this needs, so don't install the CLI, the SDKs or any other skill: npx -y skills add NeevCloudAI/agent-skills -g -s neev-sandbox-mcp -y - The only credential is the API key in NEEV_API_KEY. Don't ask me for a Personal Access Token or to sign in. - Check that NEEV_API_KEY is set without printing it. If it isn't, stop and tell me. - Never ask me to paste the key into chat, and never write its value into a file. The config must read it from the environment. - Propose a sandbox name from this project's directory name and confirm it with me. - Write the MCP config for the agent you are running in, then tell me what to restart. - After the restart, list the server's tools and call get_sandbox to prove it works. - Ask me before creating, deleting or rolling back a sandbox, or exposing a port. - If I'm setting this up for Claude Desktop, skip the NEEV_API_KEY check and follow the skill's Claude Desktop section: create the headers file with a placeholder for me to fill in myself, then tell me to quit and reopen Claude Desktop. ``` The agent installs the setup skill, confirms a sandbox name with you, and writes a config that refers to `NEEV_API_KEY` rather than containing it, so the file is safe to keep in the project. ### 5. Restart the Agent and Check the Connection An agent loads a new MCP server only when it starts. Restart it from the same terminal, then check that `neev-sandbox` is connected: | Agent | Restart | Check | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | Claude Code | Type `/exit`, then run `claude` again. Approve the `neev-sandbox` server when asked, since it comes from the project's `.mcp.json` | Run `/mcp`. `neev-sandbox` shows as connected, with its tool count | | Codex | Quit, then run `codex` again | Run `/mcp`, or `codex mcp list` from the terminal | | Cursor | Quit Cursor and run `cursor .` again | Open the **Customize** page and make sure `neev-sandbox` is turned on | Then ask the agent to call `get_sandbox`. Until a sandbox exists it reports that none is bound to the connection, which means the setup works. The agent creates the sandbox the first time you need it, after asking you. ### Claude Desktop Claude Desktop doesn't read your shell environment, so skip step 2. Run the prompt in a coding agent such as Claude Code and say it's for Claude Desktop. The agent creates a headers file at `~/.neevcloud/sandbox-mcp.headers` with a placeholder. Open the file, replace the placeholder with your key, and save it. Then quit Claude Desktop completely and reopen it. To do it by hand instead, follow the Claude Desktop tab below. If you'd rather configure any agent yourself, use the settings below. ## Connect Your Agent {% tabs %} {% tab title="Claude Code" %} ```bash claude mcp add --transport http neev-sandbox \ https://mcp.sandboxes.as-south-1.ai.neevcloud.com/mcp \ --header "Authorization: Bearer $NEEV_API_KEY" \ --header "x-sandbox-name: my-agent" ``` {% endtab %} {% tab title="Cursor and other JSON configs" %} ```json { "mcpServers": { "neev-sandbox": { "url": "https://mcp.sandboxes.as-south-1.ai.neevcloud.com/mcp", "headers": { "Authorization": "Bearer sk-nc-...", "x-sandbox-name": "my-agent" } } } } ``` {% endtab %} {% tab title="Claude Desktop" %} Claude Desktop's configuration file starts only local (stdio) servers, so it reaches the sandbox MCP server through the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) bridge. You need Node.js installed. Put the headers in a file that only you can read, such as `~/.neevcloud/sandbox-mcp.headers`: ``` Authorization: Bearer sk-nc-... x-sandbox-name: my-agent ``` On macOS or Linux, run `chmod 600 ~/.neevcloud/sandbox-mcp.headers`. Then add the server to `claude_desktop_config.json`, which is in `~/Library/Application Support/Claude/` on macOS and `%APPDATA%\Claude\` on Windows. Use the file's full path, because `~` isn't expanded here: ```json { "mcpServers": { "neev-sandbox": { "command": "npx", "args": [ "-y", "mcp-remote@latest", "https://mcp.sandboxes.as-south-1.ai.neevcloud.com/mcp", "--transport", "http-only", "--header-file", "/Users/me/.neevcloud/sandbox-mcp.headers" ] } } } ``` Quit Claude Desktop completely and reopen it. Closing the window isn't enough. {% endtab %} {% endtabs %} **Note:** An MCP configuration file, or the Claude Desktop headers file, holds your API key in plain text. Treat it like any other secret file, and keep it out of version control. ## You Don't Have to Create the Sandbox First Name a sandbox that doesn't exist yet in `x-sandbox-name`. The first time a tool reports that there's no such sandbox, the agent calls `create_sandbox`, with no arguments needed, and it creates the sandbox this connection already names. `create_sandbox` waits until the new sandbox is reachable before it returns, so the next call can use it. If a call still says the sandbox isn't ready, the agent should check `get_sandbox` and wait a moment rather than creating another one. ## The Tools **Work inside the sandbox** | Tool | What it does | | ---------------------------------- | ------------------------------------------------------------------------- | | `exec` | Run a program and wait for it to finish | | `fs_read` / `fs_write` / `fs_list` | Read, write and list files in the workspace | | `process_start` | Start a long-running program and return straight away with its process id | | `process_get` | A process's state, and its result once it has exited | | `process_logs` | A process's captured output, from a byte cursor | | `process_kill` | Send a signal to a process | **Manage the sandbox** | Tool | What it does | | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | | `create_sandbox` | Create the sandbox this connection names. Optionally takes an idle timeout | | `get_sandbox` | Report its phase, so the agent knows when it's ready | | `pause_sandbox` / `resume_sandbox` | Pause it to stop compute billing, or resume it | | `keepalive_sandbox` | Reset the idle timer while the agent is busy elsewhere | | `update_sandbox_timeout` | Change the idle and lifetime windows | | `create_snapshot` / `list_snapshots` | Checkpoint memory and files, and list checkpoints | | `rollback_sandbox` | Put the sandbox back to a snapshot. See [Undo and Duplicate](/agentic-studio/overview/undo-and-duplicate.md) | | `expose_port` / `list_ports` / `revoke_port` | Share a running server on a [preview URL](/agentic-studio/overview/exposing-ports.md), and take it down again | | `get_sandbox_metrics` | CPU, memory and disk usage over time | | `delete_sandbox` | Delete the sandbox and everything in it. This can't be undone | With `create_snapshot` and `rollback_sandbox`, an agent can checkpoint before a risky step and undo its own mistake, without you writing any code. ## Built for an Agent You Don't Fully Trust The server is designed on the assumption that the model on the other end may have been prompt-injected: * **No tool can change the network policy.** The agent can't widen its own [egress](/agentic-studio/overview/internet-access.md). Only you can, through the API or SDK. * **No tool can resize the sandbox** or change its CPU and memory. * **Responses never include the egress policy**, so an injected model can't use them to learn where it's able to connect. * **No tool mints console login tokens**, and none lists your other sandboxes. * **Preview URLs get a random slug** generated by the platform, never one the model picks, so the agent can't create a guessable URL. Every command, process and file operation an agent makes through these tools appears in the sandbox's [audit trail](/agentic-studio/overview/audit-trail.md). ## Phases the Agent Will See | `get_sandbox` phase | What to do | | -------------------------------- | ------------------------------------------------------------------- | | `Ready` | Run commands now | | `Paused` | Carry on. The next tool call wakes it. Don't create another sandbox | | `Pending`, `NotReady`, `Unknown` | Still starting. Wait a few seconds and check again | | `RestoreFailed` | It won't recover. Delete it and create a new one | ## Two MCP Servers, Two Jobs | | Sandbox MCP server (this page) | [NeevCloud MCP](/getting-started/mcp/overview.md) | | ---------------------- | ----------------------------------------- | ------------------------------------------------- | | **Gives the agent** | One sandbox to work in | Your account: list resources, view GPUs and so on | | **Authenticates with** | Project API key (`sk-nc-…`) | Personal Access Token | | **Use it for** | Running code, files, processes, snapshots | Managing cloud resources in natural language | ## Remember A sandbox uses quota for as long as it exists. Pausing stops compute billing, but only `delete_sandbox` (or a lifetime limit with `on_idle: "delete"`, see [Auto Pause and Resume](/agentic-studio/overview/auto-pause-and-resume.md)) removes it. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.ai.neevcloud.com/agentic-studio/overview/sandbox-mcp-server.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.