MCP 扩展

MCP（Model Context Protocol）让 Mogick 使用外部工具和资源。适合把企业系统、文档检索、仿真工具或项目专用服务接入 Agent。

快速添加一个本地 server

在项目 .mogick/mcp.json 中写入：

json

{
  "servers": {
    "my-tool": {
      "type": "local",
      "transport": "stdio",
      "enabled": true,
      "command": ["npx", "-y", "@my/mcp-server"],
      "env": { "API_KEY": "<api-key>" }
    }
  }
}

验证：

bash

mogick mcp list
mogick

进入 TUI 后使用 /mcp 查看状态。完整字段见 MCP 配置。

管理 server

入口	作用
`mogick mcp list`	列出配置、启用状态和来源；不验证连接，实际连接状态请在 TUI `/mcp` 查看
`mogick mcp setup`	交互式新增或修改配置
`/mcp`	在 TUI 查看来源、启停和重启
`Ctrl+P`	从命令面板进入 MCP 与工具列表

配置来源按 ACP 宿主、项目、全局的顺序覆盖同名 server。会话内更新会在任务边界刷新工具，不需要重启整个 Mogick 进程。

懒加载

启动慢或很少使用的 server 可以配置：

json

{
  "startup": "lazy"
}

它会显示为 cold，不阻塞启动。Agent 需要时可以调用 mcp.connect；首次 mcp.call 也可以触发按需连接。结束会话后，不再被其他会话使用的按需连接会释放。

普通 server 省略 startup，默认 eager 连接。

渐进式工具发现

当已连接 MCP 工具的 schema 总量超过上下文预算时，Mogick 自动切换为渐进式模式，不把全部工具定义直接放进模型上下文。Agent 使用：

text

mcp.search → mcp.help → mcp.call

先搜索工具、读取参数，再执行目标工具。这样可以控制 token 占用，并让 server 连接变化时保持工具前缀稳定。看不到每个远程工具名称不一定是故障，可先检查 mcp.list 和 mcp.status。

MCP 元工具

工具	作用
`mcp.list`	列出 server、工具和资源概况
`mcp.status`	查看连接详情
`mcp.wait_ready`	等待正在初始化的 server
`mcp.connect`	连接 cold/lazy server
`mcp.disconnect`	断开按需连接并释放上下文
`mcp.reconnect`	对失败 server 发起一次重连
`mcp.search`	跨 server 搜索工具
`mcp.help`	查看工具参数说明
`mcp.call`	在渐进式模式中调用具体工具
`mcp.read`	读取 server 暴露的资源

mcp.call 可以包装有副作用的远程工具，不应视为只读入口；实际执行仍经过权限审批。

工具到达时机

Eager 本地 server 在首轮请求前有短暂就绪等待。晚于等待窗口连接成功的 server 会把工具追加到当前会话；任务结束后的下一轮一定使用最新工具快照。

当 schema 预算未超限时，连接后的 server 工具可直接出现在工具列表；超限时统一通过渐进式元工具访问。

适用建议

高频、启动快的 server 使用 eager。
低频、启动慢或工具很多的 server 使用 lazy。
本地 command 使用绝对路径。
远程服务优先 HTTP，只有兼容旧服务时使用 SSE。
密钥不要写入可提交的项目配置。

问题排查

按顺序运行：

bash

mogick mcp list
mogick doctor

服务器不出现、disabled、cold、failed 或没有工具时，查看 MCP 问题排查。

MCP 扩展 ​

快速添加一个本地 server ​

管理 server ​

懒加载 ​

渐进式工具发现 ​

MCP 元工具 ​

工具到达时机 ​

适用建议 ​

问题排查 ​