跳转到内容

MCP 客户端

每个 aidy 宿主都在 <url>/mcp 提供基于 streamable HTTP 的 MCP,例如 https://console.example.com/mcp。客户端使用用户自己的凭证认证,也就是你的 API 本来就接受的 bearer token,只能看到该用户可用的操作。

  • 工具:surfaces 包含 mcp 的目录操作,外加 search(跨所有搜索源的联合搜索)。读操作默认包含 mcp,写操作默认不包含。
  • 注解:根据操作的 effect 生成 readOnlyHint、destructiveHint、idempotentHint。
  • 结果:去掉 x-aidy.redact 列出的字段。
  • 调用:以用户身份发往你的 API,附带 Aidy-Assertion,其中 cid 是 MCP 请求 id。是否允许由你的授权逻辑决定,与界面请求完全一样。

要把写操作开放给 MCP,需要显式列出该 surface:

"x-aidy": {
"name": "stop_vm",
"surfaces": ["agent", "mcp", "cli"],
"confirmation": { "title": "Stop server {resource_name}?", "lookup": { "path": "/api/vm/{vm_id}", "labelPath": "name" } }
}

需要审批的操作(approval: always,写操作的默认值)执行前,aidy 先解析参数、执行确认查询,再通过 MCP elicitation 向用户展示确认文本(“Stop server gpu-train-01?”)。不支持 elicitation 的客户端仍能看到该工具,但调用会被拒绝并附带说明,不会执行任何操作。这项检查写在 aidy 的代码里,任何提示词都无法绕过。

终端窗口
claude mcp add --transport http console https://console.example.com/mcp \
--header "Authorization: Bearer $CONSOLE_TOKEN"

console 是该服务器在 Claude Code 中的名字。运行 claude mcp list 确认已连接,然后就可以向 Claude 询问你的服务器(“cn-beijing-a 里有哪些 VM 在运行?”)。

在项目的 .cursor/mcp.json 中添加服务器;如需对所有项目生效,写到 ~/.cursor/mcp.json:

{
"mcpServers": {
"console": {
"url": "https://console.example.com/mcp",
"headers": { "Authorization": "Bearer ${env:CONSOLE_TOKEN}" }
}
}
}

Cursor 会在 url 和 headers 中用启动时的环境变量替换 ${env:NAME},令牌因此不必写进文件。

任何支持 MCP streamable HTTP 的客户端都可以接入,需要配置:

配置项 值
传输方式 Streamable HTTP
URL https://console.example.com/mcp
请求头 Authorization: Bearer <token>

只支持 stdio 的客户端可以通过 mcp-remote 之类的桥接工具接入:

{
"mcpServers": {
"console": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://console.example.com/mcp", "--header", "Authorization: Bearer ${CONSOLE_TOKEN}"]
}
}
}

在脚本和终端中,aidy CLI 就是连接同一端点的 MCP 客户端。

令牌就是你的 API 在 Authorization 中接受的任何凭证:个人访问令牌、API key 或 OAuth access token。aidy 把它转发给身份操作以确认用户,并在每次调用时转发。它只在请求期间保存在内存中,从不落盘。令牌过期后调用会失败,直到客户端提供新的令牌。

为用户提供一个创建 MCP 令牌的页面,最好与其他 API 令牌一样可限定范围、可撤销。

支持 MCP 授权的客户端可以通过你的 OAuth 服务器让用户登录,无需手动粘贴令牌。在 aidy 配置中指定授权服务器:

createAidy({
// ...
mcp: { authorizationServers: ['https://auth.example.com'] },
});

aidy 随后在 /.well-known/oauth-protected-resource/mcp 提供受保护资源元数据:

{
"resource": "https://console.example.com/mcp",
"authorization_servers": ["https://auth.example.com"],
"bearer_methods_supported": ["header"]
}

未认证的 /mcp 请求返回 401,并带有 WWW-Authenticate: Bearer resource_metadata="https://console.example.com/.well-known/oauth-protected-resource/mcp",客户端据此找到授权服务器、完成 OAuth 流程,再带着 access token 重试。令牌由你的授权服务器签发、由你的 API 校验,aidy 只负责转发。

aidy 位于反向代理之后时,要把 /.well-known/oauth-protected-resource/mcp 和 /mcp 一起转发给它,见部署。