@runpod/mcp-server 1.4.0 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,115 @@
 # @runpod/mcp-server
 
+## 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
@@ -22,7 +132,7 @@
 
 ### 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 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).
@@ -59,4 +169,4 @@
 
 ### 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.
+- 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.

package/README.md

@@ -2,33 +2,61 @@
 
 [![smithery badge](https://smithery.ai/badge/@runpod/runpod-mcp-ts)](https://smithery.ai/server/@runpod/runpod-mcp-ts)
 
-This is the official Runpod Model Context Protocol (MCP) server, published to npm as `@runpod/mcp-server`.
+This is the official Runpod Model Context Protocol (MCP) server, published to npm as `@runpod/mcp-server`. It lets MCP clients such as Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code manage your Runpod Pods, Serverless endpoints, templates, network volumes, and more.
 
-It supports two deployment modes:
+## Quick start
 
-- Local `stdio` for Claude Desktop, Claude Code, Cursor, VS Code, and other MCP clients that launch a local process. The caller sets `RUNPOD_API_KEY` in the environment.
-- Hosted Streamable HTTP for Vercel or other HTTP-capable platforms. Each request carries its own `Authorization: Bearer <token>`, which the server forwards directly to the Runpod API. The token can be a Runpod API key or one obtained through the OAuth "Sign in with Runpod" flow.
+The fastest way to get connected is the guided installer pointed at the **hosted Runpod MCP server at `https://mcp.getrunpod.io/`**. The installer detects the agents you have installed, asks which ones to configure, and writes the configuration for you:
 
-The server never holds a credential of its own and never shares one across users.
+```bash
+npx @runpod/mcp-server@latest add
+```
 
-## Requirements
+It supports **Claude Code, Claude Desktop, Cursor, Windsurf, and Visual Studio Code**, and offers two connection modes:
 
-- Node.js 18 or higher.
-- A Runpod account and API key: https://www.runpod.io/console/user/settings
+- **Hosted (recommended).** Points the agent at the hosted server and authenticates with the **"Sign in with Runpod"** OAuth flow, so **no API key is stored on disk**.
+- **Local.** Runs the server through `npx` and stores a `RUNPOD_API_KEY` in the agent's config.
 
-## Quick start
+To undo the changes later, run:
+
+```bash
+npx @runpod/mcp-server@latest remove
+```
 
-### Guided install
+### Connect to the hosted server manually
 
-The fastest way to get set up is the interactive installer. It detects the agents you have installed, asks which ones to configure, and writes the configuration for you:
+If you'd rather configure your client by hand, point it at the hosted server over HTTP (no local process, no API key stored).
+
+**Claude Code** — add it as an HTTP server:
 
 ```bash
-npx @runpod/mcp-server@latest add
+claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/
+```
+
+**Other clients** (Cursor, VS Code, Claude Desktop connectors, …) — use a URL-based MCP entry:
+
+```json
+{
+  "mcpServers": {
+    "runpod": {
+      "url": "https://mcp.getrunpod.io/"
+    }
+  }
+}
 ```
 
-It supports Claude Code, Claude Desktop, Cursor, Windsurf, and Visual Studio Code, and offers two connection modes. The recommended mode points the agent at the hosted server and lets it authenticate with the "Sign in with Runpod" OAuth flow, so no API key is stored on disk. The local mode runs the server through `npx` and stores a `RUNPOD_API_KEY` in the agent's config. To undo the changes later, run `npx @runpod/mcp-server@latest remove`.
+The hosted server uses the "Sign in with Runpod" OAuth flow for authentication, so no API key is stored. An OAuth-capable client starts the sign-in flow automatically on first connect. See [Sign in with Runpod (authorize flow)](#sign-in-with-runpod-authorize-flow) for details.
+
+> Prefer your own API key instead of OAuth? Append `--header "Authorization: Bearer YOUR_API_KEY"` to the `claude mcp add` command (or add a `headers` block in the JSON), and the server forwards that key to the Runpod API directly.
 
-### Run locally with `npx`
+### Requirements
+
+- Node.js 18 or higher.
+- A Runpod account and API key: https://www.runpod.io/console/user/settings
+
+## Run locally with `npx`
+
+To run the server as a local `stdio` process with your own API key:
 
 ```bash
 RUNPOD_API_KEY=YOUR_API_KEY npx -y @runpod/mcp-server@latest
@@ -40,9 +68,9 @@ RUNPOD_API_KEY=YOUR_API_KEY npx -y @runpod/mcp-server@latest
 npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
 ```
 
-## Local MCP clients
+## Local MCP client setup
 
-Local MCP clients should use the default package entrypoint, which is the `stdio` server.
+Local MCP clients should use the default package entrypoint, which is the `stdio` server. The caller sets `RUNPOD_API_KEY` in the environment, and the server forwards it directly to the Runpod API.
 
 ### Claude Code
 
@@ -90,6 +118,8 @@ Windows:
 
 Restart Claude Desktop after saving.
 
+For remote clients such as Claude's connector, use the hosted HTTP server instead (the [Quick start](#quick-start) above). The client then runs the OAuth "Sign in with Runpod" flow, and the resulting Runpod API key is forwarded to the Runpod API on each request.
+
 ### Cursor
 
 Add this to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
@@ -118,9 +148,42 @@ Use the same pattern:
 
 For a broader list of MCP clients, see https://modelcontextprotocol.io/clients
 
+## Usage examples
+
+### List all Pods
+
+```text
+Can you list all my Runpod Pods?
+```
+
+### Create a new Pod
+
+```text
+Create a new Runpod Pod with the following specifications:
+- Name: test-pod
+- Image: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
+- GPU Type: NVIDIA GeForce RTX 4090
+- GPU Count: 1
+```
+
+### Create a Serverless endpoint
+
+```text
+Create a Runpod Serverless endpoint with the following configuration:
+- Name: my-endpoint
+- Image: runpod/test-output:0.0.1
+- GPU pool: AMPERE_80   (a "pool" value from list-gpu-types)
+- Minimum workers: 0
+- Maximum workers: 3
+```
+
+On the v2 API (the default) endpoints are image-based — pass an image and a GPU
+pool, not a template. To use the legacy template-based model, pin
+`RUNPOD_REST_VERSION=v1` and provide a `Template ID` instead.
+
 ## Hosted HTTP deployment
 
-The package also exports a Streamable HTTP entrypoint at `@runpod/mcp-server/http`, and this repo includes a Vercel function in `api/index.ts`.
+The package also exports a Streamable HTTP entrypoint at `@runpod/mcp-server/http`, and this repo includes a Vercel function in `api/index.ts`. This is what powers the hosted server at `https://mcp.getrunpod.io/`.
 
 The hosted transport is stateless:
 
@@ -137,7 +200,9 @@ The token can be either:
 - a Runpod API key the caller configured manually, or
 - a Runpod API key obtained through the OAuth "Sign in with Runpod" flow (see below).
 
-An unauthenticated request receives a `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata, which tells an OAuth-capable client (such as Claude) to start the sign-in flow. A caller that brings its own API key as the bearer token never hits that path.
+An unauthenticated request receives a `401` with a `WWW-Authenticate` header pointing at the protected-resource metadata, which tells an OAuth-capable client (such as Claude) to start the sign-in flow.
+
+A request whose bearer token is _rejected_ — a revoked key, whether OAuth-minted or supplied by the caller — gets the same `401`, plus `error="invalid_token"` to distinguish it from having sent no credential at all. The token is verified once and the verdict cached briefly. If a credential dies mid-session while a "valid" verdict is still cached, the first call afterward can still surface the upstream 401 as a `200` tool error; that call drops the cached verdict, so the next request re-checks and surfaces a real HTTP `401` that triggers re-authentication. Set `MCP_SKIP_CREDENTIAL_CHECK=true` to disable that verification; it also self-disables when the REST/Serverless hosts and the auth GraphQL host are pointed at different environments, since it would otherwise validate the key against the wrong backend.
 
 ### Sign in with Runpod (authorize flow)
 
@@ -200,12 +265,6 @@ This validates:
 - A public GraphQL-backed tool call.
 - An authenticated REST-backed tool call.
 
-## Claude Desktop and hosted MCP
-
-Use the local `stdio` integration for Claude Desktop today.
-
-For remote clients such as Claude's connector, deploy the hosted HTTP server. The client then runs the OAuth "Sign in with Runpod" flow, and the resulting Runpod API key is forwarded to the Runpod API on each request.
-
 ## Local development
 
 ```bash
@@ -240,42 +299,20 @@ RUNPOD_API_KEY=YOUR_API_KEY pnpm build
 RUNPOD_API_KEY=YOUR_API_KEY pnpm smoke:stdio
 ```
 
-## Usage examples
-
-### List all Pods
-
-```text
-Can you list all my Runpod Pods?
-```
-
-### Create a new Pod
-
-```text
-Create a new Runpod Pod with the following specifications:
-- Name: test-pod
-- Image: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
-- GPU Type: NVIDIA GeForce RTX 4090
-- GPU Count: 1
-```
-
-### Create a Serverless endpoint
-
-```text
-Create a Runpod Serverless endpoint with the following configuration:
-- Name: my-endpoint
-- Template ID: 30zmvf89kd
-- Minimum workers: 0
-- Maximum workers: 3
-```
-
 ## Contributing
 
 The source is now split by responsibility:
 
-- `src/stdio.ts`: local `stdio` entrypoint.
+- `src/stdio.ts`: local `stdio` entrypoint (runs the v2 probe at startup for `auto` mode).
 - `src/http.ts`: bearer-token extraction and the per-request MCP session for the Streamable HTTP transport.
-- `src/tools.ts`: all Runpod MCP tools.
+- `src/tools.ts`: thin orchestrator — builds the shared runtime and calls each per-resource registrar.
+- `src/tools/<resource>.ts`: the tools for one resource (`pods`, `endpoints`, `jobs`, `templates`, `network-volumes`, `registries`, `catalog`), each with a description + MCP annotations.
+- `src/tools/runtime.ts`: the shared per-server runtime (caller-tracking, the authenticated REST/Serverless/GraphQL clients, the v1/v2 backend resolver) threaded into every registrar.
 - `src/server.ts`: shared server metadata and construction.
+- `src/_shared/backend.ts`: v1/v2 routing adapter — version resolution, per-resource paths, list-envelope unwrap, and the v2 probe.
+- `src/_shared/http.ts`: unified authenticated JSON client + `HttpError`.
+- `src/_shared/tracking.ts`: caller-tracking header construction.
+- `src/_shared/mappers.ts`: v1→v2 request-body mappers.
 - `api/index.ts`: Vercel adapter and the OAuth authorization-server routes (`/.well-known/*`, `/register`, `/authorize`, `/token`).
 
 After changes:
@@ -283,9 +320,27 @@ After changes:
 ```bash
 pnpm type-check
 pnpm lint
+pnpm test
 pnpm build
 ```
 
+`pnpm test` runs the offline unit suite (outbound-request goldens, adapter, mappers, http client) — no network or API key required.
+
+### v2 spec parity gate
+
+`tests/spec-parity.test.ts` walks every operation in the vendored v2 OpenAPI spec (`tests/fixtures/v2-openapi.yaml`) and fails if a v2 endpoint has no MCP tool covering it (and isn't explicitly allowlisted) — the drift gate that flags when the API grows an endpoint we don't expose yet. It also runs the reverse check (no tool is left unaccounted for). It's part of `pnpm test`, hermetic (parses the committed spec; no network, no API key).
+
+Refresh the vendored spec when the v2 API changes:
+
+```bash
+pnpm tsx scripts/fetch-v2-spec.ts   # re-fetch tests/fixtures/v2-openapi.yaml
+pnpm test                           # parity test shows any newly-uncovered endpoint
+```
+
+The serverless runtime tools (`run-endpoint`, `get-job-status`, …) target `api.runpod.ai/v2`, which is a different service from the v2 REST control plane, so they are allowlisted as intentionally spec-unmapped. The spec has no logs/artifacts endpoints, so there are no such tools.
+
+An optional live shape check (skipped by default) verifies the live endpoints still return the envelopes the list tools unwrap; run it with `MCP_LIVE_V2_KEY=<dev-key> pnpm test` (optionally `MCP_LIVE_V2_BASE`).
+
 For transport validation:
 
 ```bash
@@ -293,10 +348,85 @@ pnpm smoke:stdio
 pnpm smoke:http
 ```
 
+To exercise a real create→get→delete lifecycle against a **dev account** (free resources only — templates and registry auths — with fail-closed teardown):
+
+```bash
+RUNPOD_API_KEY=YOUR_DEV_KEY \
+RUNPOD_REST_V2_API_URL=https://v2-rest.runpod.dev/v2 \
+pnpm smoke:crud v1 v2
+```
+
 This project uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing. Every PR with user-facing changes needs a changeset file at `.changeset/DESCRIPTIVE_NAME.md`.
 
 See `CLAUDE.md` and `docs/context.md` for contributor guidance.
 
+## Reference
+
+### Deployment modes
+
+The server supports two deployment modes:
+
+- Local `stdio` for Claude Desktop, Claude Code, Cursor, VS Code, and other MCP clients that launch a local process. The caller sets `RUNPOD_API_KEY` in the environment.
+- Hosted Streamable HTTP for Vercel or other HTTP-capable platforms. Each request carries its own `Authorization: Bearer <token>`, which the server forwards directly to the Runpod API. The token can be a Runpod API key or one obtained through the OAuth "Sign in with Runpod" flow.
+
+The server never holds a credential of its own and never shares one across users.
+
+### REST API version (v1 / v2)
+
+The server can target either the v1 REST API (`rest.runpod.io/v1`) or the newer v2 REST API (`v2-rest.runpod.io/v2`). It **defaults to v2**; set `RUNPOD_REST_VERSION=v1` to pin the previous v1 behavior. These environment variables are read once at startup:
+
+| Variable                         | Values                 | Default                        | Effect                                                                                                |
+| -------------------------------- | ---------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------- |
+| `RUNPOD_REST_VERSION`            | `v1` \| `v2` \| `auto` | `v2`                           | Version used for all resources.                                                                       |
+| `RUNPOD_REST_VERSION_<RESOURCE>` | `v1` \| `v2` \| `auto` | —                              | Per-resource override (e.g. `RUNPOD_REST_VERSION_PODS=v2`). Takes precedence over the global setting. |
+| `RUNPOD_REST_V2_API_URL`         | URL                    | `https://v2-rest.runpod.io/v2` | v2 base URL. Override to target a non-prod host.                                                      |
+| `RUNPOD_REST_API_URL`            | URL                    | `https://rest.runpod.io/v1`    | v1 base URL.                                                                                          |
+| `RUNPOD_SERVERLESS_API_URL`      | URL                    | `https://api.runpod.ai/v2`     | Serverless runtime base URL.                                                                          |
+
+> **⚠️ Migration note — `create-endpoint` / `update-endpoint` changed shape in v2.** Serverless endpoints now use the v2 API (`/v2/serverless`) with an **inline config** instead of a `templateId`. On v2, `create-endpoint` requires `imageName` + `gpuPoolIds` (GPU **pool** names from `list-gpu-types` — the `pool` field, e.g. `AMPERE_80`), plus optional `workersMin`/`workersMax`, `scalerType`/`scalerValue`/`idleTimeout`, `containerDiskInGb`, `env`, `flashboot`, etc. It no longer accepts `templateId`. **If you previously called `create-endpoint` with `{ templateId }` and have no `RUNPOD_REST_VERSION` set, that call now returns a clean `400` after upgrading** — switch to the inline fields, or pin `RUNPOD_REST_VERSION=v1` to keep the legacy template-based model.
+
+Notes:
+
+- **Default is v2** — with nothing set, every control-plane resource uses the v2 REST API. Set `RUNPOD_REST_VERSION=v1` to pin the previous v1 behavior.
+- **Pinning a deployment** — the env var is read once at startup, so set `RUNPOD_REST_VERSION` (`v1` or `v2`) in the host's environment (e.g. a Vercel project env var) and redeploy; no code change. Hosted HTTP honors this default like any other transport.
+- **What `auto` does:** it probes v2 once at startup and falls back to v1 — but **only on the `stdio` transport** (one process = one key). On hosted HTTP `auto` resolves to **v1**, because a warm instance serves many users and a cached probe verdict could leak across them. `auto` is a stdio-only convenience; on HTTP, rely on the default or pin the version explicitly.
+- `jobs` (serverless runtime) always uses v1 regardless of the setting — it has no v2 REST home (it targets `api.runpod.ai/v2`, a different service).
+- The v2-only tools (`list-cpu-types`, `get-gpu-type`, `restart-pod`, and the three `*-registry-delegation(s)` tools) return a clear "v2 only" notice when called under v1.
+- `create-pod` for a **CPU pod** (`computeType: "CPU"`) on v2 is transparently served by the **v1** API — v2 has no CPU pods yet — and the reply is flagged `_servedBy: "v1"`. Because that fallback hits the **v1 base**, set `RUNPOD_REST_API_URL` to match your environment when running v2 against a non-prod host (otherwise CPU creates land on v1 **prod**). On v2 a create with neither `gpuTypeIds` nor `computeType` is rejected — absence is never silently turned into a CPU pod.
+
+### Private image pull: credentials vs ECR delegation
+
+Two ways to let Runpod pull a private image, and they are not interchangeable:
+
+- **`create-container-registry-auth`** — stores a username + password/token. Works for any registry (Docker Hub, GHCR, Quay, a self-hosted one). Available on v1 and v2. Reference the resulting id from `create-pod` / `create-endpoint` via `containerRegistryAuthId`.
+- **`create-registry-delegation`** — **AWS ECR only, v2-only, no credentials stored.** You register an ECR repository ARN and Runpod is granted scoped pull access to it; the reply carries a `dockerRegistryUri` plus the resolved repository, tag, and AWS region. Manage with `list-registry-delegations` and revoke with `delete-registry-delegation`.
+
+Prefer the delegation for ECR — nothing long-lived is stored on Runpod's side.
+
+Example (stdio client config) — v2 against prod:
+
+```json
+"env": {
+  "RUNPOD_API_KEY": "YOUR_API_KEY",
+  "RUNPOD_REST_VERSION": "v2"
+}
+```
+
+Targeting a **non-prod (dev) environment** — point **both** bases at it (the v1 base matters even in v2 mode, for the CPU-pod fallback above):
+
+```json
+"env": {
+  "RUNPOD_API_KEY": "YOUR_DEV_KEY",
+  "RUNPOD_REST_VERSION": "v2",
+  "RUNPOD_REST_V2_API_URL": "https://v2-rest.runpod.dev/v2",
+  "RUNPOD_REST_API_URL": "https://rest.runpod.dev/v1"
+}
+```
+
+### Large tool output
+
+Resource **lists** are paginated (default 20 items, `nextCursor`), so a big account can't flood the agent's context. But **serverless job output** — `run-endpoint`, `runsync-endpoint`, `get-job-status`, and especially `stream-job` (which accumulates every chunk) — is returned **as-is and is not size-capped**. It's a single opaque payload, not a list, so there's no cursor to page. A very large or long-streaming result can exceed the context window. If output may be huge, have the agent **write it to a file** instead of returning it inline, or set `s3Config` on the job so large outputs go to object storage.
+
 ## Security considerations
 
 This server acts with the full permissions of the supplied `RUNPOD_API_KEY`.