> ## 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.

# MCP server

> Plug Podflare into any MCP-capable client — Claude Desktop, Cursor, Cline, Zed, Windsurf.

<Note>
  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.
</Note>

## Install + run

```bash theme={null}
# 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`:

```json theme={null}
{
  "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

<ParamField path="run_python" type="tool">
  Execute Python in a Podflare sandbox. State persists across calls
  (REPL). Returns `{stdout, stderr, exit_code}`.
</ParamField>

<ParamField path="run_bash" type="tool">
  Execute a bash snippet. Fresh subprocess each call.
</ParamField>

<ParamField path="fork" type="tool">
  Spawn N children from current sandbox state. Returns a list of child
  sandbox IDs.
</ParamField>

<ParamField path="diff" type="tool">
  Filesystem diff between two sandboxes.
</ParamField>

<ParamField path="merge_into" type="tool">
  Commit a winner fork as the new parent state.
</ParamField>

<ParamField path="upload" type="tool">
  Copy base64-encoded bytes into a path inside the sandbox.
</ParamField>

<ParamField path="download" type="tool">
  Read a file from the sandbox, return base64.
</ParamField>

## 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.