---
name: runpod-mcp
description: >-
  Manage Runpod infrastructure — pods, serverless endpoints, jobs, templates,
  network volumes, container-registry auth, GPU/CPU catalog, and billing — via
  the Runpod MCP server's structured tool calls. Use when the Runpod MCP tools
  (create-pod, list-endpoints, …) are connected in this session, or to connect
  them (hosted OAuth or local npx). Prefer this over runpodctl for plain infra
  CRUD when MCP is available; use runpodctl for the terminal, Hub deploys, file
  transfer, or SSH setup.
allowed-tools: Bash(npx:*), Bash(claude:*)
compatibility: Linux, macOS, Windows
metadata:
  author: runpod
  version: "1.1.0" # x-release-please-version
license: Apache-2.0
---

# 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):

```bash
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](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:

```bash
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