MCP 参考 - Qoder

MCP（Model Context Protocol）允许 Qoder CLI 接入第三方工具和服务。本页是 MCP 服务器配置的完整参考。使用指南见 MCP 服务。

传输方式

MCP 服务器通过 type 字段指定传输协议：

类型	说明
`stdio`（默认）	启动一个子进程，通过 stdin/stdout 交互。
`sse`	通过 Server-Sent Events HTTP 连接。
`http` / `streamable-http`	通过 HTTP（JSON-RPC + 可选流式）连接。
`ws`	通过 WebSocket / TCP 连接。
`sdk`	内置 SDK 级别的服务器（进程内）。

配置字段

MCP 服务器在 settings.json 的 mcpServers 字段下配置，每个 key 为服务器名：

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["./mcp-server.js"],
      "env": { "API_KEY": "..." },
      "cwd": "/path/to/dir"
    }
  }
}

stdio 类型

字段	类型	说明
`command`	string	启动服务器的命令。
`args`	string[]	传递给命令的参数。
`env`	object	传递给子进程的环境变量。
`cwd`	string	子进程的工作目录。

sse 类型

字段	类型	说明
`url`	string	SSE 端点 URL。
`type`	`"sse"`	传输类型标识。
`headers`	object	HTTP 请求头（可含认证）。

http / streamable-http 类型

字段	类型	说明
`url`	string	HTTP 端点 URL。
`type`	`"http"`	传输类型标识。
`headers`	object	HTTP 请求头。

ws 类型（TCP）

字段	类型	说明
`tcp`	object	TCP 连接参数（host/port）。
`type`	`"ws"`	传输类型标识。

通用可选字段

字段	类型	说明
`timeout`	number	连接/请求超时（毫秒）。
`type`	string	显式指定传输类型。
`description`	string	服务器描述，用于管理视图中展示。
`trust`	boolean	信任该服务器，调用其工具时跳过确认。
`includeTools`	string[]	仅注册列出的工具。
`excludeTools`	string[]	排除列出的工具。
`disabled`	boolean	禁用该服务器（保留配置不删除）。
`alwaysAllow`	string[]	无需确认、始终允许的工具名列表。
`oauth`	object	OAuth 授权配置（字段包括 `enabled`、`clientId`、`clientSecret`、`authorizationUrl`、`tokenUrl`、`scopes`、`callbackPort` 等）。

配置作用范围

MCP 服务器可在多个层级配置：

层级	位置	说明
用户级	`~/.qoder/settings.json` → `mcpServers`	对所有项目可用。
项目级	`<项目>/.qoder/settings.json` → `mcpServers`	需批准后可用（安全考虑）。
项目级	`<项目>/.mcp.json`	需带顶层 `mcpServers` 键；需批准后可用。
本地级	`<项目>/.qoder/settings.local.json` → `mcpServers`	仅本机当前项目；`-s` 的默认作用域，仅在目录受信任时加载。
插件	插件目录下的 `.mcp.json` 或 `mcp.json`	随插件安装加载。
CLI 参数	`--mcp-config <path>`、`--settings`	仅本次会话有效。

同名服务器按以下顺序覆盖（后者覆盖前者）：用户级 → 项目级 settings.json → 项目级 .mcp.json → 本地级 → CLI 参数。项目级 MCP 服务器默认需要逐个批准。可通过以下方式跳过：

mcp.enableAllProjectMcpServers: true：自动批准所有项目级服务器。
mcp.enabledProjectMcpServers：白名单，按名称批准。

两项写在 settings.json 的 mcp 分组下（修改后需重启）：

{
  "mcp": {
    "enableAllProjectMcpServers": true,
    "enabledProjectMcpServers": ["playwright", "context7"]
  }
}

权限与安全

MCP 工具与内置工具一样受权限系统管理——调用前需用户确认（除非使用 auto 或 bypass_permissions 模式）。
--allowed-mcp-server-names：限制仅加载指定名称的 MCP 服务器。
--strict-mcp-config：严格模式，仅加载 --mcp-config 指定文件中的服务器。
mcp.allowed / mcp.excluded：在配置中控制允许或排除的服务器列表。

懒加载模式

当连接了多个 MCP 服务器时，默认会在启动时注册所有工具 schema，可能占用较多首轮 prompt token。启用懒加载（mcp.lazyLoad: true 或 QODER_MCP_LAZY=1）后，CLI 仅暴露三个 meta 工具（mcp_list / mcp_get / mcp_call），按需加载实际工具，节省 token 开销。

管理命令

在交互式会话中使用 /mcp 斜杠命令管理 MCP 服务器：

/mcp — 查看已连接的服务器列表与状态。
/mcp reload（别名 /mcp refresh）— 重新发现 MCP 服务器与工具，适用于添加或修改配置之后。

在命令行使用 qodercli mcp 子命令进行非交互管理：

qodercli mcp add <name> -- <command> — 添加 stdio 服务器。
qodercli mcp list — 列出已配置的服务器。
qodercli mcp remove <name> — 移除服务器。

各子命令的参数与示例见 MCP 服务。

下一步

MCP 使用指南：MCP 服务。
配置项全表：配置项、环境变量与文件路径。
扩展问题排查：Hooks、MCP 和插件问题。

​传输方式

​配置字段

​stdio 类型

​sse 类型

​http / streamable-http 类型

​ws 类型（TCP）

​通用可选字段

​配置作用范围

​权限与安全

​懒加载模式

​管理命令

​下一步