Run a server in the sandbox

Overview

A server that needs no secret can run inside the agent's sandbox. It starts with the same command that your repository declares. Documentation servers are the usual example. With such a server, the Builder reads the current API of a library. It does not have to guess the API from its training data. This guide binds two of them:

{
  "mcpServers": {
    "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp"] },
    "aws-agentcore-docs": {
      "command": "uvx",
      "args": ["awslabs.amazon-bedrock-agentcore-mcp-server@latest"]
    }
  }
}

The sandbox has Node, with npx and bunx, and Python 3.12 with uv, so uvx servers start without setup. A server that needs a different Python version gets it from uv on its first start.

Bind it for the planner and builder

ConsoleCLI

Select Bind on the server's card. Choose Inside the sandbox. Tick Planner, Builder or both. You don't add a credential.

A server inside the sandbox gives the agents all of its tools, because SHIP is not between the agent and the server to filter them. For the same reason, the Reviewer and the QA agent can't use such a server. If you ask for them, SHIP refuses and gives the reason:

$ ship mcp bind context7 --roles planner,builder,reviewer
Could not bind context7: reviewer can't use a server that runs inside the sandbox: only the gateway can hold them to read-only tools. Remove it from the roles, or bind the server to run isolated or remote.

To give the Reviewer a documentation server, bind the vendor's hosted endpoint instead. Context7 hosts one at https://mcp.context7.com/mcp. Then SHIP can limit the Reviewer to read-only tools.

Add a Python server the same way

You bind a uvx server in the same way as an npm server:

ship mcp bind aws-agentcore-docs --roles planner

On its first start in a sandbox, uvx downloads the package from PyPI. The AWS Labs servers use this method. The AgentCore documentation server above answered a search from the Planner on its first run in SHIP's sandbox. The repository needed no setup.

A Python server that needs a secret can't run inside the sandbox, because nothing there can hold a secret. It can't run isolated either, because only npm packages can. Bind the vendor's hosted endpoint for it, as in Connect a hosted server.

Check that the agent had it

The first row in the timeline of a claude-code run lists the MCP servers that the agent started with, and whether each one connected. Tool calls show as server - tool:

If a server failed to start, the agent's session log usually gives the cause. For example, the package doesn't exist, the image doesn't have the command, or the server needs a secret that it didn't get.