# 云蝠远程 MCP 连接与业务接续

首页「连接 AI 助手」支持 Codex、Claude Code 与 WorkBuddy。首页已经填写文字需求时，打开接入面板，在「开始使用」复制当前任务；原文和限制随任务带入，附件需要在目标助手中另行选择。安装、企业连接和业务执行分别核对，复制内容不会增加授权。

## 选择接入方式

- Codex / Claude Code：可使用原生技能插件和 CLI，也可配置远程 MCP。插件包含根目录 `plugin.json`、技能目录及 Codex 兼容清单；本地技能与远程工具是不同入口。
- WorkBuddy：使用自定义 MCP 连接器。不要运行 Codex 安装命令。
- 其他支持 Streamable HTTP 的智能体：使用下列通用参数。参数说明不是通用客户端配置文件，也不代表已验证某个客户端的兼容性。按该客户端要求配置认证和工具授权。

## 连接与只读核验

1. 企业管理员在「开放平台 → 访问密钥」选择仍有效的当前站点密钥，只授予本任务需要的操作。安装插件不自动创建密钥。
2. 服务地址是当前云蝠站点的 `/v1/mcp`，例如 `https://你的企业站点/v1/mcp`。企业部署使用 HTTPS；仅本机预览允许 loopback HTTP。使用 Bearer 认证，凭据只在客户端安全配置，不发到聊天、源码或公开文件。
3. Codex：合入自己的 `config.toml`，使用 `bearer_token_env_var = "YUNFU_API_KEY"`。环境变量必须存在于实际启动客户端的环境。Claude Code：合入项目 `.mcp.json`，`type: "http"`，并在客户端批准该项目 MCP。两者均保留其他服务器配置。
4. WorkBuddy：在自定义连接器中配置 `type: "streamableHttp"`、URL 和 Authorization；`Bearer ${YUNFU_API_KEY}` 仅是占位符，不会在所有客户端中自动展开。
5. 先完成协议 `initialize` 和 `tools/list`，再调用 `yunfu_connection` 核对企业、账户、有效期和权限。调用 `yunfu_operations` 查明当前授权合同，只读核对一个真实资源后再接续业务。握手、复制配置或请求受理均不等于业务完成。

端点使用无会话 Streamable HTTP JSON 响应，每个请求重新鉴权；不支持旧 SSE 双端点、服务器推送或 OAuth 登录。云蝠的平台执行机是相反方向的接入：需要平台调用已登记本地 worker 时才配置 CLI 执行机；“在 Codex 中使用云蝠”不应创建执行机草稿。

## 按权限发现工具

工具列表由当前密钥和账户权限动态产生，不是固定九项；注册工具、当前授权和传输能力分别判断。以下为实现中的工具名：

| 工具 | 用途与边界 |
| --- | --- |
| `yunfu_connection` | 核对当前身份、有效期和已授权操作 |
| `yunfu_guide` | 客服场景和阶段引导；不执行业务或标记完成 |
| `yunfu_channel_setup` | 渠道接入材料、步骤及验收指引；不自动接通 |
| `yunfu_operations` | 分页发现授权操作，读取参数合同、示例、计费和传输限制 |
| `yunfu_operation_read` | 按授权合同读取业务数据；存在可用通用读取操作时提供 |
| `yunfu_operation_execute` | 按合同执行已授权业务动作；存在可用通用写入操作时提供 |
| `yunfu_agents` | 列出智能体，需要 agents.read |
| `yunfu_agent_read` | 读取智能体及 revision，需要 agent-config.read |
| `yunfu_agent_versions` | 读取版本，需要 agent-versions.read |
| `yunfu_agent_save` | 保存完整草稿，需要 agent-config.saveAgent 和 revision |
| `yunfu_agent_check` | 检查草稿，需要 agent-config.validate；会增加 revision |
| `yunfu_agent_save_cases` | 替换完整回归用例列表，需要 agent-config.saveCases，最多20条 |
| `yunfu_text_test` | 按 expectedRevision 运行一次真实文字演练，需要 text-tests.answer，可能计费 |
| `yunfu_mailbox` | 授权邮箱查询，需要 email.read；不触发收信、模型或发送 |
| `yunfu_mail_customer` | 按真实邮件关联查询客户，需要 email-customer.read；关联不等于认证 |
| `yunfu_mail_reply` | 按授权发出回复，需要 email.reply；遵守当前外发范围 |
| `yunfu_mail_draft` | 保存邮件草稿，需要 email.saveDraft；保存不等于发送 |
| `yunfu_mail_send` | 发送已保存草稿，需要 email.sendDraft 及本次发送授权 |

## 让一次任务有效推进

先发现授权和相关资源 → 复用已有配置 → 说明最短计划及验收回执 → 执行当前授权内的一步 → 重读核对 → 给出结果、阻塞和下一步。只问缺少的信息，不把每轮对话重新当成首次上手。

新建、话术优化、发布、工作流、知识、渠道、工单、任务及外呼等普通业务，可在 `yunfu_operations` 实际返回对应合同且授权满足时，通过通用工具执行。不能仅因目录中注册了接口就认为可执行。发布、外发、启动、拨号及收费调用仍需本次授权覆盖。实时媒体协商、语音流及大文件分块使用 SDK/CLI；真机媒体质量仍由设备验证。

写入使用真实资源 ID、当前 revision 和稳定 idempotencyKey。同键同内容复用回执；同键改内容拒绝；结果未知时先查原回执，不换键重试。保存用例先读取、合并并保留已有 ID。文字测试强制草稿演练，需指定版本，启用外部工具的草稿会被拒绝。模型调用成功与业务正确分别报告。

## 故障恢复

- 401：核对密钥、有效期、账号和角色；在客户端安全更新凭据。
- 403：核对签发站点、企业及实际授权，不能通过更换自报身份绕过。
- 409：资源并发变化或结果未知，先查询版本或回执再继续。
- 429：按 Retry-After 等待；协议发现也受配额限制。
- 工具缺失：先检查 tools/list 和 yunfu_operations；不虚构工具、不自动扩大密钥权限，提供对应控制台入口。

参考：[Codex MCP](https://developers.openai.com/codex/mcp)、[OpenAI 插件结构](https://developers.openai.com/plugins/build/plugins)、[Claude Code MCP](https://code.claude.com/docs/en/mcp)、[WorkBuddy 连接器](https://open.workbuddy.cn/docs/connector)。这些配置说明不代表每个客户端均完成本机端到端验收；不自动安装真实客户端、连接账号、运行收费模型或发布生产。
