@runpod/mcp-server 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # @runpod/mcp-server
 
+## 1.3.0
+
+### Minor Changes
+
+- 3e6dedf: Add HTTP transport for hosted MCP server deployments. The package now exports three entrypoints: `@runpod/mcp-server` (stdio, unchanged), `@runpod/mcp-server/http` (streamable HTTP with per-request auth), and `@runpod/mcp-server/tools` (shared tool definitions). This enables deploying the MCP server on Vercel or any HTTP-capable host where each request carries its own RunPod API key via the Authorization header. Existing stdio users are unaffected.
+- 3e6dedf: Add a "Sign in with Runpod" OAuth flow to the hosted HTTP server so it can act as the authorization server for Claude's MCP connector. When `MCP_OAUTH_ENABLED=true`, the server advertises itself in the OAuth discovery metadata and exposes `GET /authorize` and `POST /token`. The flow reuses the Runpod flash auth backend: `/authorize` creates a guest `createFlashAuthRequest` and hands off to the Runpod console for approval, and `/token` polls `flashAuthRequestStatus` and returns the minted Runpod API key as the access token, which the server then forwards to the Runpod API. The backend endpoint and console base URL are configurable via `RUNPOD_GRAPHQL_URL` and `CONSOLE_BASE_URL`.
+- 3e6dedf: Complete the hosted OAuth flow for real MCP clients. Add an OAuth 2.0 Dynamic Client Registration endpoint (`POST /register`, RFC 7591) and advertise it as `registration_endpoint`, so clients like Claude can register before signing in. Make the Runpod REST and Serverless API hosts configurable via `RUNPOD_REST_API_URL` and `RUNPOD_SERVERLESS_API_URL` so a deployment authenticating with non-production keys can target the matching environment. The console handoff path is `/integrations/mcp/login`.
+- 3e6dedf: Validate the OAuth `redirect_uri` against an allowlist. Because the authorization code redeems into a real Runpod API key, `/authorize` and `/token` now reject any `redirect_uri` that is not an allowlisted client callback, preventing an attacker from crafting an authorize link that delivers the code (and key) to a host they control. Loopback addresses (`http://localhost` / `127.0.0.1` / `::1`, any port) are always allowed per RFC 8252; the hosted client callbacks default to Claude's, and the list is extendable via `MCP_ALLOWED_REDIRECT_URIS` (comma-separated).
+- 3e6dedf: Address hosted OAuth review feedback:
+  - Remove the `MCP_OAUTH_ENABLED` flag — the hosted HTTP server always advertises the OAuth sign-in challenge. Callers that bring their own Runpod API key as the bearer token are unaffected (they never hit the challenge).
+  - Default `CONSOLE_BASE_URL` to the production console (`https://console.runpod.io`) so a deploy that forgets to set it doesn't silently redirect users to localhost.
+  - `/token` now polls for most of the function budget (~45s) instead of returning a non-retryable `authorization_pending` after ~10s, avoiding a dead-end when console→backend approval propagation lags.
+  - Caller-tracking falls back to the inbound HTTP `User-Agent` on the stateless HTTP transport, where the per-request server never sees the MCP `initialize` `clientInfo` (previously reported `client=unknown`).
+  - Stop advertising PKCE (`S256`) since it isn't enforced server-side; security rests on the `redirect_uri` allowlist and the single-use flash approval.
+  - Default the minted key name to `runpod-mcp` (`RUNPOD_API_KEY_NAME`), so hosted keys are identifiable/revocable. Set `RUNPOD_API_KEY_NAME=""` to suppress it for a backend that has not shipped the `apiKeyName` argument.
+
+- 3e6dedf: Simplify hosted HTTP auth to pure token passthrough. The server now forwards the caller's Bearer token directly to the Runpod API and holds no credential of its own — there is no shared server-side key and no token translation. When `MCP_OAUTH_ENABLED=true`, unauthenticated requests return a `WWW-Authenticate` challenge so OAuth-capable clients start the "Sign in with Runpod" flow. Removes the `RUNPOD_HTTP_SHARED_API_KEY` environment variable and the `jose` dependency.
+
+### Patch Changes
+
+- 3e6dedf: Support naming the minted Runpod API key in the OAuth flow. Set `RUNPOD_API_KEY_NAME` (e.g. `runpod-mcp`) to pass `apiKeyName` through to the flash backend's `createFlashAuthRequest`, so the key shows up under that name in the user's dashboard. It is omitted by default for compatibility with backends that don't yet support the argument.
+- 3e6dedf: Address low-severity review nits on the hosted HTTP / OAuth path:
+  - Make the public discovery GraphQL host configurable via `RUNPOD_PUBLIC_GRAPHQL_URL` (was hardcoded to prod, so a dev deploy hit prod GraphQL).
+  - Report the real package version in the hosted server's outbound `User-Agent` (read from package.json at runtime, since tsup's build-time define doesn't run when Vercel compiles `api/index.ts`).
+  - Gate OAuth request-id / handoff-URL logging behind `MCP_VERBOSE_LOGS` (request ids are live, single-use auth codes).
+  - `stream-job` now surfaces the most recent polling error in its timeout payload instead of discarding it.
+  - Pass the parsed request body to the MCP transport explicitly; dispose the per-request server/transport on response close; guard `getBaseUrl` against a missing `Host`; handle a `Buffer` request body in the token endpoint.
+  - Single CORS source of truth (handler, not `vercel.json`); stop serving the whole repo as static assets; add an `oauth-e2e` npm script and `engines.pnpm`; fix docs that misattributed the OAuth routes and listed the new env vars.
+
+## 1.2.0
+
+### Minor Changes
+
+- 7b715eb: Add list-gpu-types and list-data-centers tools using public GraphQL API for hardware and region discovery. Enhance list-templates with filter params (includeRunpodTemplates, includePublicTemplates, includeEndpointBoundTemplates). Add tool descriptions to create-pod and list-templates recommending Pytorch 2.8.0 as default template.
+- ea2451b: Add Serverless endpoint runtime tools for invoking deployed workers. New tools: run-endpoint (async), runsync-endpoint (sync), get-job-status, stream-job, cancel-job, retry-job, endpoint-health, and purge-endpoint-queue. These use the Serverless API at api.runpod.ai/v2 with a new serverlessRequest helper.
+- 34c0463: Add caller tracking headers to every outbound API call. Each request now carries a structured `User-Agent` (`runpod-mcp-server/<version> (caller=mcp; client=<mcp_client_name>; client_version=<mcp_client_version>; transport=<stdio|http>)`) and an anonymous per-process `X-Runpod-Session-Id` UUID. The MCP client identity is sourced from the `initialize` handshake's `clientInfo`. No tool behavior changes — observability only — so the Runpod platform can attribute traffic to specific MCP clients (Claude Code, Cursor, Codex, Gemini CLI, etc.) and count distinct agent sessions.
+
 ## 1.1.0
 
 ### Minor Changes

