Skip to main content
The Podflare MCP server is a thin STDIO wrapper around the Podflare SDK. Once connected, any MCP-capable AI client — Claude Desktop, Cursor, Cline, Zed, Windsurf, or any other — gains a full set of sandbox tools: execute Python and bash, fork the environment, diff filesystems, merge results, and transfer files. No plugin code required on the client side.
One MCP session equals one Podflare sandbox. The sandbox is created lazily on the first tool call and destroyed when the server receives SIGTERM or SIGINT. If the client reconnects, a fresh sandbox starts — prior state is lost, which matches MCP’s own session model.

​
Installation

Build the MCP server from the Podflare repository. Node 20 or later is required.
1

Build the server

Clone the repository (or navigate to an existing checkout), then build the MCP package.
cd mcp
npm install
npm run build
The compiled entry point lands at mcp/dist/index.js. Note its absolute path — you will need it in every client configuration block.
2

Verify your Podflare host

Make sure the Podflare API is running and reachable at the address you plan to set for PODFLARE_HOST. The MCP server forwards every tool call to that host; if it is unreachable the tool call fails with a connection error.

​
Client configuration

Add a podflare entry to your MCP client’s mcpServers configuration. The shape is identical across all clients — only the config file location differs.
Add the block below to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent path on your OS. Restart Claude Desktop after saving.
{
  "mcpServers": {
    "podflare": {
      "command": "node",
      "args": ["/absolute/path/to/podflare/mcp/dist/index.js"],
      "env": {
        "PODFLARE_HOST": "https://api.podflare.dev",
        "PODFLARE_API_KEY": "pk_your_key_here"
      }
    }
  }
}
After restarting, Claude lists Podflare’s tools alongside its built-in capabilities in every conversation.

​
Environment variables

​
PODFLARE_HOST
string
required
The base URL of the Podflare API. Set this in the env block of every client configuration so the MCP server can reach the API. Use https://api.podflare.dev for the hosted service.
​
PODFLARE_API_KEY
string
Your Podflare API key, forwarded on every request. Required for the hosted API at https://api.podflare.dev. See Authentication for how to obtain and use your key.

​
Available tools

Every MCP session exposes the following tools. The AI client can call them autonomously or in response to user prompts.
​
run_python
tool
Execute a Python snippet inside the sandbox. State persists across calls — variables, imports, and open file handles are all retained between invocations (REPL semantics). Returns {stdout, stderr, exit_code}.
​
run_bash
tool
Execute a bash snippet. Each call spawns a fresh subprocess, so environment variables set in one call do not persist to the next.
​
fork
tool
Snapshot the current sandbox and spawn n children from that moment’s state. Returns a list of child sandbox IDs. Each child inherits the parent’s Python REPL state, filesystem, and running processes.
​
diff
tool
Compare the filesystems of two sandboxes. Returns the set of added, removed, and modified paths. Useful for inspecting what a fork changed relative to a sibling.
​
merge_into
tool
Commit a winner fork as the new state of the parent sandbox. After this call the parent’s ID drives the winner’s VM; the winner’s ID becomes defunct.
​
upload
tool
Write base64-encoded bytes to a path inside the sandbox filesystem.
​
download
tool
Read a file from the sandbox filesystem and return its contents as base64.

​
Session model

Each time an MCP client opens a connection to the Podflare MCP server, a single sandbox is created for that session. All tool calls within the session share that sandbox — state accumulates across calls just like a terminal session. When the connection closes (or the server receives SIGTERM/SIGINT), the sandbox is destroyed. If the client reconnects, a new sandbox starts from scratch. This behaviour is intentional: it keeps the session model predictable and consistent with how MCP itself defines session boundaries.
Do not rely on sandbox state persisting across client reconnections. If you need durable state, use upload and download to checkpoint files before closing the session, then restore them after reconnecting.