@runpod/mcp-server 3.0.0 → 3.2.0

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @runpod/mcp-server
 
+## 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 - <message>`), 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` (runpod/RunPod, DR-1398) 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

package/README.md

@@ -2,32 +2,56 @@
 
 [![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`. 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.
+The official Runpod Model Context Protocol (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.
+
+**We host it for you at [`https://mcp.getrunpod.io/`](https://mcp.getrunpod.io/)** — point your client at that URL and sign in with Runpod. Nothing to install, no API key on disk. Or run it locally from npm as [`@runpod/mcp-server`](https://www.npmjs.com/package/@runpod/mcp-server).
 
 ## Quick start
 
-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 guided installer detects the clients you have installed, asks which to configure, and writes the config for you:
 
 ```bash
 npx @runpod/mcp-server@latest add
 ```
 
-It supports **Claude Code, Claude Desktop, Cursor, Windsurf, and Visual Studio Code**, and offers two connection modes:
+It offers two connection modes:
 
-- **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.
+- **Hosted (recommended)** — points the client at the hosted server and authenticates with "Sign in with Runpod" (OAuth). No API key is stored on disk.
+- **Local** — runs the server through `npx` and stores a `RUNPOD_API_KEY` in the client's config.
 
-To undo the changes later, run:
+To undo later:
 
 ```bash
 npx @runpod/mcp-server@latest remove
 ```
 
-### Connect to the hosted server manually
+### Or install the whole Runpod plugin
+
+For the full agent setup, the [official plugin marketplace](https://github.com/runpod/runpod-plugins-official) bundles this server with a router skill plus five more — `runpod-mcp`, `runpodctl`, `flash`, `runpod-usage`, and `companion-clis`:
+
+```bash
+npx skills add runpod/runpod-plugins-official
+```
+
+That works in Claude Code, Codex, Cursor, Copilot, Windsurf, Cline, Gemini, opencode, and 17+ other agents, and installs the skills — pair it with `npx @runpod/mcp-server@latest add` above for the control-plane tools.
 
-If you'd rather configure your client by hand, point it at the hosted server over HTTP (no local process, no API key stored).
+In **Claude Code**, the native plugin route also wires up the hosted MCP server for you (OAuth included), so no separate setup is needed:
 
-**Claude Code** — add it as an HTTP server:
+```
+/plugin marketplace add runpod/runpod-plugins-official
+/plugin install runpod@runpod
+```
+
+### Requirements
+
+- Node.js 18 or higher.
+- A Runpod account and [API key](https://www.runpod.io/console/user/settings).
+
+## Connect to the hosted server
+
+To configure a client by hand, point it at the hosted server over HTTP (no local process, no API key stored).
+
+**Claude Code:**
 
 ```bash
 claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/
@@ -45,34 +69,29 @@ claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/
 }
 ```
 
-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.
+An OAuth-capable client starts the "Sign in with Runpod" flow automatically on first connect: it opens a browser, you log in to the Runpod console and approve, and the server obtains a Runpod API key scoped to your session. Nothing is stored on disk.
 
-> 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.
-
-### Requirements
-
-- Node.js 18 or higher.
-- A Runpod account and API key: https://www.runpod.io/console/user/settings
+> Prefer your own API key over OAuth? Append `--header "Authorization: Bearer YOUR_API_KEY"` to the `claude mcp add` command (or add a `headers` block in the JSON). The server forwards that key to the Runpod API directly.
 
 ## Run locally with `npx`
 
-To run the server as a local `stdio` process with your own API key:
+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
 ```
 
-### Install via Smithery
+Or install via [Smithery](https://smithery.ai/server/@runpod/runpod-mcp-ts):
 
 ```bash
 npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
 ```
 
-## Local MCP client setup
+### Local client setup
 
-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.
+Local clients launch the `stdio` server and set `RUNPOD_API_KEY` in the environment.
 
-### Claude Code
+**Claude Code:**
 
 ```bash
 claude mcp add runpod -s user \
@@ -80,27 +99,9 @@ claude mcp add runpod -s user \
   -- npx -y @runpod/mcp-server@latest
 ```
 
-For a project-local server:
+Use `-s project` for a project-local server. Verify with `claude mcp list`; in a session, `/mcp` reconnects.
 
-```bash
-claude mcp add runpod -s project \
-  -e RUNPOD_API_KEY=YOUR_API_KEY \
-  -- npx -y @runpod/mcp-server@latest
-```
-
-Verify with `claude mcp list`. In an active session, use `/mcp` to reconnect.
-
-### Claude Desktop
-
-Local MCP servers in Claude Desktop still use `claude_desktop_config.json`.
-
-macOS:
-
-`~/Library/Application Support/Claude/claude_desktop_config.json`
-
-Windows:
-
-`%APPDATA%\\Claude\\claude_desktop_config.json`
+**Claude Desktop, Cursor, VS Code, Windsurf, and other clients** — use the same command in the client's MCP config:
 
 ```json
 {
@@ -116,154 +117,38 @@ 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:
-
-```json
-{
-  "mcpServers": {
-    "runpod": {
-      "command": "npx",
-      "args": ["-y", "@runpod/mcp-server@latest"],
-      "env": {
-        "RUNPOD_API_KEY": "YOUR_API_KEY"
-      }
-    }
-  }
-}
-```
-
-### VS Code, Windsurf, Cline, JetBrains, and other local clients
-
-Use the same pattern:
-
-- command: `npx`
-- args: `["-y", "@runpod/mcp-server@latest"]`
-- env: `RUNPOD_API_KEY=YOUR_API_KEY`
-
-For a broader list of MCP clients, see https://modelcontextprotocol.io/clients
+Claude Desktop's config lives at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows); restart the app after saving. For a broader list of clients, see the [MCP clients directory](https://modelcontextprotocol.io/clients).
 
 ## Usage examples
 
-### List all Pods
+Ask your MCP client in natural language:
 
 ```text
-Can you list all my Runpod Pods?
+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 Runpod Pod named test-pod with image
+runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04,
+GPU type NVIDIA GeForce RTX 4090, 1 GPU.
 ```
 
-### 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
+Create a Serverless endpoint named my-endpoint with image
+runpod/test-output:0.0.1, GPU pool AMPERE_80, 0 min workers, 3 max workers.
 ```
 
-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`. This is what powers the hosted server at `https://mcp.getrunpod.io/`.
-
-The hosted transport is stateless:
-
-- Each request creates a fresh MCP server instance.
-- The caller must send `Authorization: Bearer <token>`.
-- No credentials are cached or shared server-side.
+On the v2 API (the default), endpoints are image-based — pass an image and a GPU pool (a `pool` value from `list-gpu-types`), not a template.
 
-### Hosted auth
+See [`docs/configuration.md`](docs/configuration.md) for REST v1/v2 selection and the `templateId` migration note, private image pull (registry credentials vs ECR delegation), and large-output handling.
 
-The server forwards the caller's Bearer token directly to the Runpod API as the credential for that request. There is no server-side or shared key.
+## Security
 
-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 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)
-
-In OAuth mode the hosted server is itself the authorization server for Claude's connector. It advertises itself in `/.well-known/oauth-protected-resource` and `/.well-known/oauth-authorization-server`, pointing `authorization_endpoint` at its own `GET /authorize`, `token_endpoint` at its own `POST /token`, and `registration_endpoint` at its own `POST /register`.
-
-The flow reuses the Runpod flash auth backend and mints a real Runpod API key:
-
-1. The client registers via `POST /register` (OAuth Dynamic Client Registration, RFC 7591) to obtain a `client_id`. This is a public client; no client secret is used.
-2. `GET /authorize` calls the guest `createFlashAuthRequest` mutation to get a request id (which serves as the OAuth authorization code), then `302`-redirects the browser to the console handoff page (`/integrations/mcp/login`), carrying the request id plus the client's `redirect_uri` and `state`.
-3. The user logs in and approves the request in the console. On approval the backend mints a Runpod API key for the request.
-4. The console returns the browser to the client's `redirect_uri` with `code=<request id>`.
-5. `POST /token` polls the guest `flashAuthRequestStatus` query for that id; once `APPROVED`, it returns the minted `apiKey` as the `access_token`. The client then sends that key as its bearer token on every MCP request, and the server forwards it to the Runpod API.
-
-This flow uses these environment variables:
-
-- `RUNPOD_GRAPHQL_URL`: flash auth backend endpoint (default `https://api.runpod.io/graphql`).
-- `CONSOLE_BASE_URL`: base URL of the console that hosts the handoff login page (default `https://console.runpod.io`).
-- `RUNPOD_REST_API_URL` / `RUNPOD_SERVERLESS_API_URL`: override the REST and Serverless API hosts so a deployment authenticating with non-production keys can target the matching environment.
-- `RUNPOD_API_KEY_NAME`: name for the minted key as shown in the user's dashboard. Defaults to `runpod-mcp`. Set it to `""` to omit the name for a backend that does not support the `apiKeyName` argument (such backends reject the request when it is sent).
-- `MCP_ALLOWED_REDIRECT_URIS`: comma-separated extra `redirect_uri` values to allow, in addition to the built-in Claude callbacks. Loopback addresses (`localhost`/`127.0.0.1`/`::1`, any port) are always allowed. `/authorize` and `/token` reject any `redirect_uri` not on this list, since the authorization code redeems into a real API key.
-
-You can verify the entire flow end to end with `MCP_SERVER_URL=<deployment-url> npx tsx scripts/oauth-e2e.ts` (the harness uses a loopback callback).
-
-Notes and current limitations:
-
-- PKCE is not supported: `code_challenge` is neither advertised nor enforced (the flash flow has no place to bind it). Security relies on the `redirect_uri` allowlist and the single-use, short-lived flash approval.
-- The minted key is named via `RUNPOD_API_KEY_NAME` (default `runpod-mcp`), which requires a flash backend that supports the `apiKeyName` argument. Against a backend without it, set `RUNPOD_API_KEY_NAME=""`.
-
-### Vercel
-
-This repo already contains `vercel.json` and the Vercel handler.
-
-Deploy with the Vercel CLI:
-
-```bash
-vercel
-vercel --prod
-```
+This server acts with the full permissions of the supplied API key.
 
-After deploy, test the endpoint:
-
-```bash
-curl -i https://YOUR-DEPLOYMENT.vercel.app/
-```
-
-Unauthenticated requests should return `401`.
-
-### Hosted smoke test
-
-```bash
-MCP_SERVER_URL=https://YOUR-DEPLOYMENT.vercel.app \
-RUNPOD_API_KEY=YOUR_API_KEY \
-pnpm smoke:http
-```
-
-This validates:
-
-- MCP initialization.
-- `tools/list`.
-- A public GraphQL-backed tool call.
-- An authenticated REST-backed tool call.
+- Never share your API key.
+- Be deliberate with destructive tools.
+- Each request authenticates with its own caller-supplied token, which is forwarded to the Runpod API and **never persisted server-side**. The server never holds a credential of its own and never shares one across users.
 
 ## Local development
 
@@ -280,161 +165,16 @@ Run the local build directly:
 RUNPOD_API_KEY=YOUR_API_KEY node dist/stdio.mjs
 ```
 
-Or point a client at your local build:
-
-```json
-{
-  "command": "node",
-  "args": ["/absolute/path/to/runpod-mcp/dist/stdio.mjs"],
-  "env": {
-    "RUNPOD_API_KEY": "YOUR_API_KEY"
-  }
-}
-```
-
-### Local smoke test
-
-```bash
-RUNPOD_API_KEY=YOUR_API_KEY pnpm build
-RUNPOD_API_KEY=YOUR_API_KEY pnpm smoke:stdio
-```
-
-## Contributing
-
-The source is now split by responsibility:
-
-- `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`: 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:
 
 ```bash
 pnpm type-check
 pnpm lint
-pnpm test
+pnpm test    # offline unit suite — no network or API key required
 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
-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`.
-
-- Never share your API key.
-- Be deliberate about destructive tools.
-- Treat hosted deployments as sensitive infrastructure.
-- Each request authenticates with its own caller-supplied token, which is forwarded to the Runpod API and never persisted server-side.
+This project uses [changesets](https://github.com/changesets/changesets) for versioning and npm publishing; every PR with user-facing changes needs a changeset. See `CLAUDE.md` and `docs/context.md` for full contributor guidance, architecture, and the test suite.
 
 ## License