package/README.md

@@ -1,101 +1,300 @@
-# Runpod MCP Server
+# Runpod MCP server
+
 [![smithery badge](https://smithery.ai/badge/@runpod/runpod-mcp-ts)](https://smithery.ai/server/@runpod/runpod-mcp-ts)
 
-This Model Context Protocol (MCP) server enables you to interact with the Runpod REST API through Claude or other MCP-compatible clients.
+This is the official Runpod Model Context Protocol (MCP) server, published to npm as `@runpod/mcp-server`.
+
+It supports two deployment modes:
 
-## Features
+- 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 provides tools for managing:
+The server never holds a credential of its own and never shares one across users.
 
-- **Pods**: Create, list, get details, update, start, stop, and delete pods
-- **Endpoints**: Create, list, get details, update, and delete serverless endpoints
-- **Templates**: Create, list, get details, update, and delete templates
-- **Network Volumes**: Create, list, get details, update, and delete network volumes
-- **Container Registry Authentications**: Create, list, get details, and delete authentications
+## Requirements
 
-## Quick Start
+- Node.js 18 or higher.
+- A Runpod account and API key: https://www.runpod.io/console/user/settings
 
-### Prerequisites
+## Quick start
 
-- Node.js 18 or higher
-- A Runpod account and API key ([get your API key](https://www.runpod.io/console/user/settings))
+### Run locally with `npx`
 
-### Running with npx
+```bash
+RUNPOD_API_KEY=YOUR_API_KEY npx -y @runpod/mcp-server@latest
+```
 
-You can run the server directly without installation:
+### Install via Smithery
 
 ```bash
-RUNPOD_API_KEY=your_api_key_here npx @runpod/mcp-server@latest
+npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
 ```
 
-### Installing via Smithery
+## Local MCP clients
+
+Local MCP clients should use the default package entrypoint, which is the `stdio` server.
 
-To install for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@runpod/runpod-mcp-ts):
+### Claude Code
 
 ```bash
-npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
+claude mcp add runpod -s user \
+  -e RUNPOD_API_KEY=YOUR_API_KEY \
+  -- npx -y @runpod/mcp-server@latest
 ```
 
-## Setting up with Claude for Desktop
+For a project-local server:
+
+```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`.
 
-1. Open Claude for Desktop
-2. Edit the config file:
-   - macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-   - Windows: `%APPDATA%\Claude\claude_desktop_config.json`
-3. Add the server configuration:
+macOS:
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`
+
+Windows:
+
+`%APPDATA%\\Claude\\claude_desktop_config.json`
 
 ```json
 {
   "mcpServers": {
     "runpod": {
       "command": "npx",
-      "args": ["@runpod/mcp-server@latest"],
+      "args": ["-y", "@runpod/mcp-server@latest"],
       "env": {
-        "RUNPOD_API_KEY": "your_api_key_here"
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
       }
     }
   }
 }
 ```
 
-4. Restart Claude for Desktop
+Restart Claude Desktop after saving.
 
-## Usage Examples
+### Cursor
 
-### List all pods
+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"
+      }
+    }
+  }
+}
 ```
-Can you list all my Runpod pods?
+
+### 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
+
+## 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 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.
+
+### Hosted auth
+
+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.
+
+## 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
+git clone https://github.com/runpod/runpod-mcp.git
+cd runpod-mcp
+pnpm install
+pnpm build
 ```
 
-### Create a new pod
+Run the local build directly:
 
+```bash
+RUNPOD_API_KEY=YOUR_API_KEY node dist/stdio.mjs
 ```
-Create a new Runpod pod with the following specifications:
+
+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
+```
+
+## 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
+### Create a Serverless endpoint
 
-```
-Create a Runpod serverless endpoint with the following configuration:
+```text
+Create a Runpod Serverless endpoint with the following configuration:
 - Name: my-endpoint
 - Template ID: 30zmvf89kd
 - Minimum workers: 0
 - Maximum workers: 3
 ```
 
-## Security Considerations
+## Contributing
+
+The source is now split by responsibility:
+
+- `src/stdio.ts`: local `stdio` entrypoint.
+- `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/server.ts`: shared server metadata and construction.
+- `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 build
+```
+
+For transport validation:
+
+```bash
+pnpm smoke:stdio
+pnpm smoke:http
+```
+
+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.
+
+## Security considerations
 
-This server requires your Runpod API key, which grants full access to your Runpod account. For security:
+This server acts with the full permissions of the supplied `RUNPOD_API_KEY`.
 
-- Never share your API key
-- Be cautious about what operations you perform
-- Consider setting up a separate API key with limited permissions
-- Don't use this in a production environment without proper security measures
+- 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.
 
 ## License