MCP 客户端
每个 aidy 宿主都在 <url>/mcp 提供基于 streamable HTTP 的 MCP,例如 https://console.example.com/mcp。客户端使用用户自己的凭证认证,也就是你的 API 本来就接受的 bearer token,只能看到该用户可用的操作。
客户端能看到什么
Section titled “客户端能看到什么”- 工具:
surfaces包含mcp的目录操作,外加search(跨所有搜索源的联合搜索)。读操作默认包含mcp,写操作默认不包含。 - 注解:根据操作的 effect 生成
readOnlyHint、destructiveHint、idempotentHint。 - 结果:去掉
x-aidy.redact列出的字段。 - 调用:以用户身份发往你的 API,附带
Aidy-Assertion,其中cid是 MCP 请求 id。是否允许由你的授权逻辑决定,与界面请求完全一样。
写操作需要 elicitation
Section titled “写操作需要 elicitation”要把写操作开放给 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 Code
Section titled “Claude Code”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
Section titled “Cursor”在项目的 .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 令牌一样可限定范围、可撤销。
OAuth 发现
Section titled “OAuth 发现”支持 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 一起转发给它,见部署。