在已连接 Runpod MCP 时用结构化工具调用管理…

当 Runpod MCP 工具（create-pod、list-endpoints 等）已在本会话连接，或需要连接它们时，用结构化工具调用而非手写 REST 调用来管理 Runpod 基础设施。

适用场景

解决思路

1. 多步任务在调用工具前先阅读 runpod/golden-paths/README.md 中的已验证端到端序列（镜像→模板→端点、Pod→卷→Serverless、多区域、自动扩缩、监控），本技能只说明每个工具做什么，golden paths 说明按什么顺序做以及成本。
2. 连接托管服务器时，若同时使用 runpodctl/flash，用 API key 作为 Bearer header（这一个 key 同时认证 MCP 和 CLI，是 80% 的路径）：claude mcp add --transport http runpod -s user https://mcp.getrunpod.io/ --header "Authorization: Bearer $RUNPOD_API_KEY"。
3. 若只做 MCP 相关工作，可用纯 OAuth（"Sign in with Runpod"，通过 npx @runpod/mcp-server@latest add），但它仅认证 MCP，CLI 仍处于未认证状态；本地 stdio 则以子进程方式运行服务器并使用你的 key。
4. 连接后重连客户端（在 Claude Code 中执行 /mcp）以加载工具。
5. 依赖 MCP 前先验证其可用：在 Claude Code 中运行 /mcp，runpod 应显示 Connected 而非 Needs authentication（若是后者先在那里登录）；通过请求 list-endpoints 确认真实调用可用；若 runpod 工具完全不存在，说明服务器未连接，重新运行安装或回退到 runpodctl。
6. 检查服务器版本（决定其驱动哪个 REST API）：MCP initialize 握手会在 serverInfo.version 中返回它；Claude Code 的 /mcp 会显示，或直接探测托管服务器：printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' | curl -s -X POST https://mcp.getrunpod.io/ -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -H "Authorization: Bearer $RUNPOD_API_KEY" -d @-。
7. 创建端点时优先使用 MCP 或 runpodctl，而非手写 rest.runpod.io/v1 调用。
8. Pods：使用 list、get、create、update、start、stop、restart、delete、stream logs 工具。
9. Serverless 端点：使用 list、get、create、update、delete；list workers；list releases；stream worker logs。日志不再是 MCP 独有——runpodctl v2.10.0 新增了 pod logs 和 serverless logs；MCP 返回已解析、有界帧，在 agent 内更易用，shell-only 或需要 --follow 时用 CLI；任务输出流（stream-job）仍仅 MCP 支持。
10. create-endpoint 接受 endpointType: QUEUE（默认）或 LOAD_BALANCER；路由类型在创建时固定，update-endpoint 无法更改。
11. 从 get/list 回复的 requestUrls 读取端点的调用 URL，而不是自行拼接。
12. 要在现有端点上固定特定 GPU SKU，使用 set-endpoint-gpus；create-endpoint/update-endpoint 只暴露 gpuPoolIds，无法表达 SKU（deploy-hub-repo 可在部署时通过 gpuIds 排除项固定一个）。
13. Jobs（Serverless 运行时）：使用 run、runsync、status、stream、cancel、retry、health、purge queue。
14. Hub：使用 list-hub-repos（预构建 Serverless worker 和 Pod 模板的公共目录：vLLM、ComfyUI 等）和 deploy-hub-repo，后者将仓库列出的 release 部署为端点，等同于在 Hub 上点击 Deploy。
15. Public endpoints：使用 list-public-endpoints 获取托管按用量付费的模型 API（文本/图像/视频/音频），无需部署；用 run-endpoint/runsync-endpoint 调用返回的 endpointId。
16. Templates：使用 list、get、create、update、delete。
17. Network volumes：使用 list、get、create、update、delete；create-network-volume 接受 volumeType（STANDARD | HIGH_PERFORMANCE）和 10–4096 GB 的大小；省略 volumeType 则使用数据中心的默认层级；层级在创建后不可变，update-network-volume 无法更改。
18. Container registry auth：使用 list、get、create、delete；为任意镜像仓库提供用户名+密码，将得到的 id 作为 containerRegistryAuthId 传给 create-pod/create-endpoint。
19. ECR delegations（list-/create-/delete-registry-delegation）：仅 AWS ECR、仅 v2，且不存储凭据——注册仓库 ARN，Runpod 获得范围受限的拉取权限；对 ECR 优先使用它而非存储用户名/密码；回复携带 dockerRegistryUri，即部署时使用的镜像 URI。
20. Catalog：使用 list/get GPU types、list/get CPU types、list/get data centers。
21. Billing：使用 get-billing 获取范围化的用量/成本明细。
22. 将工具列表视为地图而非契约：服务器是唯一事实来源，/mcp（或客户端的工具列表）显示所连接版本实际暴露的内容，每个工具自带参数说明；在假设某能力存在或不存在前先查看那里。
23. 删除工具（delete-template、delete-pod 等）即使成功也可能返回 isError: true 和 "Unexpected end of JSON input"，因为 Runpod REST API 返回 204 No Content；不要当作失败，用后续 get-/list- 确认（已删除资源会 404）。
24. 当工具已连接且任务是基础设施 CRUD 或服务器暴露的 Serverless 任务调用时使用 runpod-mcp；将大型任务/日志输出写入文件。
25. 以下情况改用 runpodctl：send/receive 文件传输、SSH 密钥管理、doctor 设置、模型缓存，或任何 shell-only agent，或用户想要可复现命令时。
26. 多 GPU 优先级列表的 Pod 创建交给 runpodctl（MCP 的 v2 create-pod 只接受一种 GPU 类型，额外的 gpuTypeIds 会在成功时被丢弃并带 _warning），或模板+CPU 组合的 Pod（create-pod 拒绝该组合，因为模板部署仅限 GPU 和 v2）；单独使用时 MCP 均可：templateId（仅 v2，imageName 随后可选，且传入的每个字段会替换模板的整个值而非合并）或 computeType: "CPU"。
27. 不属于本通道：编写/部署自己的 Python（→ flash）；下载模型或构建/推送镜像（→ companion-clis）。
28. 概念（Pod vs Serverless、GPU 选择、存储）请阅读 ../runpod-usage/。

适用边界 · 注意事项

• 需要 send/receive 文件传输、SSH 密钥管理、doctor 设置或模型缓存时，改用 runpodctl。
• 需要多 GPU 优先级列表的 Pod 创建，或模板+CPU 组合的 Pod 时，改用 runpodctl。
• CPU Serverless 端点无法通过 MCP 创建（v2 没有 CPU 端点概念，create-endpoint 要求 gpuPoolIds），需使用 runpodctl serverless create --compute-type CPU。