> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blaxel.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP server

> Built-in MCP server that allows agents to operate a sandbox using tool calls.

Every sandbox is exposed via an MCP server that allows agents to **operate it using tool calls.**

## Connect to the MCP server

The MCP server operates through streamable HTTP at the sandbox's base URL:

```text theme={null}
https://<SANDBOX_BASE_URL>/mcp
```

The base URL of a sandbox can be [retrieved](https://docs.blaxel.ai/api-reference/compute/get-sandbox) via the management API of sandboxes under `metadata.url`.

Connect to this MCP server [like any other MCP server](../Functions/Invoke-functions) though the endpoint shown above. Instructions for some popular applications are provided below.

<Note>
  You must provide your [Blaxel API key](../Security) in the `Authorization` header. If your user has access to multiple workspaces, include the workspace header as well.

  * Required: `Authorization: Bearer <APIKEY>`
  * Optional (multi-workspace): `X-Blaxel-Workspace: <WORKSPACE_NAME_OR_ID>`
</Note>

### Add to Cursor

Add the server to `~/.cursor/mcp.json`:

```json theme={null}
{
  "mcpServers": {
    "blaxel": {
      "url": "https://<SANDBOX_BASE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <APIKEY>",
        "X-Blaxel-Workspace": "<OPTIONAL_WORKSPACE>"
      }
    }
  }
}
```

### Add to Claude Code

[Add the remote HTTP server to your Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#option-3%3A-add-a-remote-http-server) by running the following command:

```bash theme={null}
claude mcp add --transport http blaxel https://<SANDBOX_BASE_URL>/mcp \\
  --header "Authorization: Bearer <APIKEY>" \\
  --header "X-Blaxel-Workspace: <OPTIONAL_WORKSPACE>"
```

[Follow this tutorial to build a Claude Agent SDK-powered agent that connects to a Blaxel sandbox and operates it using the sandbox's MCP server](../Tutorials/Claude-Agent-SDK-MCP).

### Add to Windsurf

Add to `~/.codeium/windsurf/mcp_config.json`:

```json theme={null}
{
  "mcpServers": {
    "blaxel": {
      "url": "https://<SANDBOX_BASE_URL>/mcp",
      "headers": {
        "Authorization": "Bearer <APIKEY>",
        "X-Blaxel-Workspace": "<OPTIONAL_WORKSPACE>"
      }
    }
  }
}
```

### Add to Goose

Add to `~/.config/goose/config.yaml`:

```yaml theme={null}
extensions:
  sandbox-mcp:
    enabled: true
    type: streamable_http
    name: sandbox-mcp
    description: Sandbox MCP
    uri: https://<SANDBOX_BASE_URL>/mcp
    envs: {}
    env_keys: []
    headers:
      Authorization: Bearer <APIKEY>
      X-Blaxel-Workspace: <OPTIONAL_WORKSPACE>
    timeout: 300
    bundled: null
    available_tools: []
```

## Tools available in the MCP server

### Process management

| Tool             | Description                                                   |
| ---------------- | ------------------------------------------------------------- |
| `processExecute` | Execute a command with options for timeout, restart, env vars |
| `processGet`     | Get info about a process by PID or name                       |
| `processGetLogs` | Get logs for a specific process                               |
| `processesList`  | List all running processes                                    |
| `processStop`    | Stop a specific process                                       |
| `processKill`    | Kill a specific process                                       |

### Filesystem operations

| Tool                      | Description                       |
| ------------------------- | --------------------------------- |
| `fsGetWorkingDirectory`   | Get the current working directory |
| `fsListDirectory`         | List contents of a directory      |
| `fsReadFile`              | Read contents of a file           |
| `fsWriteFile`             | Create or update a file           |
| `fsDeleteFileOrDirectory` | Delete a file or directory        |

### Code search and navigation

| Tool                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `codegenCodebaseSearch` | Semantic search to find relevant code snippets                  |
| `codegenFileSearch`     | Fast fuzzy file path search                                     |
| `codegenGrepSearch`     | Exact regex search using ripgrep engine                         |
| `codegenListDir`        | List directory contents (quick discovery)                       |
| `codegenReadFileRange`  | Read file contents within a specific line range (max 250 lines) |
| `codegenRerank`         | Performs semantic search/reranking on code files in a directory |

### Code editing

| Tool                   | Description                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------- |
| `codegenEditFile`      | Propose and apply a [targeted edit to a file](/Sandboxes/Codegen-tools) (⚠️ requires Morph or Relace API key) |
| `codegenParallelApply` | Plan parallel edits across multiple file locations                                                            |
| `codegenReapply`       | Use smarter model to retry a failed edit                                                                      |

Using Blaxel SDK, you can retrieve the tools for a sandbox in any supported framework format by passing the sandbox’s name. For example, in LangGraph:

<CodeGroup>
  ```typescript TypeScript theme={null}
  import { blTools } from "@blaxel/vercel";

  const tools = await blTools([`sandbox/${sandboxName}`])
  ```

  ```python Python theme={null}
  from blaxel.langgraph import bl_tools

  tools = await bl_tools([f"sandbox/{sandbox_name}"])
  ```
</CodeGroup>

[Read more documentation](../Functions/Invoke-functions) on connecting to the MCP server directly from your code.

## Example: Connect to a sandbox from Claude Agent SDK

<Card title="Connect Claude Code to a Blaxel Sandbox" icon="cube" iconType="light" href="../Tutorials/Claude-Agent-SDK-MCP">
  Build a Claude Agent SDK agent that connects to a Blaxel sandbox and operates it using the sandbox's MCP server.
</Card>