Setup

This page covers direct connections to your PodWarden instance. If your instance isn't directly reachable (behind NAT/firewall), see Hub MCP Proxy instead — your AI client connects to Hub, which routes commands through a secure tunnel.

Prerequisites

• A running PodWarden instance accessible via HTTPS
• An MCP token (create one in Settings → MCP → Create Token)

The MCP endpoint is at https://your-podwarden.example/mcp.

Claude Desktop

Claude Desktop does not support url + headers configs for remote MCP servers. Instead, it uses the mcp-remote package as a stdio-to-HTTP bridge.

Requirements: Node.js (provides npx)

1. Open Claude Desktop → Settings → Developer → Edit Config
2. Add the "podwarden" entry inside your existing mcpServers. If the file already has content, merge it — don't paste as a separate JSON block.
3. Save and restart Claude Desktop.

{
  "mcpServers": {
    "podwarden": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-podwarden.example/mcp",
        "--header",
        "Authorization:${PODWARDEN_TOKEN}"
      ],
      "env": {
        "PODWARDEN_TOKEN": "Bearer pwm_YOUR_TOKEN_HERE"
      }
    }
  }
}

The token is placed in env rather than inline in args to avoid a Windows escaping bug where spaces in args get mangled.

The "Add connector" UI dialog in Claude Desktop only supports OAuth — use the config file for Bearer token auth.

Claude Code

Run this command in your terminal:

claude mcp add --transport http podwarden https://your-podwarden.example/mcp \
  --header "Authorization: Bearer pwm_YOUR_TOKEN_HERE"

The server will be available immediately in your next Claude Code session.

Cursor

1. Open Cursor Settings → MCP → "Add new global MCP server"
2. Paste the following config:

{
  "mcpServers": {
    "podwarden": {
      "url": "https://your-podwarden.example/mcp",
      "headers": {
        "Authorization": "Bearer pwm_YOUR_TOKEN_HERE"
      }
    }
  }
}

Other clients

Any MCP-compatible client can connect using the Streamable HTTP transport.

Manual test with curl

curl -X POST https://your-podwarden.example/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer pwm_YOUR_TOKEN_HERE" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {"name": "test", "version": "1.0"}
    },
    "id": 1
  }'

A successful response looks like:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "tools": {"listChanged": false}
    },
    "serverInfo": {
      "name": "podwarden",
      "version": "1.26.0"
    }
  }
}

Auto-generated configs in the UI

PodWarden Settings → MCP shows ready-to-copy config snippets with your actual token pre-filled. After creating or reissuing a token, the config snippet updates automatically — just copy and paste.

Access level

PodWarden has an instance-wide MCP tier switch (Settings → MCP). Each tier is on or off:

This is the only setting that restricts which tools a connected model can call. It applies to every caller alike, on both direct connections and Hub tunnel connections — a token's stored role does not change it. Changing a tier takes effect on the next direct call; if the Hub tunnel is active, saving reconnects it to re-announce the tool list. See What gates a tool call. The tools your instance offers right now: the tools your PodWarden instance offers. To see the exact list, connect a PodWarden Core to your account, or ask your AI client to run list_tool_categories.

Enabling MCP

The MCP endpoint is enabled by the stored setting mcp.enabled (off by default), or automatically when the instance is on a paid Hub plan. Turn it on in Settings → MCP. The old PODWARDEN_MCP_ENABLED environment variable no longer does anything: Core ignores it (and warns about it at boot), so setting it in .env or your compose file will not enable MCP.

Troubleshooting

"Server disconnected" in Claude Desktop

• Verify Node.js is installed: node --version
• Test the endpoint manually with curl (see above)
• Check Claude Desktop logs: click "View Logs" on the failed server entry

401 Unauthorized

• Token may be expired or revoked — check Settings → MCP
• Verify the token starts with pwm_
• Ensure there's a space between Bearer and the token

404 Not Found

• The /mcp endpoint must be routed to the PodWarden backend by your reverse proxy
• If using Caddy/nginx, add a rule to proxy /mcp to the backend (same upstream as /api/*)

421 Invalid Host header

• This happens if the MCP SDK's DNS rebinding protection rejects your hostname
• PodWarden disables this by default since it has its own auth layer
• If you see this after upgrading, rebuild the backend container