MCP.json 使用手册
更新时间：2025-12-04
配置文件位置与优先级
- 全局：
~/.comate/mcp.json - 项目：
<workspace>/.comate/mcp.json - 本地（仅当前机器）：
<workspace>/.comate/mcp.local.json（实验性质） - 合并规则：相同 server 名字后写覆盖先写，优先级
local > project > global。解析失败时会在 UI/日志中提示MCP 配置错误。
基本结构
Plain Text
1{
2 "mcpServers": {
3 "serverName": {
4 "transportType": "stdio",
5 "command": "node",
6 "args": ["server.js"],
7 "env": { "TOKEN": "xxx" },
8 "cwd": "/path/to/workdir",
9 "timeout": 50,
10 "disabled": false
11 }
12 }
13}字段解析
| 字段 | 说明 | 默认值 |
|---|---|---|
| type | 传输类型：stdio/sse/streamableHttp | 无，必填 |
| disabled | 是否禁用 | false |
| timeout | 超时（秒） | 30 |
| command | 本地进程入口（仅 stdio） | 必填 |
| args | 命令行参数数组（字符串自动 trim） | [] |
| env | 进程环境变量 | {} |
| cwd | 进程工作目录 | 用户家目录 |
| url | 远程地址（仅 sse/streamableHttp） | 必填 |
| headers | HTTP 头（与 requestInit.headers 合并，headers 优先） | {} |
| requestInit.headers | HTTP 头（较低优先级，主要用于向后兼容） | {} |
占位符与变量解析
支持 $COMATE.ENV.* 占位符，可使用的占位符暂时包括：
USERNAME-> 当前用户WORKSPACE-> 工作区根路径（file URI 转路径） 可嵌入到任意字符串字段：command、args、env 值、cwd。未知占位符会被原样保留。
Plain Text
1{
2 "command": "bun",
3 "args": ["run", "$COMATE.ENV.WORKSPACE/src/servers/roots.ts"],
4 "cwd": "$COMATE.ENV.WORKSPACE"
5}示例
Local / stdio
Plain Text
1{
2 "mcpServers": {
3 "my-stdio-server": {
4 "command": "node",
5 "args": ["server.js", "--port", "8080"],
6 "env": { "PORT": "8080" },
7 "cwd": "$COMATE.ENV.WORKSPACE",
8 "timeout": 45
9 }
10 }
11}Remote / SSE
Plain Text
1{
2 "mcpServers": {
3 "my-sse-server": {
4 "type": "sse",
5 "url": "https://example.com/sse",
6 "headers": { "Authorization": "Bearer ..." },
7 "timeout": 60
8 }
9 }
10}Remote / Streamable HTTP
Plain Text
1{
2 "mcpServers": {
3 "my-streamable-http": {
4 "transportType": "streamableHttp",
5 "url": "https://example.com/mcp",
6 "headers": { "X-Trace": "1" }
7 }
8 }
9}常见问题 & 排查
- 占位符未替换：确认字段是字符串，格式为
$COMATE.ENV.KEY，KEY 是否在支持列表（USERNAME/WORKSPACE）。 - command 找不到文件：检查 cwd 是否正确（默认家目录）；可显式设置
cwd: "$COMATE.ENV.WORKSPACE"。 - HTTP headers 丢失：
requestInit.headers与headers会合并，后者优先；避免键名大小写冲突。