Skip to main content
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: 
https://<SANDBOX_BASE_URL>/mcp
The base URL of a sandbox can be retrieved via the management API of sandboxes under metadata.url. Connect to this MCP server like any other MCP server though the endpoint shown above. Instructions for some popular applications are provided below.
You must provide your Blaxel API key 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>

​
Add to Cursor

Add the server to ~/.cursor/mcp.json: 
{
  "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 by running the following command: 
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.

​
Add to Windsurf

Add to ~/.codeium/windsurf/mcp_config.json: 
{
  "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: 
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

ToolDescription
processExecuteExecute a command with options for timeout, restart, env vars
processGetGet info about a process by PID or name
processGetLogsGet logs for a specific process
processesListList all running processes
processStopStop a specific process
processKillKill a specific process

​
Filesystem operations

ToolDescription
fsGetWorkingDirectoryGet the current working directory
fsListDirectoryList contents of a directory
fsReadFileRead contents of a file
fsWriteFileCreate or update a file
fsDeleteFileOrDirectoryDelete a file or directory

​
Code search and navigation

ToolDescription
codegenCodebaseSearchSemantic search to find relevant code snippets
codegenFileSearchFast fuzzy file path search
codegenGrepSearchExact regex search using ripgrep engine
codegenListDirList directory contents (quick discovery)
codegenReadFileRangeRead file contents within a specific line range (max 250 lines)
codegenRerankPerforms semantic search/reranking on code files in a directory

​
Code editing

ToolDescription
codegenEditFilePropose and apply a targeted edit to a file (⚠️ requires Morph or Relace API key)
codegenParallelApplyPlan parallel edits across multiple file locations
codegenReapplyUse 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: 
import { blTools } from "@blaxel/vercel";

const tools = await blTools([`sandbox/${sandboxName}`])
Read more documentation on connecting to the MCP server directly from your code.

​
Example: Connect to a sandbox from Claude Agent SDK

Connect Claude Code to a Blaxel Sandbox

Build a Claude Agent SDK agent that connects to a Blaxel sandbox and operates it using the sandbox’s MCP server.