# @runpod/mcp-server ## 4.12.0 ### Minor Changes - 704faa0: The hosted server now accepts an `X-Team-Id` request header and forwards it on every REST v2 request, so a Console (Clerk JWT) caller can act for a team. A malformed value is refused with HTTP 400 instead of silently running on the user's own account. The header is never sent to GraphQL or the Serverless runtime, and `deploy-hub-repo` refuses while a team is set, because it would create the endpoint on the personal account. ## 4.11.0 ### Minor Changes - 00dc801: Check every tool call against the tool's full input schema: types, enums, ranges and nested fields, not just top-level required and unknown arguments. By default this runs in shadow mode and only logs a `schema_violation` line (schema keywords and locations, never argument values), so no call that works today is blocked. Set `MCP_SCHEMA_VALIDATION=enforce` to reject an invalid call before any request is sent, with an `invalid_arguments` error naming each field's path, the problem, and the allowed values. With enforcement on, a shape error is no longer hidden behind an authentication failure. A `null` sent for an optional argument at any depth counts as omitted. - 7c58f5b: Add `exec-pod`: run one command in a running Pod's container and get stdout, stderr and the exit code back, with no SSH setup (REST v2 `POST /v2/pods/{id}/exec`). The tool description covers background jobs for long downloads, the 25-second limit, and the 404/409 answers while a new Pod starts. Resync the v2 spec from production; the new signup routes are excluded from the tool surface. ### Patch Changes - e9f7fe2: The hosted 404 loop breaker now counts and blocks only `get-pod`, which caused 519 of the 559 blocks in the last month. 404s from other tools, such as `exec-pod` retried while a new Pod is still being created, no longer count toward a block. ## 4.10.1 ### Patch Changes - 12d34ee: Treat a `null` optional argument as omitted on the hand-written tools too. Strict-schema clients such as Codex and opencode send every property, and the fix for generated tools did not reach the curated ones: `get-job-status` and `runsync-endpoint` rejected `wait: null` with a 400, `set-endpoint-gpus` rejected every null GPU field (`gpuIds`, `gpuCount`, `minCudaVersion` and the rest) so it could not be called at all, and `run-endpoint` and `runsync-endpoint` forwarded `webhook: null`, `policy: null` and `s3Config: null` into the job body. A null required argument is still reported as missing. - 568328f: `stream-pod-logs` and `stream-worker-logs` no longer fail with "did not respond before the request deadline" when the log stream's headers take longer than `maxWaitMs`. Headers now get their own 10-second budget, and `maxWaitMs` measures how long the open stream is read. Snapshots are also capped at 32,000 serialized characters so they fit within MCP clients' tool-output limits: a capped snapshot keeps its leading lines, cuts only between timestamps where it can, clips oversized lines (measured after JSON escaping), and sets `truncated: true`. The tool descriptions now say that `since` is exclusive and replays container lines only. - 1cb0082: Record why a hosted tool call failed. Failed calls now carry `error_class` (`capacity`, `balance`, `conflicting_args`, `validation`, `auth`, `permission`, `not_found`, `rate_limited`, `timeout`, `server` or `other`) on the anonymous analytics event, from a fixed list and never the upstream message. A 400 for "no instances currently available" now gets the capacity hint, the same as "no longer any instances available". - 27fe395: Update `@runpod/plugin-knowledge` from 1.9.0 to 2.0.0, so `list-guides` and `read-guide` serve the latest plugin guides. Plugin-knowledge 2.0.0 renames the journey guides with a `runpod-` prefix (`pod-doctor` is now `runpod-pod-doctor`). The server instructions name the new ids, and `read-guide` and `runpod://guides/` resource reads still accept the old ids through the bundle's alias map. Update run: https://github.com/runpod/runpod-mcp/actions/runs/42194967234 ## 4.10.0 ### Minor Changes - ba8ae08: Redact email addresses in ALP submissions, non-ASCII ones included, as `[redacted:email]`, counted in `redactions`. Runpod Pod SSH logins (`@ssh.runpod.io`) and the `git@` user of an SSH remote are kept. `SCRUB_VERSION` is now 6 and is exported from `@runpod/mcp-server/alp`. The ingest endpoint keeps `tool` only when it is shaped like a tool name (`^[A-Za-z0-9_-]{1,64}$`) and drops anything else, as it does an off-enum `severity`, and answers a write the sink refused at its cap (`capped: true`) with `recorded: false` and the do-not-retry note. - 80d0d1f: Pin `@runpod/plugin-knowledge` to an exact version, checked before each release for npm provenance built in `runpod/runpod-plugins-official`, and leave the concept rules listed in `KNOWLEDGE_HIDDEN_RULES` (comma-separated rule ids) out of `lookup-concept` and `search-concepts`, citations included, so the hosted server can withdraw a rule before the knowledge release that deletes it ships. An id the bundle does not hold is logged at startup. - ba8ae08: Resync the vendored v2 OpenAPI spec with production as of 2026-11-05 and regenerate the SDK schema and the tools. Adds 31 tools: organization groups, roles, invites and member updates and removal, cost centers, and endpoint cold-start, request and worker metrics. A pod's mounts now take up to 4 network volumes and 1 global volume. The `filters` query parameter on the pod, cluster, endpoint and network volume list routes is left out until the client can send JSON query parameters. ### Patch Changes - 017cdc3: Update `@runpod/plugin-knowledge` from 1.8.0 to 1.9.0, so `list-guides` and `read-guide` serve the latest plugin guides. Update run: https://github.com/runpod/runpod-mcp/actions/runs/41610964582 ## 4.9.1 ### Patch Changes - ad7445d: Drop the `node-fetch` dependency. Only the hosted entry point used it, and that now lives outside this repository. ## 4.9.0 ### Minor Changes - 6b0400d: Export the hosted-service surface as `@runpod/mcp-server/hosted` (`handleMcpRequest`, `getBaseUrl`, `handleAlpSubmit`, `handleAlpJournalRead`, `handleSearch`, `DIRECTORY_PATH`) and the ALP contract the Convex sink shares as `@runpod/mcp-server/alp` (`ALP_ROUTES`, `ONCE_PER_ACCOUNT_ROUTES`, `isOncePerAccountRoute`, `scrubSubmission` and friends), so an HTTP host and its Convex functions can build on the package instead of `src/`. ## 4.8.0 ### Minor Changes - 8f53070: Export the server profile module as `@runpod/mcp-server/profile` (`ServerProfile`, `DIRECTORY_PATH`, `DIRECTORY_TOOLS`, `profileForPath`, `directoryIncludes`, `directoryOmittedInputs`) so an HTTP host can resolve the directory profile from the package instead of reaching into `src/`. - 4c51d2a: Resync the vendored v2 OpenAPI spec with production as of 2026-10-27 and regenerate the SDK schema and the tools. Adds `list-organization-users` and `get-organization-user`, documents the 413 response on list operations, and requires a non-empty mount `path`. ### Patch Changes - 2658966: Record the tool surface on each `runpod_mcp_tool_call` analytics event as `profile` (`directory` for `mcp.runpod.io/directory`, `default` otherwise), so directory traffic (the ChatGPT plugin and the Claude connector) can be told apart from custom connectors on `/`. - f3efa2e: Avoid suggesting immediate retries when a timed-out or failed create may already have completed upstream. ## 4.7.0 ### Minor Changes - 506e813: Resync the vendored v2 OpenAPI spec with production as of 2026-10-26 and add `list-audit-logs` for reading the account audit trail with filters and pagination. `list-pods` no longer returns live utilization or the direct SSH mapping; use `get-pod` to read those fields for an individual Pod. Update run: https://github.com/runpod/runpod-mcp/actions/runs/40308747009 ### Patch Changes - e669dca: Accept Cursor's OAuth callbacks on the hosted server (`cursor://anysphere.cursor-mcp/oauth/callback` and the `https://www.cursor.com/agents/...` and `/bot/...` web callbacks), so Cursor cloud agents and bot integrations can sign in with Runpod. `/register` now rejects a client up front (`invalid_redirect_uri`) when none of its callbacks can be used, and both errors explain how to connect with an API key instead. The install wizard and stdio `search-docs` now default to `https://mcp.runpod.io/` instead of the legacy `https://mcp.getrunpod.io/`. - d527e91: Trim the `/directory` server instructions to one sentence listing what the tools cover, without naming secrets, SSH keys or registry credentials. OpenAI's plugin scan held the longer version for review. - b7c0525: On `/directory`, stop showing credentials: schema examples that name or hold one (such as `{"JUPYTER_PASSWORD": "hunter2"}` on the `env` field) are dropped, and the secret and registry-credential tools (`list-secrets`, `get-secret`, `delete-secret`, `list-registries`, `get-registry`, `delete-registry`) are left out. OpenAI's plugin review rejected the submission for soliciting access credentials. The default surface is unchanged. - 08ddd89: Point both MCP initialize profiles at the Runpod REST API v2 (the OpenAPI spec at https://api.runpod.io/v2/openapi.json and the reference at https://docs.runpod.io/api-reference-v2/overview) for operations outside their tool lists. The default profile permits read-only GET calls when `RUNPOD_API_KEY` is already in the environment and the response cannot expose secret environment values, without accessing client credential stores or making writes outside the MCP tool approval flow. The directory profile names no credentials and presents the reference as informational. - 4b8b68e: Address OpenAI plugin review findings. On `/directory`, `pod-action` is replaced by separate `start-pod`, `stop-pod` and `restart-pod` tools (terminate is `delete-pod`); the default surface keeps `pod-action`. `update-template` is now marked destructive, since it overwrites the image, env and registry and can make a template public. - 0f519bf: Drop the non-portable `pattern` (a `\p{Z}` Unicode property escape) from the `name` argument of `create-global-volume` and `update-global-volume`. OpenAI's plugin tool scan rejected the schema; the API still enforces the rule and the field description states it. - a274524: Generate the tools from the TypeScript SDK's patched copy of the v2 spec, now that the SDK lives in this repository. Argument examples use a placeholder AWS account ID and `changeme` instead of `hunter2` as the example Jupyter password, several argument descriptions drop internal or version-relative wording, and input schemas no longer carry the `x-enum-varnames` code-generation hint. Resync the shared spec with production after rebasing, adding the audit logs operation to the SDK's generated types. ## 4.6.0 ### Minor Changes - 34bb467: Add a directory profile at `/directory` (hosted: `https://mcp.runpod.io/directory`) for app directories such as Anthropic's connector directory. It lists tool descriptions that only say what each tool does, full argument schemas, and a factual briefing, and leaves out the guide tools, `describe-tool`, the tools that take a secret or password as input (`create-secret`, `update-secret`, `create-registry`) and the S3 credentials argument of `run-endpoint` and `runsync-endpoint`, the agent-learning tools, the referral ask and the guide resources; its analytics record which tool ran but no argument values. A tool appears there only once it is classified in `DIRECTORY_TOOLS` per `specgen/DIRECTORY_POLICY.md`; tests fail on an unclassified tool or a directory tool that takes a credential. The default surface at `/` is unchanged. Separately, every profile now redacts secret-looking environment values (passwords, tokens, API keys) in tool results, keeping `{{ RUNPOD_SECRET_ }}` references. ### Patch Changes - 02a8f0c: Correct the MCP annotations on tools whose HTTP method understated what they do, so hosts gate them on a human. `update-endpoint`, `update-pod`, `update-secret`, `set-endpoint-gpus` and `retry-job` are now marked destructive: each can clear settings it was not sent, restart a container, overwrite a value that cannot be read back, or remove prior job output. `stream-job` is no longer marked read-only, because the stream hands out each chunk once. `create-secret` and the field-setting updates (`update-cluster`, `update-network-volume`, `update-global-volume`, `update-template`) are now marked idempotent. - 8cfdf83: Accept ChatGPT's OAuth callbacks on the hosted server: the stable `https://chatgpt.com/connector_platform_oauth_redirect` and the per-connection `https://chatgpt.com/connector/oauth/{callback_id}`, so ChatGPT and Codex can sign in with Runpod. - e39441f: Declare `type: object` on the `body` argument of the create and update tools whose request body is an `allOf` composition (`create-cluster`, `create-endpoint`, `create-pod`, `create-template`, `update-endpoint`, `update-pod`, `update-template`), so directory reviews that read top-level argument types see one on the full schema served at `/directory`. On `/directory`, every tool that takes a request body (`body`) now ends its description with a link to the Runpod REST API v2 reference, which the Claude directory portal suggests for these tools. - 31b1c7d: Every top-level tool argument now declares its `type` (arguments that referenced a shared definition, like `bucketSize`, `cloud` and several request bodies, carried only the reference), and each tool's title is also sent as `annotations.title`. Both were flagged by Anthropic's connector directory review. - 77c2af7: Serve OpenAI's domain-verification token at `/.well-known/openai-apps-challenge` on the hosted server, so the OpenAI plugin portal can verify `mcp.runpod.io`. ## 4.5.0 ### Minor Changes - 83bffb7: Hosted server: a new optional ALP tool, `report_how_user_found_runpod`, asks the agent once per account how its user ended up on Runpod: the kind of work (`useCase`) and why Runpod came up (`source`: `searched`, `user_named`, `recommended`, `other`), or that it has no such context (`noContext`). It collects categories and at most a short generic note, never the user's own words. The ask rides in the `initialize` instructions; on each `initialize` with a resolved account the server checks the storage sink and omits the ask once the account has answered (a failed lookup keeps the ask), and the sink keeps the first answer per account, with the server answering `already_submitted` to any later one. Answers are stored with the other ALP submissions under their own `referral` route, with the note capped at 200 characters, and scrubbed like every other submission. Absent on local stdio and whenever the sink is not configured, like the other ALP tools. - ff02fdb: Every tool now carries a human-readable `title` in tools/list (for example `List GPU types` for `list-gpu-types`), so hosts can show readable names and the server meets directory review requirements. Generated tools derive the title from their name, with overrides in `specgen/generator-config.yaml`; curated tools declare their own. ### Patch Changes - da524df: GraphQL errors that Runpod returns on an HTTP 200 now fail the tool call with a status taken from the error code (401, 403, 400 including Runpod's own `RUNPOD` input errors, otherwise 502) instead of 200, so agents get the matching recovery hint. A non-array `errors` field no longer crashes the call. - d075b00: Network failures reaching the Runpod API (DNS, connection refused, unreachable host, TLS errors, or a connection dropped mid-request) now come back as tool errors with the underlying `cause` code and a recovery hint, instead of escaping as an opaque JSON-RPC `-32603 fetch failed`. Failures where the request never reached Runpod say a retry is safe; a dropped connection says a write may have been applied and to check with a get- or list- tool before calling again. - 6a577ea: Update `@runpod/plugin-knowledge` from 1.7.4 to 1.8.0, so `list-guides` and `read-guide` serve the plugin's 1.8.0 skills and guides, including the new `runpod-build-template` skill. ## 4.4.0 ### Minor Changes - a58f9f1: New `search-docs` tool: searches Runpod documentation, curated support knowledge, the Runpod blog and runpod.io through the runpod-assistant knowledge index, and returns ranked passages with source URLs. The hosted server searches with its own service key and retries the index's capacity rejections with jittered backoff. Local installs call the hosted `POST /api/search` with the user's API key. ### Patch Changes - 4b53720: Hosted server: `tools/call` now answers as `application/json` too, so the CDN compresses tool results; only tools that hold their response open (`runsync-endpoint`, `get-job-status`, `stream-job`, `stream-pod-logs`, `stream-worker-logs`, `deploy-hub-repo`) keep SSE, declared with `CuratedTool.holdsResponse`. ## 4.3.0 ### Minor Changes - 39d296f: Add `describe-tool`, which returns any tool's full definition, and list the tools with large request bodies (create/update endpoint, template and cluster, update-pod, create/update secret) with their call shape only: the top-level arguments with their types, nested objects collapsed. What each tool accepts is unchanged: the full schema still gates every call and is one `describe-tool` call away. Every client handshake carries about a quarter fewer bytes. - 40d9745: Resync the vendored v2 OpenAPI spec with production and update `@runpod/typescript-api-sdk` from 0.2.0 to 0.3.0 and `@runpod/plugin-knowledge` to 1.7.4. Adds the `list-global-volumes`, `get-global-volume`, `create-global-volume`, `update-global-volume`, `delete-global-volume` and `get-organization` tools, `global` mounts on `create-pod`, `mounts` on endpoints, and `pagination` on `list-clusters` and `list-network-volumes`. Those two list tools now return one page (default `limit` 1000); follow `pagination.nextCursor` until `hasNextPage` is false. `tools/list` shrinks from 97 KB to 87 KB. `create-pod` is listed by its call shape, like `create-endpoint`; `describe-tool` serves its full schema. Tool annotations leave out `idempotentHint` when it is `false`, the MCP spec default. A description override on a composed schema is no longer repeated on each `allOf` member. - d2d12ef: The installer runs without prompts and supports opencode and Pi. `npx @runpod/mcp-server@latest add --client ` configures the named clients with no prompts (`--hosted` by default, `--local` to read the key from `RUNPOD_API_KEY`), `remove --client ` undoes it, and `add --list` shows which clients are detected and where each config lives. Run with no `--client` and no terminal, the installer now exits 2 and says nothing was configured, instead of exiting 0 having written nothing. Exit codes: 0 configured, 1 a client failed, 2 bad usage. `--help` and `--version` work at the top level and on `add`/`remove`. New clients: opencode (`~/.config/opencode/opencode.json`, or an existing `opencode.jsonc`, under `mcp` with opencode's `remote`/`local` entry schema) and Pi (`~/.pi/agent/mcp.json`, honouring `PI_CODING_AGENT_DIR`). Both config formats were checked by running opencode 1.19.0 and Pi 1.2.0 against the files the installer writes. ### Patch Changes - 37dfc9b: Generated tool argument descriptions are compacted to what an agent needs: leading sentences up to a cap, constraints kept, REST paths replaced by tool names, response prose and status codes dropped. `tools/list` shrinks by roughly a fifth; a byte-budget test keeps it from regrowing. - a388ccb: Hosted usage analytics now record which guide or concept was requested: the `id`, `concept`, `query`, `kind` and `limit` arguments of `list-guides`, `read-guide`, `lookup-concept` and `search-concepts`. `read-guide` events also carry `guide_kind` (skill, reference or golden-path). Guide resource reads (`resources/read`) are recorded as a new `runpod_mcp_resource_call` event with the guide URI, or `unknown` when nothing matched. Other tools still send no arguments, stdio still sends nothing, and `X-Runpod-Analytics: off` still opts out. - a388ccb: The hosted server now breaks 404 loops: once a signed-in caller gets 50 404s from one tool within 10 minutes, that tool answers that caller with a retryable 429 for 1 hour. Counts live in the existing Convex sink, successful calls never touch it, and any sink failure lets calls through. Local (stdio) installs are unaffected. Each block emits one `runpod_mcp_loop_blocked` analytics event, and the 429s it serves carry `blocked_by: not_found_loop`. - 19cae9f: Hosted server: every request except `tools/call` now answers as `application/json` instead of an SSE stream, so the CDN compresses it (`tools/list` drops from ~65 KB to ~13 KB on the wire per handshake). `tools/call` keeps SSE because clients read it under their long stream timeout and some tools hold a response longer than the JSON request timeout. The per-request `mcp_request` log line is sampled (`MCP_REQUEST_LOG_SAMPLE_RATE`, default `0.1`; `MCP_VERBOSE_LOGS=true` logs all) and now records the response status, duration, JSON-RPC method (with tool name), the client's `initialize` name/version, user agent, and hashed caller key and address, so traffic can be attributed by client. - c55d61a: Hosted server: the request body is validated once with the SDK's JSON-RPC schemas; `prefersJsonResponse` and `summarizeRpc` take the parsed messages, and the log line reports a client name/version only for a spec-valid `initialize`. - 6efc1b3: Accept the argument shapes strict-schema clients send. Clients such as Codex and opencode must send every property, so an optional query filter they mean to leave out arrives as `null`, `""` or `[]`. Those are now treated as omitted: `cudaVersions: []` next to `minCudaVersion` on `get-gpu-type` and `list-gpu-types`, `lastN: null` next to an explicit range on the billing tools, and `cursor: ""` on a first page no longer fail upstream. Numbers and booleans a client stringified inside a request body (`disk: "20"`, `workers.max: "1"`) are converted back where the body schema asks for one; string fields stay strings. A 400 hint now names the upstream cause instead of always saying "Input shape mismatch": no capacity for the requested hardware, no account balance, or two conflicting arguments. Real validation failures (a 422, or field errors) keep the shape hint. ## 4.2.0 ### Minor Changes - 4865aed: Tighten what the server tells a connecting agent. The instructions now say that for work done with these tools the journey playbook is the procedure, whether it comes from the plugin's `runpod-mcp` skill or from `read-guide`; the plugin's other skills stay the lane for the CLIs, image builds and golden paths. A resource the user names by id is in scope for the change they asked for and is deleted only when they ask for the delete, and `create-cluster` waits for the user's go on the quoted shape and total hourly price. Jobs are submitted with `run-endpoint` and waited on with `get-job-status`; `runsync-endpoint` is for a warm endpoint and a fast job. The 402 hint points at `list-billing`, and the 403 hint says a permission error on a resource the agent did not create is final. Tool descriptions: `create-cluster` prices the whole shape (pods times GPUs per pod) and waits for the go; `create-endpoint` describes the CPU choice next to the GPU one; `update-endpoint` puts `idleTimeout` under `workers` and states that `gpu.pools` and `gpu.excludedTypes` are one selection; `delete-endpoint`, `delete-pod`, `delete-cluster` and `delete-secret` allow the one resource the user asked to delete by id. - 6ffb28e: The journey playbooks now come only from `@runpod/plugin-knowledge`, bumped to 1.7.1. The server no longer keeps its own copy under `runpod://skills/`: an agent loads the plugin's `runpod-mcp` skill, or `read-guide runpod-mcp` without the plugin, and that routes it to the journey guides (`discovery`, `lifecycle-crud`, `serverless-deploy`, `pod-deploy`, `pod-doctor`, `endpoint-ops`, `cost-audit`). `resources/list` serves the plugin guides as `runpod://guides/`. The instructions and the `ask_question` text point at `read-guide` instead of `runpod://skills/`. The instructions also tell an agent whose instructions look out of date to reconnect the server (or ask the user to), since reconnecting re-runs initialize and delivers the current instructions and tool list. ## 4.1.0 ### Minor Changes - 1d049b6: Serve the official Runpod plugin's guides and concept graph: `list-guides`, `read-guide`, `lookup-concept` and `search-concepts`, plus each guide as a `runpod://guides/` resource, from the `@runpod/plugin-knowledge` package. - 09a565a: `list-templates` now returns 20 templates per page by default instead of the full list. Follow `nextCursor` to see the rest. Resync the vendored v2 OpenAPI spec with production. Adds five account-secret tools (`list-secrets`, `get-secret`, `create-secret`, `update-secret`, `delete-secret`) and refreshes the schemas for pods, endpoints, templates, registries, and clusters — most visibly the `cursor`/`limit` query parameters and `pagination` response block the API now serves on its list endpoints. `list-endpoints` and `list-templates` now page on the server: `limit` and `cursor` go to the API, and `pagination` returns its `nextCursor` and `hasNextPage` plus `returned`. `list-endpoints` drops the old client-side `total`, `offset`, and `truncated` fields, which only counted one server page. Requires `@runpod/typescript-api-sdk` 0.2.0. ### Patch Changes - 531ecb0: Serve MCP tool annotations. Every tool now advertises `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` in `tools/list`: generated tools derive them from the HTTP method they wrap, so they cannot drift from the spec, with generator-config overrides for operations that delete through a POST or PUT (`pod-action`, `update-ssh-keys`), and the curated overlay declares them per tool. Hosts can auto-approve reads and gate deletions, cancels, and queue purges on a human. ## 4.0.0 ### Major Changes - 57b3973: Require Node.js 20 or newer and add the published Runpod TypeScript API SDK as the REST client foundation. Share deadline enforcement across REST, runtime, GraphQL, and log readers; preserve per-caller credentials and bounded polling. Update GPU selection with a sparse REST PATCH and isolate queued-job diagnostics by caller. Pin the bundled TypeScript API SDK to 0.1.1. Reject null required arguments and invalid endpoint IDs before issuing requests. - 57b3973: Serve the same REST v2 generated tools and skill resources over HTTP and stdio. Remove the legacy v1 fallback, hand-written tool surface, and package tools export. See specgen/old-mcp-tools.yaml for renamed tools and pod-action replacements. Include argument checks, compact lists, bounded log snapshots, upstream retry guidance, caller tracking, and opt-in hosted analytics. The REST SDK is bundled into both entrypoints. Remove the repository Dockerfile, Smithery manifest/install instructions, and bundled Cursor configuration. Use the hosted MCP URL or the published npm CLI, configured in your MCP client, instead. The install wizard verifies keys against REST v2 and honors RUNPOD_API_BASE_URL; retired REST host variables no longer disable credential preflight. ### Minor Changes - 57b3973: Add hosted-only feedback, question, and private journal tools when a storage sink is configured. Contributions are optional and scrubbed for secrets. Scope journal reads to the authenticated account, bound reads, verify storage confirmation, and reject malformed storage requests. Local stdio does not advertise these tools. Redact nested YAML/Compose secrets, Hugging Face tokens, and URL query credentials. Clarify that journals are not published to other accounts and Runpod stores submissions for review. ### Patch Changes - 57b3973: Fix two secret-redaction leaks in ALP submission scrubbing, and replace the config-assignment regex with an explicit scan. `password: p&ss#word123` and `password=abc&def` were truncated at the `&` and everything after it was stored in plaintext. A sensitive assignment nested inside a non-sensitive value was skipped entirely, so `https://host/?password=secret` passed through untouched. Values now keep `&` and `#` unless the key sits in a URL query string, where those characters really do bound the value, and the scan resumes inside a non-sensitive value instead of past it. Unbalanced and unterminated quotes no longer disable redaction. Scrub version is now 5. ## 3.4.0 ### Minor Changes - bae0e5d: Expose the REST v2 CUDA host constraints on create-pod, create-endpoint, and update-endpoint (`allowedCudaVersions`, `minCudaVersion`, nested under `gpu.*` on the wire per rphttp2 2.9.0), support CUDA-only endpoint patches without resending `gpuPoolIds`, warn when a `gpuPoolIds` update clears GPU-type exclusions set elsewhere, and add the `minCudaVersion` availability filter to list-gpu-types. Requires a server running rphttp2 2.9.0 or later for the new fields. ## 3.3.0 ### Minor Changes - a62a663: `list-gpu-types` and `get-gpu-type` now always send `product` with their `include=AVAILABILITY` catalog requests, via a new optional `product` parameter (`POD` | `CLUSTER` | `SERVERLESS`, default `POD`). Availability is product-specific — the same GPU can be scarce for Pods and plentiful for Serverless — and the next v2 API release makes `product` required with availability (400 without it), so this keeps the availability lookups working and lets agents ask for the context they actually deploy to: pass `SERVERLESS` when picking a GPU for an endpoint, `CLUSTER` for Instant Clusters. When `includeAvailability` is false, `product` is not sent (the API also rejects `product` without `include=AVAILABILITY`). The CPU catalog tools never request availability, so they are unaffected. - 7074c87: Add an `sshPublicKey` parameter to `create-pod` for full SSH access (#73), and fix v2 GPU pod creation failing without an explicit `gpuCount`. The REST API has no SSH switch yet (the console and runpodctl set it via GraphQL `startSsh`), so Pods created through the MCP got a valid-looking port-22 mapping but no authorized key — direct SSH, SCP, SFTP, and rsync all failed. Passing `sshPublicKey` now merges the key into the `PUBLIC_KEY` environment variable and ensures `22/tcp` is exposed, which any image honoring the `PUBLIC_KEY` convention (all runpod/\* official images) turns into a running sshd with the key installed. Template deploys extend the template's ports and env rather than replacing them, and an existing `PUBLIC_KEY` is appended to rather than overwritten. The key is validated before the Pod is created, because an unusable value would otherwise produce a Pod that looks SSH-ready and is not: `22/tcp` exposed, junk in `PUBLIC_KEY`, and a reply reporting SSH as configured. Rejected with a 400: a private key in any format (PEM in any case, or a PuTTY `.ppk`, which contains neither the words "private key" nor a public key line), a file path or SHA256 fingerprint passed instead of the `.pub` file's contents, a bare base64 blob with no key type, and an empty or whitespace-only value (omit the parameter to create a Pod without SSH). Accepted keys are normalized to one key per line with CRLF stripped, since a stray carriage return corrupts the `authorized_keys` entry it lands on. Error messages never echo the rejected value, which may itself be secret. `create-pod` also now rejects a `gpuCount` below 1 or with a fractional part, which the v2 API answers with an opaque 422. Separately, the v2 pod-create mapper omitted `gpu.count` when the caller passed no `gpuCount`, trusting the spec's documented server-side default of 1. In practice the scheduler matches zero machines without it and every create fails with a misleading "no instances available" error (verified live against both v2 hosts). The mapper now always emits `count`, defaulting to 1. - 9176c78: Clamp long-poll tool budgets on the hosted HTTP server, which runs behind a 60-second Vercel function limit. `runsync-endpoint` waited 90 seconds by default (300 via `wait`) and `stream-job` polled for up to 5 minutes, so for a slow job the function was reaped mid-flight: the caller got a bare 504 and every chunk collected so far was discarded. Over HTTP, `runsync-endpoint` now sends a `wait` capped at 45000 ms — a job that outlives it comes back as a job ID plus a non-terminal status to poll with `get-job-status`. `stream-job` stops after 45 seconds over HTTP and returns what it has with `pollingTimedOut: true`; `/stream` drains what it hands out, so calling again resumes rather than replaying. Its HTTP polls also send `wait=1000`, since the server otherwise holds an empty response for 10 seconds and the budget is only checked between polls. Both tool descriptions are now written per transport, so a caller is told the one budget that applies to them and where to go for more — `run-endpoint` + `get-job-status`, or the runtime API directly. The stdio server has no deadline and is unchanged. - f20d987: Give every outbound request a client-side deadline — every tool call, the OAuth handshake on the hosted server, and the install wizard's key check. node-fetch applies no timeout of its own, so a Runpod host that accepted the connection and then went silent — a wedged worker, a load balancer holding the socket — left a tool call pending forever, and on the hosted server that ended as a bare 504 when Vercel reaped the function at its 60s limit. Requests now abort after 30 seconds with a named `RequestTimeoutError` naming the API that went quiet, the deadline it was given, and what to do next. `runsync-endpoint` is the one call that legitimately asks the server to hold a connection open, so it derives its deadline from the `wait` it requested (the server's own 90-second default when `wait` is omitted) rather than being truncated. Successful tool output is unchanged. On the hosted transport the cap is a single budget for the whole invocation rather than a fresh allowance per request, because several tools make more than one call — `get-job-status` adds a queued-job diagnosis, `deploy-hub-repo` and `set-endpoint-gpus` read before they write, `update-endpoint` reads the current scaler before patching it — and two full deadlines back to back outlived the platform even with each one bounded. Each request is clamped to what is left, so a stall anywhere in a handler surfaces as the named error instead of a 504. The queued-job diagnosis, which only decorates a status that is already in hand, is bounded at 5 seconds so it cannot spend a budget the reply itself needs. `stream-job` bounds each poll by the wait the server was asked to hold rather than by its whole budget. A deadline set to the budget meant one wedged socket consumed the entire run in a single attempt — 45 seconds on the hosted server, five minutes on stdio — so the loop's retry path never ran and a stall returned nothing at all. Each poll now gets the hold plus a round trip, which both clears a reply already in flight and leaves the budget room to reconnect; a run that ends on the budget reports `pollingTimedOut` with the last error rather than discarding it. The hosted OAuth routes are bounded too. `/token` polls the flash backend for an approval, and one silent socket there hung the whole handshake until the platform reaped it — the worst place for a blank error, since the user has no credential yet to retry with. Each backend call now has its own 10-second deadline (override with `MCP_FLASH_TIMEOUT_MS`), never exceeding what is left of a 45-second poll budget, and a stall is reported as a named error naming the operation, the host and the deadline. The `runpod-mcp install` wizard's key verification gets the same treatment, so it can no longer sit at "Verifying…" indefinitely. A timed-out GraphQL read is also no longer described as a possible write. The advice keys off the HTTP method and GraphQL is always POST on the wire, so `list-gpu-types` timing out used to tell the agent the call may have landed and to "check with the matching list-/get- tool first" — which is the tool that just failed. Only actual mutations carry that warning now. ### Patch Changes - 2b6480d: Refuse the standalone GET SSE stream with 405. The HTTP server is stateless and never sends server-initiated messages, so the GET "listen" stream has nothing to carry — but the SDK accepted it anyway and held the response open with nothing to send until the platform's maxDuration killed it, at which point every connected client immediately re-opened it. On the hosted deployment that loop was ~1.1M hung requests per day (90% of all traffic), each ending in a 60-second timeout, and it dominated the serverless bill. GET now gets the spec's answer for a server without an SSE stream: 405 Method Not Allowed with an `Allow: POST, DELETE` header and a JSON-RPC error body, before any auth work — a 401 there would send OAuth clients into a pointless re-auth flow. Clients per the MCP spec treat the 405 as "no server-initiated messages offered" and continue POST-only; tool calls are unaffected. - 674fa2c: Fix Claude Code detection and registration in the install wizard on Windows (#56). Detection used the POSIX-only `command -v claude` plus three POSIX install paths, so Claude Code was undetectable on a standard Windows install. Windows now probes `%USERPROFILE%\.local\bin\claude.exe` (native installer) and `%APPDATA%\npm\claude.cmd` (global npm), and registration resolves the real entrypoint from the installed package manifest instead of running the `.cmd` shim through `cmd.exe`. Candidates are canonicalized and confined to their standard install roots, a PATH result resolving into the current project is rejected, and Claude Code is spawned with `PATH`, `COMSPEC`, `PATHEXT`, `NODE_OPTIONS`, and `NODE_PATH` sanitized, so nothing a project directory can plant receives your API key. Custom npm prefixes and redirected roaming profiles are still not auto-detected; when Claude Code is not found, the wizard now prints the exact `claude mcp` command to register or remove the entry yourself. Claude Code add and remove are now verified against its own `.claude.json` rather than the CLI exit code, which reports success for writes it never made. Re-running the wizard over an existing entry now says the entry was left unchanged instead of printing a bare success, since the CLI does not update it and a rotated API key would otherwise look applied. An entry shadowed by a local-scope one is called out with the command to clear it. For the clients that own a JSON config, an edit that would leave the file unparseable — or land in a duplicated server block the client does not read — now fails with the original file untouched instead of reporting success, and validity is judged by the parser each client actually ships (Claude Desktop is strict JSON, Cursor and VS Code accept JSONC, Windsurf's tolerance is unverified and disclosed rather than assumed). Claude Desktop on Linux and VS Code now honour `XDG_CONFIG_HOME` instead of writing where those clients never read, an empty or relative `APPDATA`/`XDG_CONFIG_HOME` no longer resolves a config path against the current directory, configs this wizard creates are `0600` because they hold a plaintext API key, and a key taken from the environment is trimmed. ## 3.2.0 ### Minor Changes - 2fb68de: Default REST v2 base URL is now `https://api.runpod.io/v2` (the documented canonical host) instead of `https://v2-rest.runpod.io/v2`. Both hosts serve the same API; deployments that pin `RUNPOD_REST_V2_API_URL` are unaffected. Server instructions updated to match. - 773a4ce: Add `get-capacity`: GPU capacity across host CUDA versions as one matrix call. Agents picking an endpoint's `allowedCudaVersions`/`minCudaVersion` (or diagnosing a capacity-starved endpoint) previously had to reverse-engineer per-version stock by calling the GraphQL `gpuTypes.lowestPrice` query once per CUDA version — an undocumented idiom nobody discovers organically. The default mode returns, per GPU type, overall stock plus AVAILABLE/UNAVAILABLE per host-reported CUDA version in a single credential-free catalog query; passing `cudaVersions` deep-probes those versions instead, returning graded stock (High/Medium/Low/Out) and the lowest on-demand price per version. Nothing is hidden by default — out-of-stock versions appear as explicit `Out` cells (set `includeUnavailable: false` to drop no-stock GPUs), and a transiently failing probe reports a per-version `probeErrors` entry instead of failing the whole call. Works on both v1 and v2 APIs — both use the public GraphQL catalog, since the v2 REST catalog's CUDA support is a `minCudaVersion` floor filter on availability, not the exact per-version breakdown, graded stock, or per-version pricing this tool returns. - 14b1f88: Add server instructions (sent in the `initialize` response) pointing agents at the machine-readable API contracts: the REST v2 OpenAPI spec at api.runpod.io/v2/openapi.json and the GraphQL schema reference at graphql-spec.runpod.io. The MCP tools are curated projections of the underlying APIs; this gives agents a discoverable escape hatch when a tool doesn't expose the field or parameter they need, instead of a dead end. Also moves the `capabilities` object to the `ServerOptions` argument of the `McpServer` constructor, where the SDK actually reads it. ### Patch Changes - 58c1218: `create-pod` now returns a clean local 400 when `name` is omitted on a v2 GPU create without a `templateId`, matching the v2 spec (`CreatePodRequest` requires `name`) instead of surfacing the API's raw 422. Template deploys (name inherited from the template) and CPU pods (routed to v1) are unaffected. - cd52f94: Surface HTTP-level GraphQL failures by status instead of as parse errors. The GraphQL helper (behind `list-gpu-types`, `list-data-centers`, `list-hub-repos`, `list-public-endpoints`, `deploy-hub-repo`, and `set-endpoint-gpus`) previously called `response.json()` unconditionally, so a 429 or 5xx returning an HTML error page surfaced as an opaque `Unexpected token '<'` parse error. Non-OK responses now throw the same `HttpError` as the REST client — status and body named, with the `RateLimit` wait hint on 429 — completing the treatment the REST client received. A non-OK body that still carries a GraphQL `errors` array keeps the readable GraphQL message as an `HttpError` with the status attached (`Runpod GraphQL Error: 400 - `), except on 401/429 where the re-auth and rate-limit hints take precedence. The 401 re-auth hint is now applied only by call sites that actually sent a credential (REST, authed GraphQL, the SSE log reader) — the credential-free public GraphQL path no longer advises re-authenticating for a 401 that cannot be about the caller's API key. `HttpError` messages now also cap embedded bodies at 2 KB (`.body` keeps the full text), so a large proxy/WAF error page can't flood an agent's context. - deae681: Make 429s actionable. A bare "rate limit exceeded" invites an immediate retry — the worst possible agent response. On a 429 from the REST or serverless client, the error now names the exhausted quota window and how long to wait, read from the API's `Retry-After` and `RateLimit` headers, e.g. `(rate limited — the hour quota is exhausted; wait ~29 minutes (1724s) before retrying, and pace bulk operations)`. Several windows can report zero remaining at once, so the hint reports the longest wait either header justifies rather than the first or the nearest — answering a 30-minute lockout with "retry in 12s" is the failure this exists to prevent. When part of the header couldn't be read, the wait is qualified "at least" rather than presented as the answer. Falls back to generic back-off guidance when neither header is usable, as on the v1 REST API, which sends neither. The log-streaming tools, which build their own error, carry the same hint. GraphQL-backed tools (catalog, hub, public endpoints, endpoint GPUs) are unchanged — that helper doesn't inspect the response status yet. `HttpError.status`/`.body` are unchanged for programmatic callers. ## 3.1.0 ### Minor Changes - 259241d: Enforce PKCE (S256) in every hosted OAuth flow. `/authorize` rejects missing, malformed, or non-S256 challenges before issuing a code and forwards a valid challenge to the flash backend. `/token` requires a valid, matching `code_verifier` before returning the minted key; missing PKCE state, `plain`, and non-matching verifiers are rejected. Requires the backend `codeChallenge` / `codeChallengeMethod` fields on `createFlashAuthRequest` / `flashAuthRequestStatus` to be deployed. - f6208cd: Diagnose stuck queued jobs instead of leaving them ambiguous. A job that stays IN_QUEUE has two very different causes that its status alone cannot distinguish: no host has the endpoint's GPU available (capacity), or a worker spun up and is crash-looping — the platform marks it UNHEALTHY while the job stays queued indefinitely, and agents reliably misread that as a capacity shortage. `get-job-status` now best-effort attaches the endpoint's worker summary (`workerHealth`) and a plain-language `hint` whenever the job is IN_QUEUE (v2 only; the extra lookup never fails the status call, and the diagnosis is cached ~15s per endpoint so polling loops do not amplify into repeated worker-list fetches): UNHEALTHY workers → crash-loop guidance naming the worker ids to inspect with `stream-worker-logs`; zero workers → capacity guidance; throttled/initializing → wait guidance. The `get-job-status`, `endpoint-health`, `list-endpoint-workers`, and `stream-worker-logs` descriptions now cross-reference each other so agents are routed from a stuck job to the worker logs without prior knowledge of the platform's queueing behavior. - f36f191: Send the reshaped v2 Serverless write schema, and support load-balancing endpoints. `/v2/serverless` changed its create/update contract: endpoint `type` (`QUEUE` or `LOAD_BALANCER`) is now required on create, the autoscaling object moved from a flat `{type, value, idleTimeout}` to a per-scaler `{type, queueDelay}` / `{type, requestCount}`, and `idleTimeout` moved under `workers`. `create-endpoint` and `update-endpoint` now emit that shape; previously they sent the older one and were rejected with a `422`. `create-endpoint` gains `endpointType` for queue-based (default) versus load-balancing request routing. `scalerType` defaults per endpoint type, `scalerValue` defaults to `4`, and passing `scalerValue` alone on `update-endpoint` keeps the endpoint's current scaler, so existing calls keep working unchanged. Responses carry `type` and `requestUrls`, and `get-endpoint` / `list-endpoints` now point at `requestUrls` as the source for an endpoint's URLs. **This requires a Runpod API host serving the new schema.** Against a host still on the older one, endpoint create/update return a `422` naming `queueDelay`/`requestCount`/`idleTimeout` as not allowed. `RUNPOD_REST_VERSION=v1` remains available for the legacy template-based model. ## 3.0.0 ### Major Changes - 119f633: Resync the tool surface with the current v2 REST spec. **Breaking:** removes the seven tag tools (`list-tags`, `get-tag`, `create-tag`, `update-tag`, `delete-tag`, `attach-tag`, `detach-tag`). `/v2/tags` no longer exists — it returns `404 "The requested path was not found."` on both the production and dev hosts — so the tools could not succeed for any caller. **New:** three AWS ECR delegation tools (`list-registry-delegations`, `create-registry-delegation`, `delete-registry-delegation`) for `/v2/registries/delegations`. Unlike `create-container-registry-auth`, this stores no credentials: you register an ECR repository ARN and Runpod is granted scoped pull access. v2-only. **New:** `create-network-volume` gains `volumeType` (`STANDARD` | `HIGH_PERFORMANCE`). The field was in the spec but no tool exposed it, so high-performance volumes could not be created here. Omit it for the data center default. Its documented size range is also corrected to 10–4096 GB (was 1–4000). **Enabled:** `list-endpoint-releases` was implemented but left unregistered because `GET /v2/serverless/{id}/releases` used to be dev-only. It now returns 200 on production. `create-template` no longer sends `category: NVIDIA` when the caller omits it — v2 made the field optional with that same server-side default, so the value is no longer invented client-side. An explicit `category` still passes through. ### Minor Changes - fbcf9b7: Add `RUNPOD_AUTHED_GRAPHQL_URL` to override the GraphQL host used by authenticated operations that have no REST equivalent (`deploy-hub-repo`, `set-endpoint-gpus`). These calls send the caller's API key as a Bearer token, so they no longer follow `RUNPOD_PUBLIC_GRAPHQL_URL` — that variable stays the credential-free discovery override, safe to point at a stub. - 00e6ec2: Surface dead credentials as a proper HTTP 401 on the HTTP server so OAuth-capable MCP clients re-authenticate automatically. Previously, when a bearer token was revoked mid-session (e.g. an OAuth-minted key), every upstream Runpod call failed with a 401 that the MCP SDK wrapped into a 200 JSON-RPC tool error — the client never saw an HTTP 401, never re-ran its auth flow, and the user was stuck with bare "Unauthorized" tool errors until they manually reconnected. The request handler now pre-flight verifies the bearer (one `myself` GraphQL query, cached ~60s valid / ~30s invalid by token hash, never the raw token) and answers `401` + `WWW-Authenticate` with the protected-resource metadata when the credential is dead. `WWW-Authenticate` is exposed via CORS so browser clients can read it, and a rejected credential carries `error="invalid_token"` to distinguish it from a request that sent none (RFC 6750 §3.1). `ToolContext` gains an optional `onUnauthorized` callback, invoked when an outbound call returns 401, which drops the cached verdict so the next request re-checks. The check is deliberately conservative so it can never reject a working key: - It fails **open** on anything indeterminate — auth-backend errors, 5xx, 403 (this host sits behind a WAF, and a block is not a revocation), a slow backend (time-bound), and a GraphQL response carrying an `errors` array (a resolver blip returns `myself: null` for everyone at once; treating that as invalid would 401 every valid key). Failing closed on any of these would make OAuth clients re-run the flow, minting a new API key per attempt — an unrecoverable loop. - It runs only for the requests the transport would actually run a tool for: a `POST` whose `Content-Type` the SDK treats as JSON and whose body invokes a method (including inside a batch). Everything else is passed through unchecked. - It self-disables (logging `skip_env_mismatch`) when the REST/Serverless hosts and the auth-GraphQL host disagree about environment in either direction, since it would otherwise validate a key against the wrong backend. - Request bodies are capped at 4 MB (matching the SDK) on hosts that do not pre-parse them. - The verdict cache is safe under load: eviction never disowns an in-flight check, and TTLs use a monotonic clock, so a burst of distinct tokens or a wall-clock adjustment cannot let a since-revoked key linger as `valid`. Set `MCP_SKIP_CREDENTIAL_CHECK=true` to disable the pre-flight entirely. Notes for consumers of the published `./http` export (not only the hosted deployment): the pre-flight adds one outbound `myself` call to the Runpod GraphQL host per checked request, and a new dependency on that host being reachable (it fails open if not). This does **not** close the pre-existing key-validity oracle — a caller who speaks MCP can still learn 401-vs-not for a token, one upstream call each, with no rate limiting; closing that needs rate limiting, which this does not add. - f3b226b: Add a `deploy-hub-repo` tool that deploys a Runpod Hub repo's listed release as a new Serverless endpoint — the same operation as clicking Deploy on the Hub. Identify the repo by `repo` ("owner/name") or `hubReleaseId` (both from `list-hub-repos`); the release supplies the prebuilt image, container disk, CUDA constraints, and env-var defaults, with caller overrides for env vars, GPU pools, worker counts, scaling, and FlashBoot. Required env vars without a default fail fast with an actionable message before anything is created, as do POD listings and releases without a GPU pool when none is provided. Uses the authenticated GraphQL `saveEndpoint` mutation (Hub deploys have no REST home yet), so it behaves identically on v1 and v2. The tool runtime gains a `graphqlAuthed` helper (API-key Bearer + variables) to support it. - 725b6cd: Surface realtime GPU availability on the v2 catalog. `list-gpu-types` now requests `?include=AVAILABILITY` by default, so each GPU carries an `availability` summary (HIGH/MEDIUM/LOW/NONE) and results are sorted highest-stock-first. The full catalog is still returned by default — nothing is hidden — so the tool stays complete for discovery and capacity/price surveys. `includeUnavailable` is now an opt-in _hide_: pass `includeUnavailable: false` to drop out-of-stock GPUs and list only currently-deployable ones. A new `includeAvailability` param (default true) can opt out of the stock lookup entirely. `get-gpu-type` returns the per-datacenter availability breakdown (and URL-encodes ids, which contain spaces) so callers can pick a `dataCenterIds` with stock before creating a pod. Falls back gracefully when the backend doesn't populate availability. The v2 path also drops the `"unknown"` sentinel GPU (matching the v1 path) so it doesn't leak into the now-unhidden default list. Behavior change to note: `list-gpu-types` still returns every GPU by default, but results are now sorted highest-stock-first rather than in a stable order. Nothing is hidden by default. - 546a40f: Add a `list-hub-repos` tool for discovering the Runpod Hub catalog (prebuilt Serverless workers and Pod templates such as vLLM, ComfyUI, and Axolotl). Served by the public GraphQL endpoint — no auth required — and available on both v1 and v2. Each result includes the repo metadata (stars, deploys, category, tags) plus the currently listed release with its `hubReleaseId` and prebuilt `imageName`, the two values a Hub deploy is pinned to. Supports `searchTerm`, `category`, `type` (SERVERLESS/POD), and `repoOwner` filters (applied client-side), and an opt-in `includeConfig` that returns the release's parsed hardware/env-var config from `.runpod/hub.json`. Results are sorted most-deployed first and use the shared pagination envelope. - e4fabd1: Add a `list-public-endpoints` tool for discovering Runpod Public Endpoints — the managed, pay-per-use model APIs (text, image, video, audio) that require no deployment. Served by the public GraphQL endpoint — no auth required — and available on both v1 and v2. Each result includes the `endpointId` to call with `run-endpoint`/`runsync-endpoint` (or directly at `https://api.runpod.ai/v2/{endpointId}`), plus the model name, modality, owner, and pricing parsed from the catalog metadata. Only live endpoints are listed by default (`includeOffline:true` to include the rest), with `searchTerm`, `modality`, and `owner` filters and the shared pagination envelope. - cc0966c: Enable pod and serverless worker log streaming (v2). `stream-pod-logs` (GET /v2/pods/{id}/logs) is now registered — it was previously implemented but disabled while the endpoint was dev-only, and it is now live on prod. A new `stream-worker-logs` tool (GET /v2/serverless/{id}/workers/{workerId}/logs) streams a single worker's logs; get the workerId from `list-endpoint-workers`. Both read a bounded snapshot of the Server-Sent-Events stream (container and/or system) and support `source`, `tail`, `since`, and `maxWaitMs`; both return a 501 notice on the v1 API. - 466a9d8: Add a `set-endpoint-gpus` tool that sets which GPUs any Serverless endpoint's workers run on — including pinning specific GPU SKUs, which the REST API cannot express (its pool-level `gpuPoolIds` has no exclusion concept). Callers pass either a raw `gpuIds` string or `pools` plus `excludeGpuTypeIds` (GPU type ids from `list-gpu-types`) and the exclusion string is built automatically; excluding all but one SKU in a pool pins that SKU exactly. Because the GraphQL `saveEndpoint` mutation resets omitted endpoint-level fields to server defaults (verified live), the tool reads the endpoint's current settings first and echoes every field back with only the GPU selection changed — workers, scaling, timeouts, FlashBoot, locations, network volumes, and the template are all preserved. - d1f3719: create-pod template deploy improvements. Added a `containerRegistryAuthId` param to `create-pod` (private-image registry credential, a valid v2 ContainerConfig field). When deploying from a `templateId`, the template's registry credential is inherited as a default so a private-image template pulls correctly, `containerRegistryAuthId` overrides it, and passing an empty string opts out entirely (emits `registry: null`, which v2 accepts, clearing the template's credential). The template is fetched from v2 explicitly, so a split per-resource version override (e.g. templates pinned to v1) can't yield a v1-shaped template merged into a v2 pod body. Tool descriptions now state that template fields are applied whole-field as defaults (an explicitly-passed field replaces the template value rather than merging). - 0b49b91: Fix two template gaps from the same ticket (API-385 / E-3717). 1. `create-template`/`update-template` were dropping the container start command on the v2 REST API. `dockerStartCmd` is now mapped to the v2 template's `args` field (a single string; a multi-element array is space-joined) instead of being discarded, so a template's startup command is persisted. `update-template` accepts `dockerStartCmd` now too. (v2 has no separate entrypoint field, so `dockerEntrypoint` is still not persisted on v2 — documented in the tool.) 2. `create-pod` can now deploy from a template. v2 `CreatePodRequest` has no `templateId`, so `create-pod` accepts a `templateId`, fetches the template, and spreads its container config (image, start command, ports, env, disk, volume, registry credential) into the pod body as defaults — any field you also pass explicitly overrides the template. `imageName` is now optional when `templateId` is given. Template-based deploy requires the v2 REST API and (for now) a GPU pod; clear errors are returned for v1, CPU, or when neither image nor template is supplied. ### Patch Changes - e50409d: URL-encode the resource ids interpolated into the log-streaming request paths (`stream-pod-logs`, `stream-worker-logs`) so an id containing a URL-special character can't corrupt the request path. Opaque Runpod ids are unaffected in practice; this is defensive hardening. - fb76883: Surface the configured `RUNPOD_REST_VERSION` in the MCP `serverInfo` version, e.g. `2.0.0 [RUNPOD_REST_VERSION=v2]` (or `RUNPOD_REST_VERSION unset (default v2)`). A plain `initialize` handshake now reveals whether a deployment is running v1 or v2 without inspecting the environment, and flags any per-resource overrides. ## 2.0.0 ### Major Changes - 2658e43: **Breaking:** default the REST version to **v2**, and migrate Serverless endpoint CRUD to the v2 API. With nothing set, all control-plane resources now use the v2 REST API (`v2-rest.runpod.io/v2`); set `RUNPOD_REST_VERSION=v1` to pin the previous v1 behavior. Why this is a major bump: `create-endpoint`/`update-endpoint` move from the v1 **template-based** model to the v2 **inline-config** model. On v2, `create-endpoint` no longer accepts a `templateId` — it requires `imageName` + `gpuPoolIds` (GPU pool names from `list-gpu-types`, e.g. `AMPERE_80`) plus optional `workers`/`scaling`. So an existing integration that calls `create-endpoint` with `{ templateId }` and no `RUNPOD_REST_VERSION` pin will get a clean `400` after upgrading, with no code change on their side. To keep the old behavior, pin `RUNPOD_REST_VERSION=v1` (templateId model preserved). `jobs` still resolves to v1 (serverless runtime API, no v2 home). CPU pods are still served by v1, and the `auto` stdio probe is unchanged. Version-sensitive tests pin their version explicitly so the suite is independent of the default. See the README "REST API version (v1 / v2)" section for the migration note. ### Minor Changes - cdba19c: Add v2-only tools covering the rest of the v2 REST surface: - **Tags** — `list-tags`, `get-tag`, `create-tag`, `update-tag`, `delete-tag`, and `attach-tag` / `detach-tag` to associate a tag with a pod, network volume, cluster, or serverless endpoint. - **Billing** — `get-billing` returns time-bucketed spend, either aggregated or broken down by resource type (`scope`), windowed by `startTime`/`endTime` or `lastN`. The records array is capped via `limit`/`cursor`. - **Endpoint workers** — `list-endpoint-workers` lists the workers behind a serverless endpoint plus an aggregate summary (capped via `limit`/`cursor`). - **Catalog by id** — `get-cpu-type` and `get-data-center` round out the catalog alongside the existing `get-gpu-type`. These resources exist only on the v2 REST API, so each returns a clean `501` notice on v1 (set `RUNPOD_REST_VERSION=v2`). ## 1.4.0 ### Minor Changes - f3ddd6d: Cap list-tool responses so they no longer overflow the agent's context window. Every `list-*` tool (`list-pods`, `list-endpoints`, `list-templates`, `list-network-volumes`, `list-container-registry-auths`) now accepts optional `limit` and `cursor` parameters and returns at most `limit` items (default 20, max 100) inside a `{ items, pagination }` envelope that reports `total`, `returned`, `truncated`, and a `nextCursor` for fetching the next page. The REST API does not yet support server-side pagination, so this is a client-side cap; the `limit`/`cursor` signature is shaped to match the cursor-based pagination the REST API will add, so the tool interface will not change when server-side pagination lands. - e59fbfe: Add a guided install wizard. Running `npx @runpod/mcp-server@latest add` detects installed agents (Claude Code, Claude Desktop, Cursor, Windsurf, Visual Studio Code), lets you pick which to configure, and writes the MCP configuration for each. It offers two connection modes: a hosted mode that points the agent at the hosted server and authenticates with the "Sign in with Runpod" OAuth flow (no API key stored on disk), and a local mode that runs the server via npx with a `RUNPOD_API_KEY`. `remove` undoes the changes. Existing config files keep their formatting and comments. ## 1.3.0 ### Minor Changes - 3e6dedf: Add HTTP transport for hosted MCP server deployments. The package now exports three entrypoints: `@runpod/mcp-server` (stdio, unchanged), `@runpod/mcp-server/http` (streamable HTTP with per-request auth), and `@runpod/mcp-server/tools` (shared tool definitions). This enables deploying the MCP server on Vercel or any HTTP-capable host where each request carries its own Runpod API key via the Authorization header. Existing stdio users are unaffected. - 3e6dedf: Add a "Sign in with Runpod" OAuth flow to the hosted HTTP server so it can act as the authorization server for Claude's MCP connector. When `MCP_OAUTH_ENABLED=true`, the server advertises itself in the OAuth discovery metadata and exposes `GET /authorize` and `POST /token`. The flow reuses the Runpod flash auth backend: `/authorize` creates a guest `createFlashAuthRequest` and hands off to the Runpod console for approval, and `/token` polls `flashAuthRequestStatus` and returns the minted Runpod API key as the access token, which the server then forwards to the Runpod API. The backend endpoint and console base URL are configurable via `RUNPOD_GRAPHQL_URL` and `CONSOLE_BASE_URL`. - 3e6dedf: Complete the hosted OAuth flow for real MCP clients. Add an OAuth 2.0 Dynamic Client Registration endpoint (`POST /register`, RFC 7591) and advertise it as `registration_endpoint`, so clients like Claude can register before signing in. Make the Runpod REST and Serverless API hosts configurable via `RUNPOD_REST_API_URL` and `RUNPOD_SERVERLESS_API_URL` so a deployment authenticating with non-production keys can target the matching environment. The console handoff path is `/integrations/mcp/login`. - 3e6dedf: Validate the OAuth `redirect_uri` against an allowlist. Because the authorization code redeems into a real Runpod API key, `/authorize` and `/token` now reject any `redirect_uri` that is not an allowlisted client callback, preventing an attacker from crafting an authorize link that delivers the code (and key) to a host they control. Loopback addresses (`http://localhost` / `127.0.0.1` / `::1`, any port) are always allowed per RFC 8252; the hosted client callbacks default to Claude's, and the list is extendable via `MCP_ALLOWED_REDIRECT_URIS` (comma-separated). - 3e6dedf: Address hosted OAuth review feedback: - Remove the `MCP_OAUTH_ENABLED` flag — the hosted HTTP server always advertises the OAuth sign-in challenge. Callers that bring their own Runpod API key as the bearer token are unaffected (they never hit the challenge). - Default `CONSOLE_BASE_URL` to the production console (`https://console.runpod.io`) so a deploy that forgets to set it doesn't silently redirect users to localhost. - `/token` now polls for most of the function budget (~45s) instead of returning a non-retryable `authorization_pending` after ~10s, avoiding a dead-end when console→backend approval propagation lags. - Caller-tracking falls back to the inbound HTTP `User-Agent` on the stateless HTTP transport, where the per-request server never sees the MCP `initialize` `clientInfo` (previously reported `client=unknown`). - Stop advertising PKCE (`S256`) since it isn't enforced server-side; security rests on the `redirect_uri` allowlist and the single-use flash approval. - Default the minted key name to `runpod-mcp` (`RUNPOD_API_KEY_NAME`), so hosted keys are identifiable/revocable. Set `RUNPOD_API_KEY_NAME=""` to suppress it for a backend that has not shipped the `apiKeyName` argument. - 3e6dedf: Simplify hosted HTTP auth to pure token passthrough. The server now forwards the caller's Bearer token directly to the Runpod API and holds no credential of its own — there is no shared server-side key and no token translation. When `MCP_OAUTH_ENABLED=true`, unauthenticated requests return a `WWW-Authenticate` challenge so OAuth-capable clients start the "Sign in with Runpod" flow. Removes the `RUNPOD_HTTP_SHARED_API_KEY` environment variable and the `jose` dependency. ### Patch Changes - 3e6dedf: Support naming the minted Runpod API key in the OAuth flow. Set `RUNPOD_API_KEY_NAME` (e.g. `runpod-mcp`) to pass `apiKeyName` through to the flash backend's `createFlashAuthRequest`, so the key shows up under that name in the user's dashboard. It is omitted by default for compatibility with backends that don't yet support the argument. - 3e6dedf: Address low-severity review nits on the hosted HTTP / OAuth path: - Make the public discovery GraphQL host configurable via `RUNPOD_PUBLIC_GRAPHQL_URL` (was hardcoded to prod, so a dev deploy hit prod GraphQL). - Report the real package version in the hosted server's outbound `User-Agent` (read from package.json at runtime, since tsup's build-time define doesn't run when Vercel compiles `api/index.ts`). - Gate OAuth request-id / handoff-URL logging behind `MCP_VERBOSE_LOGS` (request ids are live, single-use auth codes). - `stream-job` now surfaces the most recent polling error in its timeout payload instead of discarding it. - Pass the parsed request body to the MCP transport explicitly; dispose the per-request server/transport on response close; guard `getBaseUrl` against a missing `Host`; handle a `Buffer` request body in the token endpoint. - Single CORS source of truth (handler, not `vercel.json`); stop serving the whole repo as static assets; add an `oauth-e2e` npm script and `engines.pnpm`; fix docs that misattributed the OAuth routes and listed the new env vars. ## 1.2.0 ### Minor Changes - 7b715eb: Add list-gpu-types and list-data-centers tools using public GraphQL API for hardware and region discovery. Enhance list-templates with filter params (includeRunpodTemplates, includePublicTemplates, includeEndpointBoundTemplates). Add tool descriptions to create-pod and list-templates recommending Pytorch 2.8.0 as default template. - ea2451b: Add Serverless endpoint runtime tools for invoking deployed workers. New tools: run-endpoint (async), runsync-endpoint (sync), get-job-status, stream-job, cancel-job, retry-job, endpoint-health, and purge-endpoint-queue. These use the Serverless API at api.runpod.ai/v2 with a new serverlessRequest helper. - 34c0463: Add caller tracking headers to every outbound API call. Each request now carries a structured `User-Agent` (`runpod-mcp-server/ (caller=mcp; client=; client_version=; transport=)`) and an anonymous per-process `X-Runpod-Session-Id` UUID. The MCP client identity is sourced from the `initialize` handshake's `clientInfo`. No tool behavior changes — observability only — so the Runpod platform can attribute traffic to specific MCP clients (Claude Code, Cursor, Codex, Gemini CLI, etc.) and count distinct agent sessions. ## 1.1.0 ### Minor Changes - c49b2cc: Add npx support for running the MCP server directly without installation. Includes bin field in package.json, shebang in build output, and updated README with npx command. Also fixes branding consistency (Runpod -> Runpod) and adds development conventions documentation.