What · 是什么
Model Context Protocol：stdio 子进程 + remote Streamable HTTP 双传输，外部工具接入审查工具链（allowlist 过滤）
通过 Model Context Protocol（MCP）接入外部工具，扩展模型能力
双传输：stdio 子进程（mcp.CommandTransport）+ remote Streamable HTTP（headerTransport）
remote 的 headerTransport 支持 $ENV_VAR 环境变量展开，且对 401/403 返回友好报错
config.json 的 mcp_servers.<name> 配置节点：type(stdio|remote)、command、args、env、url、headers、tools、setup 字段
RegisterAll 注册时带 allowlist 过滤，保留名冲突自动跳过（不覆盖内置工具）
工具经 ToToolDef 转换为 llm.ToolDef 接入统一工具调用链路，基于 github.com/modelcontextprotocol/go-sdk 实现
Why · 为什么
原理 · Principle
让审查模型能调用外部工具（漏洞库查询、内部 API 等），突破纯文本审查边界
stdio 与 remote 双模式覆盖本地子进程与远端服务两种部署形态
安全边界：allowlist 过滤 + 保留名冲突跳过，防止恶意或重复工具定义干扰
How · 怎么做
stdio 模式：mcp_servers.<name> 配 type=stdio + command/args/env，启动子进程 MCP server
remote 模式：type=remote + url 走 Streamable HTTP，headers 中用 $ENV_VAR 注入密钥
工具过滤：tools 字段列允许的工具名；setup 字段做启动准备
冲突规避：RegisterAll 遇保留名自动跳过，无需手动处理
鉴权排障：401/403 时查看友好报错信息定位问题
验证工具接入：确认工具经 ToToolDef 转换后在模型工具列表中可见
案例 · Cases
| 代表性案例 |
|---|
| 接入本地 CLI 型 MCP server：stdio 模式拉起子进程 |
| 接入远端 MCP 网关：remote + HTTP，headers 里 $TOKEN 展开注入密钥 |
| 白名单管控：tools 字段只开放少量工具，缩小攻击面 |
| 企业内部工具：私有 MCP server 挂入审查链路 |
反模式 · Anti-patterns
- 密钥明文写进 headers 而非用 $ENV_VAR 展开，造成密钥泄露
- 忽略 401/403 友好报错：鉴权失败应看报错提示定位，而非盲目重试
- 自定义工具与内置工具重名：RegisterAll 会跳过保留名冲突，误以为注册成功
- stdio 模式没配全 command/args/env，子进程启动失败且无明确提示
- 不配 tools allowlist：工具面过大引入不必要的安全风险
正反实例论证 · Evidence
正例 · Pro
remote 传输 + $ENV_VAR 展开注入密钥
{ "mcp_servers": { "vuln-db": { "type": "remote", "url": "https://mcp.internal.example.com", "headers": { "Authorization": "Bearer $MCP_TOKEN" }, "tools": ["query_vuln"] } }}headerTransport 支持 $ENV_VAR 环境变量展开，密钥不落盘；tools 白名单收敛工具面，工具经 ToToolDef 接入统一工具调用链路。
反例 · Con
密钥明文写进 headers
{ "mcp_servers": { "vuln-db": { "type": "remote", "url": "https://mcp.example.com", "headers": { "Authorization": "Bearer sk-live-xxx" } } }}明文密钥随配置入库即泄露；鉴权失败时 remote 传输对 401/403 有友好报错，应据此排查而非盲目重试。
正例 · Pro
stdio 子进程传输拉起本地 MCP server
{ "mcp_servers": { "git-tools": { "type": "stdio", "command": "npx", "args": ["-y", "@org/mcp-git-tools"] } }}mcp.CommandTransport 以子进程方式启动本地 MCP server，适合 CLI 型工具接入。
反例 · Con
stdio 缺 command/args 子进程起不来
{ "mcp_servers": { "git-tools": { "type": "stdio" } }}stdio 模式未配 command/args，子进程无法启动且无明确提示，工具静默不可用。
正例 · Pro
allowlist 过滤 + 保留名冲突自动跳过
{ "mcp_servers": { "tools-a": { "type": "remote", "url": "https://mcp.example.com", "tools": ["list_files", "read_file"] } }}RegisterAll 注册时按 allowlist 过滤工具面，保留名冲突自动跳过，不覆盖内置工具，安全边界明确。
反例 · Con
自定义工具与内置保留名冲突
{ "mcp_servers": { "review": { "type": "remote", "url": "https://mcp.example.com" } }}server 名/工具名与内置保留名冲突时被 RegisterAll 静默跳过，误以为注册成功，实际模型调不到该工具。