MCP server

Every Blaxel sandbox exposes a built-in MCP server so agents can operate the sandbox using tool calls for files, processes, ports, and previews.

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

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

TypeScript

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.