跳转到正文

通过 MCP 接入

本文目录

在支持 MCP HTTP 传输的 AI 客户端中连接 GPUWorks,让客户端读取节点、部署和指标信息,回答集群问题。完成后可列出 GPUWorks 工具,并读取一次集群概况。

客户端必须能访问控制台地址;你需要一个可登录的平台账号,并由管理员开启 MCP 服务。MCP 默认关闭,只提供只读工具。客户端会把读取的数据交给它自己配置的模型,接入前确认该模型符合你的数据使用要求,详见数据去向。

开启服务

请管理员打开设置 → 安全与访问,在MCP 服务卡片打开开关,确认显示已开启。记下卡片显示的端点;如果客户端与浏览器不在同一台机器,确认这个地址从客户端也能访问。

平台 API 令牌

在API 令牌 → 平台 API 令牌点创建平台令牌,填写名称,权限范围选只读,按需要选择有效期,再点创建。立即保存显示的 gwp_... 令牌,完整值只显示一次。

该页有两种令牌,MCP 使用平台 API 令牌:

推理服务令牌平台 API 令牌
开头gw-gwp_
用来调用已部署模型的 /v1(OpenAI 兼容)平台管理 API(/api/v1/...)与 MCP
身份与权限不代表任何用户以创建者的身份、按其当前角色执行,再叠加令牌范围

接入 MCP

端点是 https://<控制台地址>/api/v1/mcp,使用 Streamable HTTP,请求头带平台 API 令牌。MCP 服务卡片可复制按浏览器地址生成的命令;将占位令牌替换为刚创建的完整值,地址替换为客户端实际可访问的入口。

Claude Code:

claude mcp add --transport http gpuworks https://<控制台地址>/api/v1/mcp \
  --header "Authorization: Bearer gwp_..."

其他支持 HTTP 传输的客户端,填写相同的端点与请求头。下面只示意需要传递的信息;配置文件位置和字段格式应按该客户端要求调整,不能保证直接粘贴适用于所有客户端:

{
  "mcpServers": {
    "gpuworks": {
      "type": "http",
      "url": "https://<控制台地址>/api/v1/mcp",
      "headers": { "Authorization": "Bearer gwp_..." }
    }
  }
}

连接后,在客户端确认能列出 GPUWorks 工具,并发起一次「读取集群概况」请求,确认调用了 cluster_overview 且返回本集群的数据。以工具调用结果为准,不只看模型生成的文字;未列出工具或调用失败时,按排查处理后重试。

提供哪些工具

与控制台里的 AI 助手 是同一套只读工具:cluster_overview(集群概况)、search_api / call_api(找接口、读接口,支持 jq)、search_metrics(指标目录)、get_gpu_topology(卡间互联)、compare_with_healthy_replica(失败实例与健康副本的差异)。读到的数据与令牌所属用户在控制台上看到的一样,交出之前同样做凭证脱敏和截断。MCP 不提供任何写操作,与令牌范围无关。

get_node_connection_diagnostics 还可按节点 UUID 读取连接诊断,沿用原接口的管理员权限。该操作使用固定 POST 路径,只读平台令牌会被原有方法限制拒绝;其他 GET 工具仍可正常使用。工具不接受自定义地址或 SSH 参数,不执行恢复或配置修改。

同一用户同时最多 4 个工具调用在执行,再多的调用会收到「请稍后」的结果。每次工具调用都在 server 日志里记一条 mcp tool call(用户、令牌前缀、工具、耗时)。

管理令牌

只读是默认范围,允许读取管理 API 和调用 MCP;只有其他程序确实要修改平台时才需要读写范围。MCP 工具本身始终只读,换成读写令牌不会增加写操作。

令牌有效期可选 30、90、365 天或永不过期,服务端只保存哈希。列表显示最近一次使用时间(每分钟更新一次)。客户端停用或令牌泄露时,登录控制台在该令牌行点吊销,立即生效;需要更换时,创建新令牌、更新客户端并验证后吊销旧令牌。

任何平台 API 令牌都不能用来查看、创建或吊销令牌,这些操作必须在登录状态下完成。创建者的角色改变或账号被删除,令牌权限随之改变或失效。

不用 MCP 时,令牌也可以直接调用管理 API:

curl https://<控制台地址>/api/v1/nodes -H "Authorization: Bearer gwp_..."

数据去向

MCP 客户端会把读到的平台数据交给它自己配置的模型。数据发往哪里由客户端决定,和平台“设置 → 集成 → AI 服务”里配置的模型无关。在意数据出境时,请让客户端使用你认可的模型,或保持 MCP 关闭。

排查

现象原因
403 MCP_DISABLEDMCP 服务没开,请管理员在设置 → 安全与访问的 MCP 服务卡片打开
401令牌错误、已吊销、已过期,或所属账号已删除
403 PLATFORM_TOKEN_READ_ONLY用只读令牌做了写操作(直接调管理 API 时);MCP 本身不会出现

这篇文档有帮助吗?