Terminal
Terminal/Skill
Connects the Runpod MCP server to an agent and routes Runpod infrastructure tasks to the right skill for pods, endpoints, volumes and billing.
By RunPod
Works with
npx skills add runpod/runpod-plugins-official --skill runpod-mcpThe 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).
This skill does three things: it connects the server, routes each request to the journey skill that carries its procedure (Route by intent), and owns the answer contract below, which every reply follows.
For a multi-step job, read the worked example before calling tools. Tool calls are easy to issue and easy to issue in the wrong order. The verified end-to-end sequences live in runpod/golden-paths/README.md (image → template → endpoint, pod → volume → serverless, multi-region, autoscaling, monitoring). The journey skills cover procedure within one journey; the paths cover what order to do a whole job in.
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 @-
Once connected, read the server. Do not reason about its tools from memory.
/mcp in Claude Code, or tools/list. Each tool carries its
own parameter descriptions, generated from Runpod's REST v2 contract. Check there
before concluding a capability exists or doesn't. When a journey skill's tool
binding disagrees with the live tool list, the live list wins.read-guide
(start with read-guide runpod-mcp) and the runpod://guides/<id> resources. With
this plugin installed, the journey skills below are the procedure; the server's
guides are the same text for an agent without the plugin.https://api.runpod.io/v2/openapi.json, for fields beyond the tool surface.One protocol quirk worth knowing, because it looks like a bug: delete tools can return
isError: true with "Unexpected end of JSON input" even on success, since the REST
API answers 204 No Content. Confirm with a follow-up get-/list- (a deleted resource
then 404s) rather than retrying the delete.
For concepts (pods vs serverless, GPU selection, storage), read ../runpod-usage/.
send/receive file transfer, SSH key
management, doctor setup, model cache, or any shell-only agent, or
when the user wants a reproducible command.create-pod and create-endpoint take
gpu.minCudaVersion ("12.8" by default, "13.0" only for a CUDA-13 image);
create-template takes allowedCudaVersions. Without a floor the create accepts any
host CUDA version, and a modern image can land on a host too old to run it. Why 12.8
and when to use 13.0:
runpod-usage gpu-selection.create-pod
takes one GPU type; check the live schema before assuming, and watch for a _warning
on an otherwise-successful create), or for a template + CPU pod together, which
v2 does not express. Each alone is fine in MCP: templateId (each field you pass
replaces the template's whole value rather than merging) or computeType: "CPU".| The user wants to… | Journey skill |
|---|---|
| Know what GPUs/workers/endpoints exist, what fits a model, what it costs | discovery |
| Create/inspect/update/delete pods, endpoints, templates, volumes, account secrets, SSH keys, clusters; inventory of the account | lifecycle-crud |
| Stand up a serverless endpoint for a model/workload and verify it with a real job | serverless-deploy |
| Host a ComfyUI workflow (workflow.json, custom Civitai models/LoRAs) as an endpoint | serverless-deploy, then its ComfyUI reference |
| Rent/configure an interactive GPU pod; create a pod then pause/stop it for later | pod-deploy |
| Diagnose a broken/misbehaving pod (0 GPUs, CUDA, crashes, 502s) | pod-doctor |
| Operate an existing endpoint: jobs, scaling, workers, logs | endpoint-ops |
| Understand or reduce spend; billing breakdowns | cost-audit |
| Something the tools may not cover (file transfer, a command inside a Pod) | Capability boundaries below |
This interface manages infra through the Runpod MCP tools. It does NOT do:
SSH sessions, file transfer to/from pods, local image builds, model downloads
to volumes, or interactive terminals. When a task needs one of those, say
that it is not available through these tools and name the lane that does it:
runpodctl for file transfer (send/receive), SSH setup and model
uploads; SSH or the console web terminal for commands inside a Pod; the Flash
SDK for code-first Serverless deploys; the console for Pod migration. Never
improvise a fake capability or silently drop that part of the task.
Check the served tool list before calling anything a gap: account secrets and Instant Clusters were console-only once and are served tools now. The workaround for each gap, and the discipline for answering one, are in reference/api-boundary.md.
A template id, a GPU's stock or price, or a resource's state is confirmed with a list- or get- tool before you act on it, even when a guide or an earlier session named it.
Every Runpod reply follows these rules. Journey skills add journey-specific rules and report templates; they never weaken these.
Facts come from tool reads, stated as facts.
Commit; don't hedge, don't defer.
create-cluster always waits for an explicit go: never call it until the
user has seen the shape (nodes, GPUs per node, data center) and the total
hourly price from the catalog read and has said go in this conversation. A
request to create a cluster asks for that plan and its price; the create
waits for the go.Mutations bind to what this conversation created or the user named.
The final message stands alone.
Carry the work as far as the tools allow.
wait parameters) over handing the user a poll
loop; check state between holds. When a wait outlasts what the tools can
hold, report the evidenced state (what was created, what was submitted,
what the worker states show) and the recommended next step. Offering to
keep watching is fine; silently stopping mid-wait is not.Honest failure beats fabricated success.
Use only the tools you were given.
Report habits (inventory, cost, deployment reports):