MCP 服务器、环境与过滤

把服务定义放在顶层 mcpServers，mcp 对象用于全局服务规则。每个服务选择 command、url 或 httpUrl 之一，避免在同一定义中混用多个传输入口。

Stdio 示例

{
  "mcpServers": {
    "local-tools": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": {
        "API_KEY": "$MY_EXTERNAL_TOKEN"
      },
      "cwd": "/path/to/project",
      "timeout": 30000,
      "trust": false
    }
  }
}

脚本与目录为占位，必须换成实际路径。command 是可执行程序，其他命令参数放 args；cwd 决定子进程工作目录。

关键字段

mcp.allowed 限制可连接的服务名称，mcp.excluded 排除服务；这与服务内部的工具过滤不同。

环境变量

env 支持 $VAR、${VAR}，Windows 还支持 %VAR%；未定义值解析为空字符串。明确写入某服务 env 的变量会被视为有意传递，需逐项审阅，不要硬编码 key。

MCP 专页称继承环境默认自动脱敏，但当前通用配置及 Schema 的 security.environmentVariableRedaction.enabled 默认 false。不能依赖专页的默认保证，应显式配置并核对当前版本。显式 env 是另一条透传路径，不因开启脱敏就必然被过滤。

覆盖扩展服务

本地设置与扩展同名服务合并时，excludeTools 取并集，includeTools 在双方都有名单时取交集；只有一方提供时用该名单。excludeTools 始终优先。

env 合并且本地同名变量覆盖；command、url、timeout 等标量由本地值替换。这是扩展覆盖的专门规则，不应理解为所有配置数组都拼接。

工具命名

发现工具统一使用 mcp_{serverName}_{toolName}，名称会按 API 要求清理，过长名称会缩短。服务名避免下划线，防止策略解析身份歧义；编写策略优先使用 mcpName 与简单 toolName。