Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.podflare.ai/llms.txt

Use this file to discover all available pages before exploring further.

The MCP server is a thin STDIO server that wraps the Podflare SDK. Every MCP client gets run_python, run_bash, fork, diff, merge_into, upload, and download as tools for free.

​
Install + run

# from the repo
cd mcp
npm install
npm run build
The binary lands at mcp/dist/index.js. Make sure podflare-hostd is running on PODFLARE_HOSTD_URL before launching the MCP server.

​
Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json: 
{
  "mcpServers": {
    "podflare": {
      "command": "node",
      "args": ["/absolute/path/to/podflare/mcp/dist/index.js"],
      "env": {
        "PODFLARE_HOSTD_URL": "https://api.podflare.ai"
      }
    }
  }
}
Restart Claude Desktop. In a conversation, Claude will list Podflare’s tools alongside its own.

​
Cursor / Cline / Zed / Windsurf

Any MCP client that reads an mcpServers config in the same shape works. See each client’s docs for the exact config file location.

​
Tools exposed

​
run_python
tool
Execute Python in a Podflare sandbox. State persists across calls (REPL). Returns {stdout, stderr, exit_code}.
​
run_bash
tool
Execute a bash snippet. Fresh subprocess each call.
​
fork
tool
Spawn N children from current sandbox state. Returns a list of child sandbox IDs.
​
diff
tool
Filesystem diff between two sandboxes.
​
merge_into
tool
Commit a winner fork as the new parent state.
​
upload
tool
Copy base64-encoded bytes into a path inside the sandbox.
​
download
tool
Read a file from the sandbox, return base64.

​
Session model

One MCP session = one Podflare sandbox. The sandbox is lazily created on the first tool call and destroyed on SIGTERM/SIGINT. If the MCP client reopens the connection, a fresh sandbox is created — prior state is lost. This matches MCP’s own session model.