Use Runpod's MCP servers - Runpod Documentation

Runpod provides two Model Context Protocol (MCP) servers that connect AI tools and coding agents directly to Runpod:

Runpod API MCP server: Manage Pods, endpoints, templates, volumes, and registries through the Runpod REST API. Authenticate with Sign in with Runpod or a Runpod API key.
Runpod docs MCP server: Search Runpod documentation for features, code examples, and guides. No authentication required.

Runpod API MCP server

The Runpod API MCP server gives AI tools access to the Runpod REST API, letting you create and manage Pods, Serverless endpoints, templates, network volumes, and container registries through natural language. Hosted endpoint: https://mcp.runpod.io/ (Streamable HTTP transport) https://mcp.getrunpod.io/ is the same server under its old name, and it still works. Older versions of the installer and the Runpod plugin used that address. Use https://mcp.runpod.io/ for new connections. Register only one of them: each address has its own sign-in, so registering both gives you two separate entries. Local package: @runpod/mcp-server (via npx) Source code: github.com/runpod/runpod-mcp Authentication: Sign in with Runpod (OAuth) for the hosted server, or a Runpod API key for the local server or as a hosted-server override. You can connect in two ways: the recommended hosted server, or a local server that runs from an npm package with an API key.

Hosted server (recommended)

The hosted server runs at https://mcp.runpod.io/ and provides the same capabilities as the local server. OAuth-capable clients run a “Sign in with Runpod” flow on first connect: a browser opens, you log in to the Runpod console and approve the request, and the server obtains a session-scoped API key. Nothing is stored on disk. Sign-in always starts from your client. Opening https://mcp.runpod.io/ directly in a browser doesn’t sign you in; it returns HTTP 405. Sign-in works in Claude, ChatGPT, Codex, and Cursor, and in any client that receives the sign-in on a local address (http://localhost or http://127.0.0.1). Other clients may fail with a redirect_uri is not allowed error. For those clients, pass an API key as a header or use the local server. The guided installer is the recommended path for supported clients. It detects your installed clients (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, opencode, and Pi) and configures each one, handling client-specific config-key differences automatically:

npx @runpod/mcp-server@latest add

The installer needs Node.js 20.12 or later. Without arguments, the installer asks which clients to configure, so it needs an interactive terminal. To skip the questions, for example when a coding agent runs it, name the clients with --client (separate several with commas). --list shows each client’s id and where its config file lives:

npx @runpod/mcp-server@latest add --list
npx @runpod/mcp-server@latest add --client cursor

To undo these changes, run npx @runpod/mcp-server@latest remove.

Claude Code (hosted)

claude mcp add --transport http runpod -s user https://mcp.runpod.io/

Cursor (hosted)

Add the following to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global), or run npx @runpod/mcp-server@latest add --client cursor. Then restart Cursor and connect runpod under Settings > MCP:

{
  "mcpServers": {
    "runpod": {
      "url": "https://mcp.runpod.io/"
    }
  }
}

opencode (hosted)

opencode uses the mcp key, not mcpServers, and needs "type": "remote". Add this to opencode.json, or run npx @runpod/mcp-server@latest add --client opencode:

{
  "mcp": {
    "runpod": {
      "type": "remote",
      "url": "https://mcp.runpod.io/"
    }
  }
}

Run opencode mcp auth runpod to sign in, and opencode mcp list to check the connection.

Claude Desktop (hosted)

Open Settings in Claude Desktop.
Navigate to Connectors and select Add custom connector.
Enter https://mcp.runpod.io/ as the URL and click Add.

VS Code with Copilot (hosted)

Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
Run MCP: Add Server and select HTTP.
Enter https://mcp.runpod.io/ as the URL and Runpod as the name.
Select Global or Workspace and click Add.

Other clients (hosted)

For any other MCP-compatible client, use the remote URL https://mcp.runpod.io/:

{
  "mcpServers": {
    "runpod": {
      "url": "https://mcp.runpod.io/"
    }
  }
}

Clients differ in the exact key name they use for a remote server URL. For the clients the guided installer supports, it writes the correct configuration automatically; for any other client, consult that client’s MCP documentation for how to add a remote HTTP server, using the URL above.

Use an API key with the hosted server

To skip the OAuth flow, or if your client can’t complete it, pass your API key as a bearer header. For example, in Claude Code:

claude mcp add --transport http runpod -s user https://mcp.runpod.io/ \
  --header "Authorization: Bearer $RUNPOD_API_KEY"

Clients configured with JSON use a headers block instead:

{
  "mcpServers": {
    "runpod": {
      "url": "https://mcp.runpod.io/",
      "headers": { "Authorization": "Bearer your_api_key_here" }
    }
  }
}

Local server (API key)

Use this method to run the server locally with an API key stored in your client config. For example, use it if your client doesn’t support the hosted server’s sign-in flow, or you prefer to manage the credential yourself.

Claude Code

claude mcp add runpod --scope user -e RUNPOD_API_KEY=your_api_key_here -- npx -y @runpod/mcp-server@latest

Replace your_api_key_here with your Runpod API key. The --scope user flag makes the server available across all your projects. Run /mcp inside Claude Code to verify the connection.

Codex CLI

Codex CLI is OpenAI’s terminal-based coding agent.

