MCP 集成

MCP 让 Anyy 可以使用外部 MCP server 提供的工具，也可以通过 MCP server bridge 暴露选定的 Anyy 能力。

本页是 MCP setup 和日常操作的主入口。紧凑字段表见 MCP 配置参考。工具集选择规则见工具集。

MCP 提供什么

外部工具：连接 stdio 或 HTTP MCP server。
工具暴露控制：只允许选定的 server 工具。
工具集路由：每个 server 贡献一个 mcp-<server> 工具集。
Resources 和 prompts：可选暴露 MCP resource/prompt utility 工具。
Server bridge：运行 anyy mcp serve，让 MCP client 连接 Anyy。

MCP 默认不启用。Server 出现在 config.yaml 里，并不代表它已经对模型可见。

快速开始

先添加一个带窄 include 列表的 server：

anyy mcp add docs \
  --command npx \
  --enable \
  --include search \
  --activate-toolset \
  --args -y @example/mcp-server

然后检查保存内容和运行时连通性：

anyy mcp list
anyy mcp show docs
anyy mcp test docs

如果 Anyy gateway 正在运行，配置变更会通过 RPC 更新 runtime。否则 CLI 会写入 config.yaml；在 resident session 中使用该 server 前，需要启动或重启 gateway。

暴露模型

MCP server 的工具进入模型前必须通过三道门：

mcp.client.enabled 必须为 true。
Server 必须启用，并且至少暴露一个允许的工具或 utility。
对应 mcp-<server> 工具集必须被本轮选择，或写入 toolsets.default。

--activate-toolset 会把对应工具集加入 toolsets.default，但只有当 server 已启用且有 include 列表时 Anyy 才允许激活。

可见 MCP 工具名会被规范化：

mcp_<server>_<tool>

例如 server GitHub.Prod 和工具 issues.search 会得到工具集 mcp-github_prod 和工具 mcp_github_prod_issues_search。include 和 exclude 使用 MCP 原始工具名，不使用规范化后名称。

配置形态

CLI 会把 MCP 配置写在 mcp.client.servers 下：

mcp:
  client:
    enabled: true
    servers:
      docs:
        enabled: true
        transport: stdio
        command: npx
        args: ["-y", "@example/mcp-server"]
        startup: lazy
        connect_timeout_ms: 5000
        call_timeout_ms: 30000
        tools:
          include: [search]
          exclude: []
          resources: false
          prompts: false
          default_risk: runtime-high
          approval_policy: none
          execution_policy: confirm
          output_visible_chars: 6000
          output_stored_chars: 30000

toolsets:
  default:
    - terminal
    - mcp-docs

当 policy 字段省略时，runtime 默认是 default_risk: read、approval_policy: none 和 execution_policy: direct。CLI 为新增外部 server 写入更保守的默认值：runtime-high 加 confirm。

传输方式

stdio server 会启动本地进程：

anyy mcp add project_fs \
  --preset filesystem \
  --enable \
  --include read_file,list_directory \
  --activate-toolset \
  -- /absolute/project/path

http server 使用远程 URL：

anyy mcp add docs \
  --transport http \
  --url https://mcp.example.com/mcp \
  --header Authorization=secret:mcp/docs/auth_header \
  --enable \
  --include search

Plain HTTP URL 只允许本地 endpoint。敏感 env 和 headers 值必须使用 secret:、env: 或 file: 引用；MCP 密钥字段拒绝 literal:。

OAuth

Hosted MCP server 如果使用 OAuth，请设置 --auth oauth 并运行 login：

anyy mcp add linear \
  --transport http \
  --url https://mcp.example.com/mcp \
  --auth oauth \
  --enable \
  --include list_issues,create_issue

anyy mcp login linear

OAuth token 存在 profile 的 MCP token store 中。Token 过期或 server 要求重新授权时，再运行 anyy mcp login SERVER_ID。

工具过滤

外部系统优先使用 allowlist：

anyy mcp configure github --include list_issues,create_issue --enable

如果手写 YAML，使用 MCP 原始工具名：

tools:
  include: [list_issues, create_issue]
  prompts: false
  resources: false

include 为空表示不暴露 server-native 工具。Resource 和 prompt utility 只有在显式启用且 server session 支持时才会暴露。

Resources、Prompts 与 Sampling

Resources 和 prompts 默认禁用：

tools:
  resources: true
  prompts: true

启用且 server 支持时，Anyy 会注册 mcp_docs_list_resources、 mcp_docs_read_resource、mcp_docs_list_prompts、mcp_docs_get_prompt 等 utility 工具。

MCP sampling 默认禁用，除非 sampling.enabled 为 true。启用时，需要设置正数的 token、 timeout、RPM 和 tool-loop limit。Server 可以请求模型调用时，建议设置 model_allowlist。

运行时操作

大范围暴露工具前，先用 MCP CLI 检查：

anyy mcp probe docs
anyy mcp test docs
anyy mcp reload docs
anyy mcp logs docs
anyy mcp status --json

probe 和 test 检查连通性与发现的工具。reload 在配置变化后重连。logs 会显示 MCP 诊断，并对已配置的 secret 值做 redaction。

将 Anyy 作为 MCP Server

当 MCP client 需要连接 Anyy 时，使用 bridge：

anyy mcp serve

Bridge 配置在 mcp.server 下，默认禁用：

mcp:
  server:
    enabled: false
    transport: stdio
    scopes: [conversations, tasks]
    expose_approvals: false
    expose_tools: false

Anyy MCP server bridge 目前只支持 stdio transport。支持的 scopes 见配置参考。

安全注意事项

从一个 server 和小 include 列表开始。
在理解工具参数和效果之前，不要暴露破坏性工具。
文件系统 server 应限制在最小有用目录。
密钥使用引用，不要把裸值写进 YAML。
有意使用 toolsets.default；MCP server 可以已配置但不默认可见。

故障排查

Server 已配置但没有工具出现：确认 mcp.client.enabled、server enabled、非空 tools.include，以及活跃的 mcp-<server> 工具集。
Discovery 需要交互式终端：传入 --include a,b --enable，或用 --no-discover 保存禁用配置。
OAuth server 能连接但调用失败：运行 anyy mcp login SERVER_ID 并确认 token 已保存。
改动未生效：运行 anyy mcp reload SERVER_ID 或重启 resident gateway。

MCP 提供什么​

快速开始​

暴露模型​

配置形态​

传输方式​

OAuth​

工具过滤​

Resources、Prompts 与 Sampling​

运行时操作​

将 Anyy 作为 MCP Server​

安全注意事项​

故障排查​