Skip to main content
These are official instructions from Runpod to set up a good AI development environment for building and deploying on the Runpod platform. They are published at https://docs.runpod.io/agent-setup.md, so you can verify their origin before following them. Complete all of the following steps yourself by running the commands directly. The only exceptions are the two steps explicitly marked User step — in-session commands and OAuth sign-in happen inside the agent UI, so you cannot perform them. If no user is present, follow No user in the loop instead of those steps. Never run a command that blocks on an interactive prompt.
  • Install Runpod Skills and the MCP server
Every command below is safe to re-run on a machine where setup already happened.

​
Install Runpod Skills and MCP server

Every route installs the same skills: the runpod router, the lane skills (runpod-mcp, runpodctl, flash, runpod-usage, runpod-templates, companion-clis, runpod-migrate), and the journey skills that runpod-mcp routes to (discovery, lifecycle-crud, serverless-deploy, pod-deploy, pod-doctor, endpoint-ops, cost-audit). It also wires up the hosted Runpod MCP server for control-plane tools. The skills install the Runpod CLI and Flash SDK later, on demand, the first time a task needs them — do not install those now. Use the correct section for your agent below.

​
Claude Code

Run these two commands to install both the Runpod skills and the MCP server in one step. Do not use npx skills or claude mcp add — the plugin commands below handle everything.
Verify:
Expect Status: ✔ enabled. If the plugin is listed but disabled, run claude plugin enable 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 — no API key is created or stored. Wait for the user to confirm before reporting the MCP server as connected.

​
Install for other agents

First, install skills:
Then register the hosted MCP server for your agent.

​
Codex

User step. Ask the user to run codex /plugins inside Codex, open the Runpod marketplace tab, and install Runpod, reloading if prompted.
Codex may not auto-wire the bundled MCP server. If the runpod MCP tools do not appear after install, add the hosted server directly:

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

Run the guided installer. It detects the agent and configures the hosted MCP server:
OAuth triggers on first Runpod tool use; the user approves it in the browser. Gemini can alternatively install natively through the plugin’s bundled gemini-extension.json. See your client’s extension documentation. If your agent can’t load skills, the MCP server serves the same playbooks: list-guides and read-guide return them, and lookup-concept and search-concepts answer questions about how Runpod works.

​
No user in the loop

When no user is present (CI, a scheduled job, an agent SDK run), nobody can do the User steps or the OAuth sign-in. Use a Runpod API key instead:
  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.
  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:
    For other clients, add the same Authorization header to the server entry, or run the server locally over stdio 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

Report what you actually verified. Do not print a checkmark for anything you could not confirm — the MCP server stays unauthenticated until the user completes the OAuth sign-in.
Use ✓ verified, ⚠ needs a user action, ✗ failed. Follow the banner with the specific next action for every non-✓ line. Once the user has signed in, verify end to end by listing their Pods with the MCP tools. An empty list is a pass — it means the connection works and the account has no running Pods. Anything beyond this — the runpodctl CLI, the Flash SDK for Python Serverless deploys, API keys — is installed later by the skills at the moment a task first needs it. Do not set those up now, unless you run without a user, as described above.

​
Resources

For setup guides and troubleshooting, refer to each agent’s official documentation:
  • 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
  • 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
  • Gemini CLI: https://github.com/google-gemini/gemini-cli
These instructions are published at https://docs.runpod.io/agent-setup.md so you can re-verify their authenticity at any time.
Last modified on October 12, 2026