@runpod/mcp-server 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @runpod/mcp-server
 
+## 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,31 +1,21 @@
-# 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 Model Context Protocol (MCP) server lets you manage Runpod infrastructure through any MCP-compatible client. It provides tools for working with Pods, Serverless endpoints, templates, network volumes, and container registry authentications.
 
-## Features
+## Quick start
 
-The server provides tools for managing:
+### Requirements
 
-- **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
-
-## Quick Start
-
-### Prerequisites
-
-- Node.js 18 or higher
-- A Runpod account and API key ([get your API key](https://www.runpod.io/console/user/settings))
+- Node.js 18 or higher.
+- A Runpod account and API key ([get your API key](https://www.runpod.io/console/user/settings)).
 
 ### Running with npx
 
 You can run the server directly without installation:
 
 ```bash
-RUNPOD_API_KEY=your_api_key_here npx @runpod/mcp-server@latest
+RUNPOD_API_KEY=YOUR_API_KEY npx @runpod/mcp-server@latest
 ```
 
 ### Installing via Smithery
@@ -36,66 +26,214 @@ To install for Claude Desktop automatically via [Smithery](https://smithery.ai/s
 npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
 ```
 
-## Setting up with Claude for Desktop
+## Setting up with your client
+
+Most MCP clients use a JSON configuration file with the same general structure. The examples below show the npx approach (recommended for most users) and the local build approach (for development). Replace `YOUR_API_KEY` with your actual Runpod API key.
+
+### Claude Code
+
+Add the MCP server globally so it's available across all your projects:
+
+```bash
+claude mcp add runpod -s user \
+  -e RUNPOD_API_KEY=YOUR_API_KEY \
+  -- npx -y @runpod/mcp-server@latest
+```
+
+Or add it to a specific project (creates a `.mcp.json` file you can commit):
+
+```bash
+claude mcp add runpod -s project \
+  -e RUNPOD_API_KEY=YOUR_API_KEY \
+  -- npx -y @runpod/mcp-server@latest
+```
+
+Verify the server is connected with `claude mcp list`. If you're in an active session, type `/mcp` to reconnect without restarting.
+
+### Claude Desktop
+
+Edit the config file at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "runpod": {
+      "command": "npx",
+      "args": ["-y", "@runpod/mcp-server@latest"],
+      "env": {
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after saving.
+
+### Cursor
+
+Add the following to `.cursor/mcp.json` in your project directory, or `~/.cursor/mcp.json` for global access:
+
+```json
+{
+  "mcpServers": {
+    "runpod": {
+      "command": "npx",
+      "args": ["-y", "@runpod/mcp-server@latest"],
+      "env": {
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Open Windsurf settings (Cmd+Shift+P → "Open Windsurf Settings"), navigate to the Cascade section, and enable MCP. Then edit `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "runpod": {
+      "command": "npx",
+      "args": ["-y", "@runpod/mcp-server@latest"],
+      "env": {
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+### VS Code (GitHub Copilot)
+
+MCP works in VS Code's agent mode (requires VS Code 1.101+). Add the following to `.vscode/mcp.json` in your workspace:
+
+```json
+{
+  "mcpServers": {
+    "runpod": {
+      "command": "npx",
+      "args": ["-y", "@runpod/mcp-server@latest"],
+      "env": {
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
+      }
+    }
+  }
+}
+```
+
+Click the "Start" button next to the server entry to connect.
+
+### Cline
+
+Open Cline in VS Code, click the hamburger menu (☰), and go to MCP Servers. You can add servers through the marketplace or manually configure in Cline's settings using the same JSON structure shown above.
+
+### JetBrains IDEs
 
-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:
+Create a `mcp.json` file at `~/.junie/mcp.json` (global) or `.junie/mcp/` in your project:
 
 ```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
+### Other clients
 
-## Usage Examples
+This server uses stdio transport and works with any MCP-compatible client. The configuration pattern is the same across all clients — point the command to `npx` with `@runpod/mcp-server@latest` as the argument, and set `RUNPOD_API_KEY` in the environment. For a full list of MCP clients, see the [official MCP clients page](https://modelcontextprotocol.io/clients).
 
-### List all pods
+## Using a local build
+
+If you want to run from a local clone of the repo (for development or to test unreleased changes):
+
+```bash
+git clone https://github.com/runpod/runpod-mcp.git
+cd runpod-mcp
+pnpm install
+pnpm build
+```
+
+Then replace the `command` and `args` in any of the configurations above with:
+
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/runpod-mcp/dist/index.mjs"]
+}
+```
+
+After making changes to the source, re-run `pnpm build` and restart or reconnect the MCP server for changes to take effect.
+
+## Usage examples
+
+### List all Pods
 
 ```
-Can you list all my Runpod pods?
+Can you list all my Runpod Pods?
 ```
 
-### Create a new pod
+### Create a new Pod
 
 ```
-Create a new Runpod pod with the following specifications:
+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:
+Create a Runpod Serverless endpoint with the following configuration:
 - Name: my-endpoint
 - Template ID: 30zmvf89kd
 - Minimum workers: 0
 - Maximum workers: 3
 ```
 
-## Security Considerations
+## Contributing
+
+To get started with local development, clone the repo and build:
+
+```bash
+git clone https://github.com/runpod/runpod-mcp.git
+cd runpod-mcp
+pnpm install
+pnpm build
+```
+
+After making changes, rebuild with `pnpm build`. In Claude Code, type `/mcp` to reconnect to the updated server without restarting your session. You can also use `pnpm build:watch` for auto-rebuilding during development.
+
+All tools live in `src/index.ts`. The server uses two backends: the REST API (`runpodRequest()`) for authenticated CRUD operations, and the GraphQL API (`graphqlRequest()`) for public read-only queries like GPU types and data centers. Follow existing patterns when adding new tools — kebab-case names, Zod schemas with `.describe()`, and JSON stringified responses.
+
+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`:
+
+```markdown
+---
+"@runpod/mcp-server": minor
+---
+
+Description of what changed and why.
+```
+
+Use `patch` for bug fixes, `minor` for new tools or features, and `major` for breaking changes. The `.changeset/` directory is gitignored, so use `git add -f` to stage changeset files.
+
+See [CLAUDE.md](./CLAUDE.md) for the full development guide including architecture details, tool conventions, and known issues.
 
-This server requires your Runpod API key, which grants full access to your Runpod account. For security:
+## Security considerations
 
-- 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
+This server requires your Runpod API key, which grants full access to your Runpod account. Never share your API key. Be cautious about what operations you perform, and consider setting up a separate API key with limited permissions. Do not use this in a production environment without proper security measures.
 
 ## License
 

package/dist/index.d.cts

@@ -1,2 +1,3 @@
+declare function setTransport(t: 'stdio' | 'http'): void;
 
-export {  }
+export { setTransport };

package/dist/index.d.ts

@@ -1,2 +1,3 @@
+declare function setTransport(t: 'stdio' | 'http'): void;
 
-export {  }
+export { setTransport };