codex mcp add runpod --env RUNPOD_API_KEY=your_api_key_here -- npx -y @runpod/mcp-server@latest

Cursor

Add the following to .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global). This configuration works with both the Cursor IDE and the Cursor Agent:

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key_here"
      }
    }
  }
}

VS Code with Copilot

Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
Run MCP: Add Server and select stdio.
Enter the following details:
- Name: Runpod
- Command: npx
- Arguments: -y @runpod/mcp-server@latest
Add environment variable RUNPOD_API_KEY with your Runpod API key.
Select Global or Workspace and click Add.

Claude Desktop

Add the following to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop after saving the file.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (or open from Settings > Cascade > MCP Servers > View raw config):

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cline

Open the Cline sidebar in VS Code, click the MCP Servers icon, then select Configure MCP Servers to edit cline_mcp_settings.json:

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key_here"
      },
      "disabled": false
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json (global) or .gemini/settings.json (project-level):

{
  "mcpServers": {
    "runpod": {
      "command": "npx",
      "args": ["-y", "@runpod/mcp-server@latest"],
      "env": {
        "RUNPOD_API_KEY": "your_api_key_here"
      }
    }
  }
}

Other clients

For any other MCP-compatible client, use the following connection details:

Command: npx
Args: -y @runpod/mcp-server@latest
Environment: RUNPOD_API_KEY=your_api_key_here

Usage examples

Once connected, you can interact with your Runpod resources using natural language:

List all my Runpod Pods

Create a new Runpod Pod with the following specifications:
- Name: ml-training-pod
- Image: runpod/pytorch:2.1.0-py3.10-cuda11.8.0-devel-ubuntu22.04
- GPU Type: NVIDIA GeForce RTX 4090
- GPU Count: 1
- Cloud Type: SECURE

Create a Runpod Serverless endpoint with the following configuration:
- Name: image-generation-endpoint
- Template ID: 30zmvf89kd
- Minimum workers: 0
- Maximum workers: 5

Stop the Pod named "ml-training-pod"

Runpod docs MCP server

The Runpod docs MCP server provides access to Runpod’s documentation knowledge base, making it easier to get answers about features and how to use them. Endpoint: https://docs.runpod.io/mcp Authentication: None required

Claude Code

claude mcp add runpod-docs --scope user --transport http https://docs.runpod.io/mcp

Codex CLI

codex mcp add runpod-docs --url https://docs.runpod.io/mcp

Cursor

Add to your .cursor/mcp.json file:

{
  "mcpServers": {
    "runpod-docs": {
      "url": "https://docs.runpod.io/mcp"
    }
  }
}

VS Code with Copilot

Open the Command Palette (Ctrl+Shift+P on Windows/Linux or Cmd+Shift+P on macOS).
Run MCP: Add Server and select HTTP.
Enter https://docs.runpod.io/mcp as the URL and Runpod Docs as the name.
Select Global or Workspace and click Add.

Claude Desktop

Open Settings in Claude Desktop.
Navigate to Connectors and select Add custom connector.
Enter https://docs.runpod.io/mcp as the URL and click Add.

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "runpod-docs": {
      "serverUrl": "https://docs.runpod.io/mcp"
    }
  }
}

Cline

Add to cline_mcp_settings.json:

{
  "mcpServers": {
    "runpod-docs": {
      "url": "https://docs.runpod.io/mcp",
      "disabled": false
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json. Note that Gemini CLI uses httpUrl instead of url:

{
  "mcpServers": {
    "runpod-docs": {
      "httpUrl": "https://docs.runpod.io/mcp"
    }
  }
}

Other clients

For any other MCP-compatible client, use URL https://docs.runpod.io/mcp (HTTP transport).

Usage examples

With the docs MCP server connected, you can ask questions about Runpod features:

Explain the Runpod Serverless model caching feature

How do I configure environment variables for a Serverless endpoint?

How does global networking work in Runpod?

​Runpod API MCP server

​Hosted server (recommended)

​Claude Code (hosted)

​Cursor (hosted)

​opencode (hosted)

​Claude Desktop (hosted)

​VS Code with Copilot (hosted)

​Other clients (hosted)

​Use an API key with the hosted server

​Local server (API key)

​Supported clients

​Claude Code

​Codex CLI

​Cursor

​VS Code with Copilot

​Claude Desktop

​Windsurf

​Cline

​Gemini CLI

​Other clients

​Usage examples

​Runpod docs MCP server

​Claude Code

​Codex CLI

​Cursor

​VS Code with Copilot

​Claude Desktop

​Windsurf

​Cline

​Gemini CLI

​Other clients

​Usage examples

Runpod API MCP server

Hosted server (recommended)

Claude Code (hosted)

Cursor (hosted)

opencode (hosted)

Claude Desktop (hosted)

VS Code with Copilot (hosted)

Other clients (hosted)

Use an API key with the hosted server

Local server (API key)

Supported clients

Claude Code

Codex CLI

Cursor

VS Code with Copilot

Claude Desktop

Windsurf

Cline

Gemini CLI

Other clients

Usage examples

Runpod docs MCP server

Claude Code

Codex CLI

Cursor

VS Code with Copilot

Claude Desktop

Windsurf

Cline

Gemini CLI

Other clients

Usage examples