MCP 参考

gpuctl-mcp 是把 GPUPlane 控制面暴露给 AI Agent 的 MCP 适配器——一个独立进程， 不依赖 server/agent 包，经 REST 调用 server（纯适配器；它坏了不影响控制面本体）。

两种传输

形态	命令	适用
streamable HTTP	gpuctl-mcp serve --port 18602	远程/多客户端，无状态核心，/mcp 端点 + Bearer 鉴权
stdio	gpuctl-mcp stdio	本机单客户端（Claude Code 插件形态），无需传输层鉴权

环境变量：GPUCTL_SERVER_URL（默认 http://127.0.0.1:8600）、GPUCTL_MCP_TOKEN。

鉴权与读写域

adapter 启动时调用 GET /auth/whoami 核实 token 域：

• read token：注册观测 + 语义工具（16 个），控制工具不注册，并打印提示；
• write token：全部 21 个工具可用；
• 核身失败（网络问题）：默认按 write 注册，让工具调用时由 server 返回真实错误。

HTTP 形态要求客户端持与 adapter 转发上游相同的 Bearer token——本地进程不能仅靠 够得着 adapter 端口就继承它的权限。

长时任务约定（重要）

一次训练可能跑几小时，绝不伪装成同步工具调用。submit_job / evaluate_checkpoint / cancel_job / retry_job 立即返回 task handle：

{
  "taskId": "job_…", "job_id": "job_…", "state": "working",
  "pollIntervalMs": 15000, "ttlMs": 86400000,
  "next_actions": [{"tool": "get_job", "args": {"job_id": "job_…"}, "reason": "…"}]
}

随后用 get_job / get_run_summary 按建议间隔轮询（GPU 作业 5–30s）， 或由 webhook / gpuctl event-hook 在事件发生时唤醒 Agent。

next_actions 约定

语义与控制工具的返回都带 next_actions 字段——推荐的下一个工具调用及理由。 Agent 跟着走即是正确流程，无需自己规划轮询。

工具总览（21 个）

分组	数量	工具
观测（read）	11	list_nodes · get_node_status · list_jobs · get_job · get_run_summary · query_metrics · tail_logs · list_events · list_checkpoints · list_evaluations · list_metric_definitions
语义（read）	5	diagnose_run · compare_runs · compare_checkpoints · get_best_checkpoint · explain_failure
控制（write）	5	submit_job · evaluate_checkpoint · cancel_job · retry_job · set_primary_metric

典型循环：submit_job → get_run_summary / list_events / diagnose_run → compare_runs → evaluate_checkpoint → get_best_checkpoint。 详见 实验循环与 Agent 接入。