MCP 配置（mcp.json）

MCP 配置保存在独立的 mcp.json，不属于主 config.json。

层级	路径
全局	<config-dir>/mcp.json
项目	<workspace>/.mogick/mcp.json
宿主	ACP 会话注入，不写入本地文件

同名 server 按“ACP 宿主 > 项目 > 全局”整体覆盖，不同名 server 同时保留。MOGICK_CONFIG_FILE 不改变 MCP 加载路径。

推荐结构

servers 使用以 server 名称为键的对象。旧版数组仍可读取，但 Mogick 新写入时使用对象格式。

{
  "servers": {
    "local-tool": {
      "type": "local",
      "transport": "stdio",
      "enabled": true,
      "command": ["python3", "-m", "my_mcp_server", "--port", "8080"],
      "env": { "API_KEY": "<api-key>" }
    }
  }
}

选择传输方式

场景	type	transport	必要字段
本地子进程	local	stdio	command
远程 Streamable HTTP	remote	http	url
兼容 legacy SSE	remote	sse	url

省略 transport 时，本地默认 stdio，远程默认 http。新远程服务优先使用 HTTP，只有服务端明确要求时才使用 SSE。

远程示例

{
  "servers": {
    "remote-api": {
      "type": "remote",
      "transport": "http",
      "enabled": true,
      "url": "https://mcp.example.com/api",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}

包含凭据的 headers 不应提交到版本控制。

字段参考

通用字段

字段	类型	必填	默认值/说明
type	string	建议显式填写	local 或 remote；缺省时按 URL/transport 推断
transport	string	否	stdio、http、sse
enabled	bool	否	默认 false；未启用不会连接
startup	string	否	eager（默认）或 lazy
timeout	int	否	连接/等待超时，毫秒；0 使用客户端默认行为

本地字段

字段	类型	必填	说明
command	string[]	是	第一个元素为可执行文件，其余为参数
env	object	否	追加或覆盖给子进程的字面量环境变量

本地进程继承 Mogick 的进程环境。env 值不会展开 ${VAR}；需要从外部注入密钥时，让服务器直接读取继承的环境变量，不要把占位符写进配置。

相对 command 路径按启动 Mogick 时的当前工作目录解析，而不是按 mcp.json 目录解析。推荐使用绝对路径。

远程字段

字段	类型	必填	说明
url	string	是	MCP 服务地址
headers	object	否	随请求发送的 HTTP 请求头

eager 与 lazy

• startup: "eager"：进程或会话启动时连接。
• startup: "lazy"：保持 cold，直到 mcp.connect、Skill 或首次调用触发。
• 未知 startup 值会回退为 eager 并记录警告。

懒加载适合启动慢、使用频率低或工具 schema 很大的 server。会话关闭时，按需连接且不再被其他会话引用的 lazy server 会释放连接。

管理和热更新

mogick mcp list
mogick mcp setup

mogick mcp setup 是交互式向导，不接受 server 名称和旧版配置 flags。TUI 使用 /mcp 查看来源、启停和状态。

会话中修改 MCP 配置后，新增、删除、启用或变更的 server 会重新协调；未变化的连接保持。当前正在执行的任务继续使用启动时的工具快照，下一轮请求使用更新后的工具集合。

状态

状态	含义
disabled	enabled 为 false
cold	lazy server 尚未触发连接
connecting	正在启动或握手
connected	已连接并可查询能力
failed	启动、网络或协议握手失败

问题排查

运行 mogick mcp list 和 mogick doctor。完整分支见 MCP 已配置但连接失败或没有工具。

路径占位符 <config-dir>、<db-path> 指当前 profile/通道实际生效的路径，见数据目录。