跳到主要内容
SynaRoute
返回文档索引

MCP 接入手册

如何在 Codex CLI、Claude Code 等支持 MCP 的客户端里，调用 SynaRoute 的多模型大脑聚合。

这是什么

SynaRoute 内置一个 MCP（Model Context Protocol）服务器。开启后，你可以在支持 MCP 的 AI 编程客户端里直接调用多模型聚合：

  • 多个模型并行分析你当前项目的代码；
  • 由决策者综合所有意见，输出一份清晰的建议或修改计划；
  • 建议返回给你的客户端，由客户端自己执行文件修改，用它原生的编辑工具和审批流程。

SynaRoute 只出主意，不碰你的文件。 所有实际改动都经过你在客户端里的确认。

前置条件

  1. SynaRoute 已安装并运行；
  2. 至少在一个分类（Claude CLI / Claude 桌面端 / Codex）下配好可用的 Key，并在「大脑聚合」页启用聚合、配好参与者和决策者；
  3. 客户端已安装（Codex CLI 需支持 HTTP MCP 的版本，或 Claude Code）。

开启 MCP 服务器

  1. 打开 SynaRoute → 设置 → MCP 服务器；
  2. 打开「启用 MCP 服务器」开关；
  3. 端口默认 9527。如果该端口被系统进程占用（部分 Windows 机器上 9527 / 9528 被驱动或指纹服务占用），SynaRoute 会自动向上寻找空闲端口；
  4. 卡片上的「服务地址」显示的是实际绑定的端口，复制这里显示的地址用于客户端配置；
  5. 状态指示灯变绿表示服务正在运行；若为红色，悬停可查看失败原因。

因为端口可能自动顺延，务必从设置页复制真实地址，不要想当然写 9527。

接入 Codex CLI

编辑 ~/.codex/config.toml（Windows 上是 C:\Users\<你的用户名>\.codex\config.toml），加入：

[mcp_servers.synaroute]
url = "http://127.0.0.1:9527/mcp/codex"   # 用设置页显示的真实地址

可选：在项目根目录的 AGENTS.md 里加一段提示词，引导 Codex 在合适场景主动调用：

## 多模型协作

遇到复杂的代码审查、架构设计、疑难排查任务时，优先调用 synaroute_ai 工具，
传入当前项目的绝对路径作为 cwd，获取多个模型的综合分析后再动手。

之后在 Codex 里正常提问即可，例如「用 synaroute 帮我审查一下 src/auth 模块的安全性」。

接入 Claude Code

在项目的 .claude/settings.json（或用户级 ~/.claude/settings.json）里加：

{
  "mcpServers": {
    "synaroute": {
      "url": "http://127.0.0.1:9527/mcp/claude-cli"
    }
  }
}

端口同样以设置页显示的真实地址为准。

可选：配置一个 hook，在输入包含「审查 / review / 重构」等词时提示优先走多模型分析：

{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "review|审查|重构|refactor",
        "hooks": [
          {
            "type": "prompt",
            "prompt": "优先调用 synaroute_ai 做多模型分析，传入项目绝对路径作为 cwd"
          }
        ]
      }
    ]
  }
}

工具参数

synaroute_ai 接受以下参数：

参数必填说明
prompt是任务描述，如「审查鉴权模块的安全性」
cwd否当前项目根目录的绝对路径。强烈建议传入，否则会用自动跟随识别到的最近活跃项目
languageHint否回答语言，如 zh / en，省略则跟随 prompt
images否要一起看的图片，相对 cwd 的路径数组。传了它必须同时传 cwd

图片输入

用于「这个报错截图是什么问题」这类需要看图的任务。限制与失败口径：

  • 最多 4 张，单张 不超过 5MB，仅支持 png / jpg / jpeg / gif / webp——这四类是 Anthropic 与 OpenAI 协议共同支持的格式。
  • 路径必须在工作目录内。..、绝对路径、盘符或 UNC 路径，以及指向工作目录外的符号链接都会被拒绝。
  • 凭据类文件名（.env*、密钥、证书）一律拒绝读取，图片入口同样过这道防线。
  • 任何一项不满足即整次调用报错并说明原因，不会静默丢掉某张图。 静默丢弃会让你拿到一个看起来正常、实则没看图的答案。
  • 参与者模型必须支持图片输入。纯文本模型会被上游拒绝，失败原因里会附上相应提示。

参与者按需检索

默认关闭，需在「大脑聚合 → 工具调用」里按分类开启。开启后参与者可用一组只读工具自己决定看哪些文件：读文件（可指定行区间）、正则搜索、列目录、查符号索引。

  • 需要工作目录：由本工具的 cwd 提供，或在桌面端开了自动跟随、填了工作目录。三者都没有时该轮不提供工具，运行日志会写明原因。
  • 工具只读，永不写文件、不执行命令；限制在工作目录内，凭据类文件一律拒读。
  • 有轮数上限（默认 6，可调 2～12）。到顶后会要求模型基于已获得的信息直接出结论。
  • 会明显增加额度消耗：每一轮工具调用都要把完整对话历史重发一次。

返回内容

工具返回一段 Markdown 文本，包含：综合分析或修改计划、参与模型列表、决策者、检索文件数、耗时，以及一句提示——请用你自己的编辑工具执行修改。

多项目隔离

每次工具调用带自己的 cwd，独立成一次聚合任务。项目 A 和项目 B 的聚合各自独立并发，互不影响，参与者与决策者的上下文完全隔离。

日志

MCP 调用会记录到应用的「运行日志」页（类型标为 mcp），以及日志目录下的按日文件。每条记录含时间、工作目录、参与者数、检索文件数、耗时与成败。

常见问题

状态灯是红的，或客户端连不上？

确认设置里开关已打开、状态灯为绿；用设置页显示的真实地址（端口可能不是 9527）；悬停红灯查看失败原因，若提示端口全被占用，可在设置里手动换一个端口。

返回「该分类未启用大脑聚合」？

去「大脑聚合」页，为对应的 category 启用聚合并配好参与者与决策者。

返回「未配置最终决策者」？

大脑聚合页必须选一个决策者才能工作。

SynaRoute 会自己改我的文件吗？

不会。MCP 通道只返回建议，所有文件修改都由你的客户端执行并经你确认。

安全吗？

MCP 服务器只监听 127.0.0.1，不对外网开放，因此不做鉴权。这意味着同一台机器上的其他本地进程理论上也能调用它——单机个人使用场景下这是可接受的取舍，但请不要把该端口转发到公网。

已知边界

  • 文件检索：优先使用 ripgrep（若系统已安装，速度最快）；未安装时回退到内置遍历，功能不受影响，只是稍慢。内置遍历有成本上界（最大深度、文件数上限、只扫常见文本类扩展名，跳过 node_modules、target、dist、.git 等目录），超大仓库可能漏检深层文件。
  • 符号索引检索仅在目标项目已建立索引且系统装了对应 CLI 时生效，否则自动跳过，不影响其他检索方式。
  • 工作目录自动跟随支持 Claude CLI 与 Codex 的会话历史。Claude 桌面端不落盘可解析的项目路径，通常无法自动跟随，请显式传 cwd。

关闭

设置 → MCP 服务器 → 关闭开关。服务立即停止，下次启动不再自动运行。

大脑聚合使用说明