MCP 集成

MCP 给 Anyy 接入外部工具和资源。先确定运行位置，再保存连接，随后按需认证并确认实际工具调用。配置写入成功不等于远端操作已经成功；添加默认保存启用的 lazy 定义，不强制 Probe 或工具选择，--disable 可先停用。

先选运行位置

本机命令

支持 stdio，程序运行在 Anyy 主机，不是浏览器或 CLI 客户端的另一台机器。必须先准备可执行程序及依赖。下面示例需要该主机已有 Node.js/npm：

anyy mcp add context --transport stdio --command npx \
  --exposure codemode --args -y @upstash/context7-mcp

--args 或 -- 后都是 Server 参数，Anyy 参数放在前面。--cwd DIR 仅用于 stdio；可重复 --env KEY=VALUE。服务只继承 PATH、HOME、USER、LANG、LC_ALL、TERM、TMPDIR 等有限环境，需要的其他值应显式配置。Anyy 不打包该服务的运行时。

HTTP Endpoint

anyy mcp add remote-docs --url https://mcp.example.com
anyy mcp add provider-docs --url https://mcp.example.com --auth '{"provider":"provider-id"}'
anyy mcp add header-docs --url https://mcp.example.com --header Authorization=secret:mcp/header-docs/token

http 是 Streamable HTTP，URL 应为 HTTPS，loopback 可用 HTTP。独立 sse transport 会被拒绝，HTTP 内部事件流仍受支持。连接 HTTP 不需要本地 Node.js。

保存在哪里，怎样重新加载

Profile 定义在 config.yaml 的 mcp.client.servers。项目文件位于该 Profile canonical Workspace 的 .anyy/mcp.json，当前即 <ProfileHome>/workspace/.anyy/mcp.json；切换对话或 Session 工作目录不另选项目文件。

项目文件使用 mcpServers：

{
  "mcpServers": {
    "context": {"enabled": false, "exposure": "deferred"},
    "project-docs": {"url": "https://mcp.example.com", "exposure": "codemode"}
  }
}

含 command、url 或 type 的完整项目定义替换同名 Profile 定义，不能设置 Provider auth 引用。不含这三项则是部分覆盖，必须已有同名 Profile 服务，只能改 enabled、exposure、toolExposure；有序覆盖整体替换，不合并，其他字段继承 Profile。

anyy mcp show context
anyy mcp add project-docs --local --url https://mcp.example.com
anyy mcp remove project-docs --local

--local／-l 只写项目文件：添加整体替换同名项目项，无需 --force；删除不存在项报错，删除仅项目项并保留 Profile 定义和授权。启动或空闲 session.reload 后才采用这些编辑；删除覆盖后也在重新读取时恢复 Profile 定义。格式错误会进入诊断，不静默换一个来源。

anyy mcp reload SERVER_ID 只按当前已加载值重新连接，不重读文件。没有 MCP 文件监听；手改 Profile／项目文件后需重启或空闲会话 session.reload RPC。详情见配置生效。

变量、Secret 和工作路径

环境值、Header 值、OAuth clientSecret 支持表达式：$VAR／${VAR} 取 Anyy 进程环境，$$ 和 $! 分别得到字面 $、!；以 ! 起始的值在 Anyy 进程目录执行 Shell，取去首尾空白的结果，限 10 秒和 1 MiB 输出。只处理一次，展开出的文字不再次求值。URL 和 OAuth 其他字段不执行表达式。

普通 CLI／页面保存不根据字段名字猜 Secret。Profile 定义中精确 env:、secret:、file: 前缀先走凭据解析，结果即最终值；完整项目定义将这些前缀作为普通文字，部分覆盖继续继承 Profile 解释。敏感值应明确引用已管理 Secret，不能放进 URL。

命令和参数路径展开开头 ~，cwd 还支持相对用户目录或 Workspace；路径不执行 $／!。cwd 不裁剪空白。stdio 工作目录、对外 Workspace root、!command 的进程目录彼此不同。

连接和工作目录规则

初始化结果必须包含字符串 protocolVersion、对象 capabilities，以及具有字符串 name／version 的 serverInfo；可选 instructions 必须是字符串。无效初始化会关闭连接，不标记就绪；缺失、空字符串和未裁剪 instructions 保持区别，摘要消费时才裁剪。

Server 请求 roots/list 时得到常驻 Workspace canonical 目录这一个 file root，manager 创建后固定，不随会话切换。stdio 默认工作在该目录，配置 cwd 可改变进程目录，不改变声明的 root。它们都不构成文件权限沙箱，本机进程仍用 Anyy 用户的 OS 权限。

完成认证

没有 Authorization Header 或 Provider 引用的 HTTP 服务支持按需 OAuth；匿名服务不强制登录，token 未加载本身也不构成重新认证要求。Provider auth 是 JSON 对象，OAuth 选项是另一对象，例如 --oauth '{"clientId":"registered-client"}'。旧 oauth／header／none 字符串选择器不接受。

