MCP server

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 or via the Blaxel SDKs. Connect to this MCP server like any other MCP server through 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>

Bearer-token authentication only — there is no OAuth for connecting to the sandbox MCP endpoint. See MCP endpoints at a glance for how this compares to the other MCP surfaces on Blaxel.

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

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

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 (⚠️ 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:

import { blTools } from "@blaxel/vercel";

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

from blaxel.langgraph import bl_tools

tools = await bl_tools([f"sandbox/{sandbox_name}"])

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.

Get Started

Sandboxes

Agent Drive

Volumes

Batch Jobs

Agents Hosting

MCP Servers Hosting

Model Gateway

Observability

Integrations

Administration & security

Troubleshooting

Connect to the MCP server

Add to Cursor

Add to Claude Code

Add to Windsurf

Add to Goose

Tools available in the MCP server

Process management

Filesystem operations

Code search and navigation

Code editing

Example: Connect to a sandbox from Claude Agent SDK

Connect Claude Code to a Blaxel Sandbox

​Connect to the MCP server

​Add to Cursor

​Add to Claude Code

​Add to Windsurf

​Add to Goose

​Tools available in the MCP server

​Process management

​Filesystem operations

​Code search and navigation

​Code editing

​Example: Connect to a sandbox from Claude Agent SDK

Connect Claude Code to a Blaxel Sandbox

Connect to the MCP server

Add to Cursor

Add to Claude Code

Add to Windsurf

Add to Goose

Tools available in the MCP server

Process management

Filesystem operations

Code search and navigation

Code editing

Example: Connect to a sandbox from Claude Agent SDK