@runpod/mcp-server 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# @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
+
+- 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

@@ -1,133 +1,239 @@
-# 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
+- Node.js 18 or higher.
+- A Runpod account and API key ([get your API key](https://www.runpod.io/console/user/settings)).
 
-## Setup
+### Running with npx
 
-### Prerequisites
+You can run the server directly without installation:
 
-- Node.js 18 or higher
-- A RunPod account and API key
-- Claude for Desktop or another MCP-compatible client
+```bash
+RUNPOD_API_KEY=YOUR_API_KEY npx @runpod/mcp-server@latest
+```
 
 ### Installing via Smithery
 
-To install runpod-mcp-ts for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@runpod/runpod-mcp-ts):
+To install for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@runpod/runpod-mcp-ts):
 
 ```bash
 npx -y @smithery/cli install @runpod/runpod-mcp-ts --client claude
 ```
 
-### Installation
+## Setting up with your client
 
-1. Clone the repository
-2. Install dependencies:
-   ```
-   pnpm install
-   ```
-3. Build the server:
-   ```
-   pnpm build
-   ```
+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.
 
-### Configuration
+### Claude Code
 
-Set your RunPod API key as an environment variable:
+Add the MCP server globally so it's available across all your projects:
 
 ```bash
-# Linux/macOS
-export RUNPOD_API_KEY=your_api_key_here
+claude mcp add runpod -s user \
+  -e RUNPOD_API_KEY=YOUR_API_KEY \
+  -- npx -y @runpod/mcp-server@latest
+```
 
-# Windows (Command Prompt)
-set RUNPOD_API_KEY=your_api_key_here
+Or add it to a specific project (creates a `.mcp.json` file you can commit):
 
-# Windows (PowerShell)
-$env:RUNPOD_API_KEY="your_api_key_here"
+```bash
+claude mcp add runpod -s project \
+  -e RUNPOD_API_KEY=YOUR_API_KEY \
+  -- npx -y @runpod/mcp-server@latest
 ```
 
-You can get your API key from the [RunPod console](https://www.runpod.io/console/user/settings).
+Verify the server is connected with `claude mcp list`. If you're in an active session, type `/mcp` to reconnect without restarting.
 
-### Running the Server
+### Claude Desktop
 
-Start the server:
+Edit the config file at `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
 
-```bash
-pnpm start
+```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"
+      }
+    }
+  }
+}
 ```
 
-## Setting up with Claude for Desktop
+Click the "Start" button next to the server entry to connect.
+
+### Cline
 
-1. Open Claude for Desktop
-2. Edit the config file: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows)
-3. Add the server configuration:
+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
+
+Create a `mcp.json` file at `~/.junie/mcp.json` (global) or `.junie/mcp/` in your project:
 
 ```json
 {
   "mcpServers": {
     "runpod": {
-      "command": "node",
-      "args": ["/path/to/mcp-server/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@runpod/mcp-server@latest"],
       "env": {
-        "RUNPOD_API_KEY": "your_api_key_here"
+        "RUNPOD_API_KEY": "YOUR_API_KEY"
       }
     }
   }
 }
 ```
 
-Make sure to replace the `"args": ["/path/to/mcp-server/dist/index.js"]` with the path to the dist folder in the repository.
+### Other clients
+
+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).
+
+## 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:
 
-4. Restart Claude for Desktop
+```json
+{
+  "command": "node",
+  "args": ["/absolute/path/to/runpod-mcp/dist/index.mjs"]
+}
+```
 
-## Usage Examples
+After making changes to the source, re-run `pnpm build` and restart or reconnect the MCP server for changes to take effect.
 
-Here are some examples of how to use the server with Claude:
+## Usage examples
 
-### List all pods
+### 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 };