先保存 Server，再开始：

anyy mcp login remote-docs --timeout 300

CLI 先查连接，已经 ready 就返回 Already signed in；普通连接错误不会转成登录。显式登录可以为已保存的停用 Server 认证，但不会启用工具。默认 300 秒只限授权，不包含前置检查和登录后重连。

在浏览器授权；不能回调 Anyy 主机时，粘贴完整重定向 URL 到本次输入。非交互 CLI 只等浏览器回调，不读粘贴。Dashboard 已保存 Server 的登录、TUI setup 的 Tools & MCP 提供同一入口；TUI Ctrl+Y 复制链接、Esc 取消，Dashboard 离开或取消结束待完成登录。完成后临时链接和输入会清除。

远端要求交互授权或更多 Scope 时，失败调用报告需登录，应显式登录，不会自动重放该工具调用。取消结束本次登录，不在后台继续。服务拒绝保存的 client credentials 时可清理被拒状态并恢复一次，可能要求重新登录；缺少 code-exchange verifier 会终止尝试。

另一个进程为同 Profile／Server 保存凭据后，等待认证的连接在模型轮次开始时检查。已准备请求保留原声明，新目录在后续请求准备时出现。不轮询凭据；此路径不借凭据变更重新启动普通失败／关闭连接，也不代替手改配置重载。

退出登录

anyy mcp logout remote-docs

必须给精确 Server ID。退出删除当前本地凭据、关闭连接，保留配置及工具／资源／instructions 缓存；没有条目也是成功。它不撤销远端 token，识别到旧 fallback 时可能需要再退出一次。优先使用常驻 Profile；超时或错误不授权绕过它离线改文件。

HTTP 流、token 与重试

初始化后默认另开 GET 流接收 Server 请求与通知。Provider 认证在每次真正 HTTP dispatch（包括 GET）获取当前 token，不另外保存 MCP Provider token 副本。已配置 Header 保留，不为 loopback 自动添加 Origin；显式 Origin 不被覆盖，远端仍可自行校验。

有 cursor 时，事件流中断可带 last event ID 发 GET 恢复，不重发工具调用。没有 cursor 且流在回答前结束，该请求失败。关闭连接结束恢复。同 Profile／Server 多进程协调 token 刷新，刷新前重读保存值，但不保证任意崩溃／lease 丢失都能恢复。

connect_timeout_ms 已退休；call_timeout_ms 分别限制初始化、发现和工具请求，没有额外 opening 总时限。符合条件的初始 HTTP 失败最多重试两次。普通网络失败不自动重放工具调用；expired-session 恢复另有协议路径，不能据此假定外部写入可安全重试。

工具怎样进入模型

Exposure	路径
codemode	默认，由脚本发现和调用
deferred	模型工具搜索
direct	直接声明
hidden	模型和脚本均不可见

anyy mcp configure context --exposure deferred
anyy mcp set context description '文档检索服务'
anyy mcp set context toolExposure '{"get-*":"deferred","*":"hidden"}'

toolExposure 先匹配精确原始名，否则采用有序对象首个匹配通配符。启用／Exposure 保存到有效定义或既有项目覆盖；Exposure 不重连，enable/disable 只影响该服务。连接错误不撤销已保存设置。

Profile 尚无覆盖时，enable／disable SERVER_ID --project 只将 enabled 写入项目；不用于完整项目定义或已覆盖服务。configure --description／--tool-exposure 与 set/unset 修改原始 Profile 定义，不与 configure --exposure／--enable 混用；修改项目覆盖应编辑其项目项。

MCP 不生成 mcp-* 个人组。Role、个人工具组和父名称限制各有职责。旧全局 mcp.client.enabled、tools.include/exclude/trusted、--include、--exclude、--activate-toolset 及选择提示均已移除，配置会拒绝它们。RPC tool_exposure 使用 JSON 字符串保留顺序，存为单个有序 toolExposure。

摘要不是连接回执

一轮开始时生成有界 mcp_servers，列出已启用且配置 Codemode／deferred 的服务，仍在连接的也可出现；direct-only、hidden-only、disabled 不列。混合路由优先 Codemode 标签。摘要按名称排序，优先配置描述，否则用可用 instructions 首行，截短并统计未展示项，不应包含凭据。

本轮后续工具轮次沿用摘要；描述或配置变化在下一提示词反映。没有服务符合条件时移除该段。

检查目录，再调用

anyy mcp show context
anyy mcp probe context
anyy mcp test context
anyy mcp list
anyy mcp status --json
anyy mcp logs context

Probe 单个 tools 清单给出 name、visible_name、description、exposure、offered。若当前服务确实提供 search 且 Schema 要求 query，调用才可写成：

