使用 MCP 服务器

当外部 MCP server 已经提供了你需要的工具面，并且你希望 Anyy 只暴露其中一小部分可审查工具时，用这页作为实用路径。

完整配置模型见 MCP 集成。字段表见 MCP 配置参考。

什么时候使用 MCP

适合使用 MCP 的情况：

有用的外部工具已经以 MCP server 形式存在；
你想通过清晰的 RPC 边界连接本地或 hosted system；
你需要 per-server tool filtering；
你想连接一个内部系统，但不想为此添加 Anyy native tool。

如果 Anyy 内置工具已经能很好解决问题，或者 server 暴露了大量 destructive tools 而你还没有准备好过滤，就不要先用 MCP。

Mental Model

MCP 是 adapter layer：

Anyy 仍然是 assistant 和 resident runtime。
MCP servers 提供外部 tools。
Anyy 会先过滤这些 tools，再让模型使用。
每个 server 映射到一个 mcp-<server> toolset。

好的 MCP setup 不是“连接所有工具”，而是“连接最小可用工具面”。

先添加一个 Server

先从一个低风险 server 和 include list 开始：

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

检查写入内容：

anyy mcp list
anyy mcp show project_fs

--activate-toolset 会把 mcp-project_fs 加入新 sessions 的 toolsets.default。Anyy 会拒绝激活未启用或 include list 为空的 server。

验证 Runtime 可见性

gateway 运行时：

anyy mcp probe project_fs
anyy mcp test project_fs
anyy mcp status

修改 config 后，reload server 或重启 gateway：

anyy mcp reload project_fs

然后在新的或已 reload 的 session 中询问：

Which MCP-backed tools are available right now?

如果 tools 仍然没有出现，检查所有 visibility gates：

Gate	检查
Client enabled	`mcp.client.enabled: true`
Server enabled	`mcp.client.servers.<id>.enabled: true`
Tools allowed	`tools.include` 包含 server-native tool names
Toolset active	`mcp-<server>` 被当前 session 选择，或在 `toolsets.default` 中

立即过滤

优先使用 allowlists：

anyy mcp configure github \
  --include list_issues,create_issue \
  --enable \
  --activate-toolset

YAML 中使用 MCP server 原始 tool names：

mcp:
  client:
    enabled: true
    servers:
      github:
        enabled: true
        tools:
          include: [list_issues, create_issue]
          resources: false
          prompts: false

Anyy 里的 sanitized tool name 可能像 mcp_github_list_issues，但 filter list 使用 server-native names。

使用 Hosted MCP Servers

HTTP servers 使用 URL：

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

如果远端 server 需要 Bearer ... 这类值，把完整 sensitive header value 存进 secret。Sensitive env 和 headers values 必须使用 secret:、env: 或 file: references；secret-bearing MCP fields 会拒绝 literal:。

OAuth servers：

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

anyy mcp login linear

Plain HTTP URL 只允许本地 endpoint。远程 server 使用 HTTPS。

把 Anyy 作为 MCP Server

当其他 MCP client 需要和 Anyy 通信时，运行：

anyy mcp serve

Anyy MCP server bridge 当前使用 stdio transport。只在 mcp.server 中启用 client 需要的 scopes。

常见首个 Pattern

Pattern	从这里开始
Local project assistant	Filesystem server，root 到一个项目目录。
Issue triage	GitHub server，只 include read/list/create issue tools。
Internal API assistant	Hosted MCP server，使用 read-heavy include list。
Documentation server	只有 server 支持且确实需要时，才启用 resource/prompt utilities。

只有当有具体 prompt 需要更多工具时，再扩展 include list。

故障排查

现象	检查
没有 tools 出现	确认 `mcp.client.enabled`、server `enabled`、非空 `tools.include`，以及 active `mcp-<server>` toolset。
Discovery 需要交互式 terminal	传 `--include a,b --enable`，或用 `--no-discover` 保存 disabled config。
OAuth calls 失败	运行 `anyy mcp login SERVER_ID`。
Runtime 没更新	运行 `anyy mcp reload SERVER_ID` 或重启 resident gateway。
出现太多 tools	收窄 `tools.include`，除非需要，否则关闭 `resources` / `prompts`。
远程 HTTP URL 被拒绝	使用 HTTPS；plain HTTP 只保留给本地 endpoint。

什么时候使用 MCP​

Mental Model​

先添加一个 Server​

验证 Runtime 可见性​

立即过滤​

使用 Hosted MCP Servers​

把 Anyy 作为 MCP Server​

常见首个 Pattern​

故障排查​