MCP 配置参考

本页是 Anyy MCP client 和 MCP server bridge 配置的紧凑参考。Setup workflow 和安全指引见 MCP 集成。常规配置建议使用 anyy mcp 命令，而不是直接手写 YAML。

MCP client 默认不启用。即使配置了 server，也只有在选中对应 mcp-<server> 工具集时， 该 server 的工具才会暴露给模型。

根结构

mcp:
  client:
    enabled: false
    session_idle_ttl_ms: 300000
    servers:
      docs:
        enabled: true
        display_name: Docs
        transport: stdio
        command: npx
        args: ["-y", "@example/mcp-server"]
        env:
          EXAMPLE_TOKEN: secret:mcp/docs/token
        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
        sampling:
          enabled: false

  server:
    enabled: false
    transport: stdio

未知字段会导致配置校验失败。

CLI 命令

常用 setup 和检查命令：

anyy mcp add SERVER_ID --command CMD --enable --include tool_a,tool_b
anyy mcp configure SERVER_ID --include tool_a,tool_b --enable
anyy mcp list
anyy mcp show SERVER_ID
anyy mcp probe SERVER_ID
anyy mcp test SERVER_ID
anyy mcp reload [SERVER_ID]
anyy mcp logs SERVER_ID

--activate-toolset 会把对应的 mcp-<server> 工具集加入 toolsets.default。如果 server 未启用或 include 列表为空，Anyy 会拒绝激活。

Client 字段

字段	类型	默认值	含义
mcp.client.enabled	bool	false	启用 MCP client runtime。
mcp.client.session_idle_ttl_ms	int	300000	client session 可被关闭前的空闲 TTL。
mcp.client.servers	map	empty	以 server id 为 key 的 server 定义。

Server id 可包含字母、数字、_、- 和 .。可见工具名和工具集名会使用规范化后的 id。

服务器定义

字段	类型	默认值	含义
enabled	bool	false	禁用的 server 保留在配置中，但不会连接或暴露。
display_name	string	server id	状态界面的友好名称。
transport	string	inferred	stdio 或 http。
auth	string	none	HTTP 认证姿态：none、header 或 oauth。
command	string	none	stdio server 的可执行命令。
cwd	string	none	stdio 工作目录；设置时必须是绝对路径。
args	list	empty	stdio 命令参数。
env	map	empty	stdio server 的环境变量。敏感值必须使用引用。
url	string	none	http server URL。
headers	map	empty	HTTP headers。敏感值必须使用引用。
startup	string	lazy	lazy、gateway 或 session。
connect_timeout_ms	int	5000	初始连接超时。
call_timeout_ms	int	30000	工具调用超时。
tools	map	见下方	工具过滤和策略。
sampling	map	disabled	server 发起模型请求时的限制。

传输推断很直接：有 command 的 server 推断为 stdio；有 url 的 server 推断为 http。不符合预期时请显式设置 transport。

传输方式

stdio server 会启动本地进程，并使用官方 MCP stdio transport：stdin/stdout 上每行 一个 UTF-8 JSON-RPC message。它需要 command，可设置 args、cwd 和 env，不能设置 url。auth 必须为空或 none。

http server 使用官方 Streamable HTTP transport。Anyy 会在初始化时声明最新支持的 MCP protocol version，保存协商出的版本，并在 HTTP 请求中发送 MCP-Protocol-Version。 http server 需要有效 url，可设置 headers，不能设置 command 或 args。它的 auth 可以为空、none、header 或 oauth。

cwd 存在时必须是绝对路径。超时必须为 0 或正数；0 表示应用默认值。

环境变量与密钥

MCP env 和 headers 值可以使用 secret:、env: 或 file: 引用。不要使用旧的 secret://、env:// 或 file:// 形式。

MCP 的密钥字段拒绝 literal:。字段名或字段值看起来敏感时，例如 Authorization、 *_TOKEN、api_key、password 或 Bearer ...，必须使用 secret 引用。

推荐写法：

headers:
  Authorization: secret:mcp/docs/auth_header
env:
  GITHUB_TOKEN: env:GITHUB_TOKEN

会被拒绝的写法：

headers:
  Authorization: "Bearer raw-token"
env:
  API_KEY: literal:raw-token

工具策略

MCP server 默认按不受信任处理。如果 tools.include 为空，server 原生远端工具不会暴露。 只有当资源或 prompt utility 被显式启用且 server 声明支持时，对应 utility 工具才会暴露。

字段	默认值	含义
include	empty	允许的 MCP 原始工具名。配置校验拒绝 *。
exclude	empty	在原本会被允许的工具中排除这些名称。
resources	false	server 支持 resources 时暴露 list_resources 和 read_resource。
prompts	false	server 支持 prompts 时暴露 list_prompts 和 get_prompt。
default_risk	empty -> read	暴露出的 server 工具使用的风险等级。anyy mcp add 会写入 runtime-high。
approval_policy	empty -> none	暴露出的 server 工具使用的审批策略。
execution_policy	empty -> direct	暴露出的 server 工具使用的执行策略。anyy mcp add 会写入 confirm。
output_visible_chars	6000	模型可见输出预算。
output_stored_chars	30000	存储输出预算。

允许的工具会得到以下可见名称：

mcp_<server>_<tool>

Server id 和工具名会小写并规范化。例如 GitHub.Prod 加 issues.search 会得到工具集 mcp-github_prod 和工具 mcp_github_prod_issues_search。

include 和 exclude 使用 MCP server 原始工具名，不使用规范化后的可见名称。

风险与执行值

default_risk 支持：

read、runtime-low、runtime-high、config-low、config-high、 credential-high、dangerous、force-required。

approval_policy 支持 none、hook、always。

execution_policy 支持 direct、audit、confirm、change_plan、 force_change_plan。

这些策略不会替代全局工具治理。它们设置的是来自该 MCP server 的工具描述符。

Sampling

除非 sampling.enabled 为 true，否则 sampling 关闭。

字段	启用后默认值	含义
model_allowlist	empty	MCP server 可以请求的模型。
max_tokens_cap	4096	最大请求输出 tokens。
timeout_ms	30000	sampling 调用超时。
max_rpm	10	每个 server 的请求速率限制。
tool_loop_limit	1	sampled 调用的工具循环上限。

启用 sampling 时，应用默认值后的每个数值限制都必须为正数。

将 Anyy 暴露为 MCP Server

mcp.server 块用于通过 MCP bridge 暴露 Anyy 本身。默认关闭。

字段	默认值	含义
enabled	false	启用 server bridge。
transport	stdio	当前只支持 stdio。
scopes	empty	可选 scope allowlist。
expose_approvals	false	暴露审批相关 bridge 能力。
expose_tools	false	通过 bridge 暴露选定的 Anyy 工具。

允许的 scopes 是 conversations、messaging、approvals、tasks、 reminders、memory、skills、tools。

运行注意事项

修改 config.yaml 不会自动更新已经连接的 MCP session。编辑后使用 anyy mcp reload [SERVER_ID]，或重启 resident gateway。

使用 anyy mcp probe SERVER_ID 或 anyy mcp test SERVER_ID 检查 server 健康状态和发现到的工具。server 启动或连接失败时，使用 anyy mcp logs SERVER_ID 查看日志。