anyy mcp call docs.search --args '{"query":"Anyy"}'

CLI 用原始 Server 工具名。模型侧名称加 namespace、规范化字符并处理冲突，Codemode 要使用发现返回的 JS 标识符，不手拼。参见 Codemode和工具搜索。

新直接调用按当前 JSON Schema 校验；替换前已准备的调用保留当时声明与已验证参数，执行时再解析当前服务和 offering。替换会关闭旧在途连接，不在新连接重放。模型工具和 CLI 均直接执行远端写入，仍受认证、Profile 所有权、凭据保护和名称范围约束，旧审批／执行策略键不会恢复。

资源、模板与 Prompt

共享工具	参数	程序结果
list_mcp_resources	可选 server、cursor	resources，可能带 server、nextCursor、errors
list_mcp_resource_templates	同上	resourceTemplates 及同类分页字段
read_mcp_resource	必需 server、uri	server、uri、contents

给 server 读取一页，再传 nextCursor；cursor 必须配 server。不指定服务则汇总符合条件服务的全部页，保留成功项并在 errors 指出失败服务；指定服务失败则拒绝调用。

已启用、报告资源能力且基础 Exposure 非 hidden 的服务参与，共享暴露从 direct、codemode、deferred 依次选最宽。能力已知后出现，撤回则隐藏，资源清单在调用时读取而非启动抓取。MCP App UI 资源被过滤。

read 保留完整程序 JSON，模型侧按文本、图片、保存文件呈现，长文本遵守 20 KiB 首尾投影。交付失败不重复已经成功的资源读取。旧逐 Server resource/prompt 工具与 tools.resources／tools.prompts 配置均拒绝，值为 false/null 也不接受。状态保留 advertised/capabilities，不再有旧 enabled/posture/count。Prompt 的 List/Get 仍是协议 API，不生成 Agent 工具。

把 Anyy 接到另一个 MCP 客户端

anyy mcp serve 用 stdio 提供 conversations_list、conversation_get、messages_read、events_poll、events_wait、messages_send，操作走现有 Gateway RPC。

mcp.server.scopes 仅允许 conversations、messaging；不写默认两者都有，空数组不暴露工具。旧 approvals、未实现占位 scope 和 expose_approvals/expose_tools 均拒绝。

取得某一次输入的结果

messages_send 只收 session_id 与 text：

{"session_id":"ses_example","text":"整理本周任务"}

先 session.submit，再以原 submission_id 等待 execution.await。结果 JSON text 包含 submission（原接纳回执）、execution（本输入实际调用状态）、messages（按记录引用读出的有序结果）、timed_out。后来的提示词不会替换这一份结果，messages_read 只是历史查询，不用来兜底拼答案。

成功完成或实际 clarification suspension 的 MCP isError=false；suspended 保留澄清句柄并表示需要输入，不是最终回答。失败、中断、清空、超时或未结束状态为 true；idle 仅 outcome=succeeded 才成功。

直接 RPC 客户端要保存两个 ID：

{"execution_id":"exec_example","submission_id":"sub_example","timeout_ms":30000}

等待跟随原预留／选中运行及其恢复链，包括选中前准备失败。被清空的未选输入返回 interrupted/input_cleared 且无消息。等待不激活队列。超时 messages 为空；超时或取消观察不取消已接纳工作，单独 execution_id 也不能标识某次输入结果。重发前先检查状态。

结果与停用

MCP structuredContent 保留接受的 JSON，包括 null、false、数字、字符串和数组。查看模型文本时要区分：content 有块时，模型使用这些块的转换结果，不再另外追加 structuredContent；content 数组为空、但 structuredContent 存在时，会将该 JSON 格式化为模型文本块。这个补充文本同样先保护凭据，再按 20 KiB 规则处理输出。输出 Schema 声明程序返回，不另加本地远端结果验证门槛。模型内容保留文本／图片顺序；音频和未知块用文字占位，嵌入资源变文本、图片或保存的二进制。超过 20 KiB 文本保留全输出并投影首尾。

远端 isError 保持失败，transport／JSON-RPC exception 拒绝调用。图片与保存文件走既有 Session Artifact 交付，不因交付失败再调服务；文本保存前保护。所有块先开始保存再等转换，因此一个无效块可使转换失败，而已开始保存仍完成。

anyy mcp disable context
anyy mcp remove context

停用保留配置。从 Profile 配置中删除 MCP 服务器定义，会移除该定义及其 Anyy 管理凭据，项目 remove --local 保留授权。对 Profile 中 MCP 服务器定义执行操作时，--force 用于脚本确认替换／删除，不绕过所有权。外部服务决定实际认证、计费、传输要求；本机服务先查命令／环境，HTTP 先查认证／连接，再查 Exposure 和 offering。页面流程见 Dashboard MCP。