@runpod/mcp-server 2.0.0 → 3.1.0

package/CHANGELOG.md

@@ -1,5 +1,100 @@
 # @runpod/mcp-server
 
+## 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
+
+- 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
@@ -65,7 +160,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).
@@ -102,4 +197,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,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,152 +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/`.
+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.
 
-The hosted transport is stateless:
+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.
 
-- Each request creates a fresh MCP server instance.
-- The caller must send `Authorization: Bearer <token>`.
-- No credentials are cached or shared server-side.
+## Security
 
-### Hosted auth
+This server acts with the full permissions of the supplied API key.
 
-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.
-
-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.
-
-### 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
-```
-
-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
 
@@ -278,153 +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.                                                                          |
-
-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`) return a clear "v2 only" notice when called under v1.
-
-> **⚠️ 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.
-
-- `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.
-
-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