runpod-mcp

Runpod MCP

The Runpod MCP server exposes Runpod's control plane as structured tool calls, so an MCP-capable agent can manage infrastructure without shelling out. It is the same Runpod REST API that runpodctl uses — pick MCP when its tools are connected (typed params, structured errors, no shell quoting).

Connect

Connect the hosted server with your API key as a Bearer header if you also use runpodctl/flash — that one key auths the MCP and the CLIs (the 80% path):

claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/ \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

Plain OAuth ("Sign in with Runpod", via npx @runpod/mcp-server@latest add) is MCP-only — the CLIs stay unauthed, so use it only for MCP-only work. Local stdio runs the server as a subprocess with your key. Those variants + the key-vs-OAuth tradeoff: reference/connect.md. After connecting, reconnect the client (in Claude Code, /mcp) so the tools load.

Verify it's live (do this before relying on MCP): in Claude Code run /mcp — runpod should show Connected, not Needs authentication (if it's the latter, sign in there first; the bundled plugin server registers the URL but stays inert until you authenticate). Confirm a real call works by asking for list-endpoints. If the runpod tools aren't present at all, the server isn't connected — (re)run the install above, or fall back to runpodctl for this task.

Check the server version (which REST API it drives): the MCP initialize handshake returns it in serverInfo.version. /mcp in Claude Code shows it, or probe the hosted server directly:

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' \
| curl -s -X POST https://mcp.getrunpod.io/ -H "Content-Type: application/json" \
    -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $RUNPOD_API_KEY" -d @-
# → serverInfo.version e.g. "2.0.0 [RUNPOD_REST_VERSION=v2]"  (verified 2026-07-14)

The MCP server drives Runpod's REST v2 internally (RUNPOD_REST_VERSION=v2), so it handles infra correctly where the public rest.runpod.io/v1 control API is buggy — notably CPU serverless endpoints (see the runpodctl skill).

Prefer MCP or runpodctl over hand-rolled rest.runpod.io/v1 calls for creating endpoints.

Tool surface

Structured tools, grouped by resource:

• Pods — list, get, create, update, start, stop, restart, delete, stream logs.
• Serverless endpoints — list, get, create, update, delete; list workers; list releases.
• Jobs (serverless runtime) — run, runsync, status, stream, cancel, retry, health, purge queue.
• Templates — list, get, create, update, delete.
• Network volumes — list, get, create, update, delete. ⚠️ create-network-volume takes only name/size/dataCenter — it can't set the storage tier, so it always gets the data center's default. For a High-Performance volume use the console or a raw v2 REST call (POST https://v2-rest.runpod.io/v2/network-volumes with "type":"HIGH_PERFORMANCE"); see golden path 21.
• Container registry auth — list, get, create, delete.
• Catalog — list/get GPU types, list/get CPU types, list/get data centers.
• Tags — list, get, create, update, delete; attach/detach to resources.
• Billing — scoped usage/cost breakdowns (get-billing).

Delete tools (delete-template, delete-pod, …) can return isError: true with "Unexpected end of JSON input" even on success — the Runpod REST API returns 204 No Content. Don't treat it as failure; confirm with a follow-up get-/list- (a deleted resource then 404s).

Use MCP vs runpodctl

• Use runpod-mcp when the tools are connected AND the task is infra CRUD or a serverless job call the server exposes. Cap large job/log output to a file.
• Use runpodctl instead for: anything MCP has no tool for — Hub browse/deploy, send/receive file transfer, SSH key management, doctor setup, model cache — or any shell-only agent, or when the user wants a reproducible command.
• Hand pod creation to runpodctl when it needs a capability MCP's create-pod lacks: from a template (--template-id), a CPU pod (--compute-type cpu), or a multi-GPU priority list. MCP's v2 create-pod requires an image and takes a single GPU type — fine for a simple one-image/one-GPU pod, but defer the richer cases even when MCP is connected.
• Not this lane: writing/deploying your own Python (→ flash); downloading models or building/pushing images (→ companion-clis).

For concepts (pods vs serverless, GPU selection, storage), read ../runpod-usage/.

Source & docs

• Server source: https://github.com/runpod/runpod-mcp
• Package (npm): https://www.npmjs.com/package/@runpod/mcp-server
• Hosted endpoint: https://mcp.getrunpod.io/
• Docs: https://docs.runpod.io