Skip to main content
Every Blaxel sandbox exposes a Model Context Protocol (MCP) server that allows agents to operate the sandbox using tool calls. This includes tools for process management, filesystem operations, and code generation. This guide demonstrates by creating a sandbox-aware agent using the Claude Agent SDK, but you could also use other frameworks like LangChain, Vercel AI SDK, Mastra, or your own custom code.

​
Assumptions

This example assumes that you have the following:

​
1. Install required dependencies

Create a directory for the project: 
mkdir sandbox-agent && cd sandbox-agent
Agents deployed on Blaxel must expose an HTTP endpoint for requests. In your project directory, install the Claude Agent SDK for the agent loop, the Blaxel TypeScript SDK / Python SDK for sandbox operations, and Express (TypeScript) / FastAPI (Python) to handle HTTP requests and responses: 
npm init # if new project
npm install @anthropic-ai/claude-agent-sdk express @blaxel/core

​
2. Configure the environment

Add your API keys to a .env file in the project directory: 
echo "ANTHROPIC_API_KEY=your_anthropic_key_here" > .env
echo "BL_API_KEY=your_blaxel_key_here" >> .env

​
3. Build the agent

In your project directory, create a file named index.ts (TypeScript) or main.py (Python) with the following code: 
import { query } from "@anthropic-ai/claude-agent-sdk";
import express from "express";
import { SandboxInstance } from "@blaxel/core";

const host = process.env.HOST || "0.0.0.0";
const port = parseInt(process.env.PORT || "8000");

const app = express();

app.use(express.json());

app.post("/query", async (req, res) => {
  const { prompt } = req.body;

  if (!prompt) {
    return res.status(400).json({ error: "prompt is required" });
  }

  if (!process.env.BL_API_KEY) {
    return res.status(400).json({ error: "BL_API_KEY env var is required" });
  }

  try {

    const sandbox = await SandboxInstance.createIfNotExists({
      name: "my-sandbox",
      image: "blaxel/base-image:latest",
      memory: 4096,
    });

    let response = "";

    for await (const message of query({
      prompt: prompt,
      options: {
        systemPrompt: "You are connected to a sandbox environment with tools. Use the tools to accomplish the task.",
        mcpServers: {
          "sandbox": {
            type: "http",
            url: `${sandbox.metadata?.url}/mcp`,
            headers: {
              Authorization: `Bearer ${process.env.BL_API_KEY}`,
            },
          },
        },
        tools: [],
        permissionMode: "bypassPermissions",
        allowDangerouslySkipPermissions: true,
      }
    })) {
      if (message.type === "assistant" && message.message?.content) {
        for (const block of message.message.content) {
          if ("text" in block) {
            console.log(block.text);
          } else if ("name" in block) {
            console.log(`Tool: ${block.name}`);
          }
        }
      } else if (message.type === "result") {
        console.log(`Done: ${message.result}`); // Final result
        response = message.result
      }
    }

    return res.json({ response });
  } catch (error) {
    return res.status(500).json({ error: error instanceof Error ? error.message : "Unknown error" });
  }
});

app.listen(port, host, () => {
  console.log(`Server listening on ${host}:${port}`);
});
This creates a Blaxel sandbox named my-sandbox and an agent using the Claude Agent SDK.
  • The sandbox exposes a streamable HTTP MCP server at the sandbox’s base URL: https://<SANDBOX_BASE_URL>/mcp. The base URL can be retrieved under metadata.url in the sandbox.
  • The agent exposes an HTTP endpoint at /query to accept user requests.
  • The agent’s HTTP service is bound to the host and port provided by Blaxel. Blaxel automatically injects these values as HOST and PORT variables into the runtime environment.
  • The agent configuration includes the sandbox MCP server URL and uses the Blaxel API key as credential to gain access to it (the Authorization header).
In TypeScript, entrypoints are managed in the scripts section of the package.json file. Update your package.json to ensure that start and dev scripts are defined in the scripts section (TypeScript only). 
{
  "scripts": {
    "start": "tsx index.ts",
    "dev": "tsx --watch index.ts",
    "build": "tsc"
  },
  // ...
}
Your agent is now ready to operate the sandbox using the sandbox’s MCP tools! For example, you could instruct the agent to “install a Python dev environment” and it would use the available MCP tools to find, download and install all the required libraries and tools for Python development in the sandbox.

​
Next steps

Blaxel isn’t just a sandbox platform. It also lets you co-host and deploy your agent as a serverless auto-scalable endpoint, with near-instant latency. Agent hosting provides endpoints for both synchronous and asynchronous requests and includes full observability and tracing out of the box. The following resources will help you go further:

Build and deploy an agent on Blaxel with Claude Agent SDK

Complete guide for building an agent with Claude Agent SDK and deploying it on Blaxel as a serverless auto-scalable API.

Give compute to your agent with the TypeScript SDK

Complete guide for using the TypeScript SDK to develop an agent using Blaxel services.

Give compute to your agent with the Python SDK

Complete guide for using the Python SDK to develop an agent using Blaxel services.

Deploy your agent code to Blaxel

Complete guide for deploying AI agents on Blaxel.

Manage environment variables

Complete guide for managing variables and secrets when deploying on Blaxel.