Onboard your agent to Runpod

• Install Runpod Skills and the MCP server

​

Install Runpod Skills and MCP server

​

Claude Code

claude plugin marketplace add runpod/runpod-plugins-official
claude plugin install runpod@runpod

claude plugin list | grep -A2 'runpod@runpod'

User step. Ask the user to run /reload-plugins inside Claude Code to activate the plugin, then sign in to the MCP server with /mcp → runpod → Sign in with Runpod. This uses OAuth, so no API key is created or stored. Wait for the user to confirm before reporting the MCP server as connected.

​

Install for other agents

​

1. Install the skills

npx -y skills add runpod/runpod-plugins-official --skill '*' --agent <agent-id> --yes --global

npx -y skills list --global

​

2. Register the MCP server

​

Codex

codex plugin marketplace add https://github.com/runpod/runpod-plugins-official.git
codex plugin add runpod@runpod

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

​

Gemini CLI

gemini mcp add -s user -t http runpod https://mcp.runpod.io/

​

Pi

pi mcp add runpod --url https://mcp.runpod.io/

​

Hermes

hermes config set mcp_servers.runpod.url https://mcp.runpod.io/
hermes config set mcp_servers.runpod.auth oauth

User step. Ask the user to run hermes mcp login runpod and approve the sign-in in the browser. Then check with hermes mcp test runpod.

​

Grok Build

grok mcp add --transport http runpod https://mcp.runpod.io/

User step. In Grok, the user opens /mcps, selects runpod, and presses i to sign in.

​

Cursor, GitHub Copilot, Windsurf, Cline, opencode, and all other agents

npx @runpod/mcp-server@latest add --client <agent-id>

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

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

​

If OAuth sign-in fails

1. Ask the user to create a key on the Credentials page and set it as RUNPOD_API_KEY in the environment your agent starts from.
2. Send it as a header on the server entry, for example:
   {
     "mcpServers": {
       "runpod": {
         "url": "https://mcp.runpod.io/",
         "headers": { "Authorization": "Bearer ${RUNPOD_API_KEY}" }
       }
     }
   }
   
   ${RUNPOD_API_KEY} reads the key from the environment, but clients write this differently, so check your client’s docs. If your client can’t read environment variables, run the server locally instead, with RUNPOD_API_KEY set: npx -y @runpod/mcp-server@latest.

​

No user in the loop

1. Read the key from the RUNPOD_API_KEY environment variable. The runpodctl CLI and the Flash SDK read the same variable. Do not ask for the key, print it, or write it to a file. If it is not set, stop and report that it is missing. The variable must be set in the environment the agent starts from, for example as a CI secret, in a service unit, or in a shell profile. Clients that store only the variable’s name, such as pi mcp add --bearer-token-env-var RUNPOD_API_KEY, read the key from there each time they start.
2. Install the skills for your agent as above. Skip /reload-plugins: the plugin loads the next time the agent starts.
3. Connect the hosted MCP server with the key instead of OAuth:
   claude mcp add --transport http runpod -s user https://mcp.runpod.io/ --header "Authorization: Bearer $RUNPOD_API_KEY"
   
   For other clients, add the same Authorization header to the server entry, as in the JSON under If OAuth sign-in fails. For Gemini CLI, run gemini mcp add -s user -t http -H "Authorization: Bearer $RUNPOD_API_KEY" runpod https://mcp.runpod.io/. You can also run the server locally with RUNPOD_API_KEY set: npx -y @runpod/mcp-server@latest.
4. In headless Claude Code (claude -p), allow the Runpod skill and the MCP tools your task needs up front, for example --allowedTools "Skill(runpod:runpod-mcp)". Without Skill(runpod:runpod-mcp), the runpod-mcp skill is refused.
5. Write the result banner below to your log. Mark anything that still needs a person with ✗.

​

Report the result

┌─ Runpod Agent Setup ─────────────────────────────────┐
│  ✓ Runpod skills   router + lane + journey skills    │
│  ⚠ runpod MCP      needs sign-in: /mcp → runpod      │
│                                                      │
│  ⚡ Reload or restart your agent to load the skills  │
└──────────────────────────────────────────────────────┘

​

Feedback

• About these docs: submit_feedback on the Runpod docs MCP server (https://docs.runpod.io/mcp).
• About the Runpod product or the Runpod MCP tools: report_feedback on the Runpod MCP server (https://mcp.runpod.io/).

​

Resources

• Runpod agent skills: https://docs.runpod.io/get-started/agent-skills
• Runpod MCP servers: https://docs.runpod.io/get-started/mcp-servers
• Runpod skills plugin (source): https://github.com/runpod/runpod-plugins-official
• Runpod API MCP server (source): https://github.com/runpod/runpod-mcp
• Claude Code: https://docs.anthropic.com/en/docs/claude-code/mcp
• Codex: https://developers.openai.com/codex/mcp
• Cursor: https://cursor.com/docs/mcp
• Windsurf: https://docs.windsurf.com/windsurf/cascade/mcp
• GitHub Copilot (VS Code): https://code.visualstudio.com/docs/copilot/customization/mcp-servers
• opencode: https://opencode.ai/docs/mcp-servers
• Cline: https://docs.cline.bot/mcp/configuring-mcp-servers
• Gemini CLI: https://github.com/google-gemini/gemini-cli