[!abstract] 核心结论 MCP 只规定 Host 与 Server 如何通信；“项目级配置、哪些工具能进本次会话、是否允许写入、失败如何隔离”属于 Agent Harness 的控制面。优雅方案的关键是让项目声明能力需求，让 Harness 负责解析、授权、启动、限流和审计。

[!info] related notes

• 前置概念: MCP 协议, Agent Runtime, 本地 MCP Server
• 操作落地: 项目级 MCP 配置指南
• 网关实现: Docker MCP Gateway
• 相邻概念: Skills, Function Calling, Permission Boundary

MCP 在 Agent Harness 中的配置架构

Harness 应把 MCP 当作受治理的能力依赖

一个成熟 Harness 不是把所有 MCP 工具原样塞给模型，而是把它们纳入 Tool Runtime：发现配置、验证来源、按会话建立连接、过滤工具、执行批准、记录结果，再把必要结果送回模型。

flowchart TD
  P[项目声明：需要哪些能力] --> R[Harness 配置解析器]
  U[用户级偏好与密钥] --> R
  R --> G[策略：信任、allow-list、审批、预算]
  G --> C[MCP Client Registry]
  C --> L[本地 stdio Server]
  C --> H[远程 HTTP Server]
  C --> W[Gateway Profile]
  L --> T[Tool schema 与结果]
  H --> T
  W --> T
  T --> A[Agent run loop / LLM]
  A --> O[Trace、审计、评估]

这个分层避免了两类常见失控：每个项目都复制一套密钥和启动脚本；或把几十个无关工具加载进每次会话，既增加 token，又让模型更难选工具。

四个配置层次各自解决什么

层次	应放什么	不应放什么
用户级	跨项目常用 Server、个人密钥引用、私有实验	团队必须一致的项目工具
项目级	可提交的 Server 声明、项目路径参数、只读工具集	token、生产密码、绝对个人路径
会话级	临时禁用/启用、一次任务的工具选择、审批	可复用的团队事实
网关/组织级	镜像、凭据注入、审计、全局策略、Profile	对业务仓库实现细节的猜测

具体文件和 precedence 由 Host 决定，不属于 MCP 协议。Claude Code 的项目配置是根目录 .mcp.json；Codex 支持用户级和受信项目的 .codex/config.toml。同名 Server 的覆盖而不是字段合并，要在团队规范中明确。

优雅的生命周期：声明、解析、激活、调用、回收

1. 声明：项目提交它需要的“能力名”和非敏感连接形态，例如 codegraph、nx、browser。
2. 解析：Harness 读取当前工作区、Host 允许的项目配置和用户环境变量；未知来源或缺少变量应显式告警，而非静默连接。
3. 激活：仅为当前项目/会话连接所需 Server；stdio Server 由 Host 启动，远程 HTTP Server 建立会话，Gateway 按 Profile 暴露工具。
4. 调用：先按 server/tool allow-list 和读写风险过滤，再让模型选择；高风险写入、网络副作用、生产数据访问走审批。
5. 回收：会话结束关闭连接和子进程；保留结构化 trace，而不持久化敏感返回值。

这解释了“项目级 MCP”为什么不是简单把 JSON 放进 Git：配置文件只是声明入口，真正的安全与生命周期必须由 Harness 和 Host 运行时落实。

Skills 与 MCP 如何配合

Skills 是工作说明与可复用流程，回答“遇到这个任务该按什么步骤、使用何种验证”。MCP 是可执行能力，回答“可以调用什么外部系统”。

Skill：先用 CodeGraph 定位调用链，再读目标文件，最后跑最近测试
  ↓
Harness：根据项目策略只给本会话暴露 codegraph_explore 与测试相关工具
  ↓
MCP：实际执行代码图查询

因此应把工具选择原则写进 Skill/AGENTS.md，把 Server 地址、命令和凭据引用交给 MCP 配置及受控环境；不要在技能正文里硬编码 token 或机器专属路径。

工具预算、权限和观测是运行时问题

• 预算：工具 schema 与返回会占据上下文。按项目 Profile、enabled_tools、延迟工具发现或任务阶段过滤，比“全局装一切”更稳定。
• 权限：把读代码、运行测试、写文件、访问网络、写数据库区分审批级别；Server 可用不代表每个工具都应自动批准。
• 隔离：不可信或依赖复杂的 Server 优先容器化；本地 stdio 仍需限制 cwd、文件目录与环境变量。
• 观测：记录 Server 版本、调用时间、输入摘要、结果大小、失败原因与审批决定，才能复现工具失败或评估收益。

决策规则

• 单项目、少量本地工具：项目级 stdio 声明即可。
• 多 Agent 共享一组容器化工具：用 Docker MCP Gateway Profile 收敛生命周期和凭据。
• 多用户、多机器、长期远程服务与组织级策略：再评估独立的远程 MCP 控制平面。

相关链接

• 项目级 MCP 配置指南
• MCP 客户端配置指南
• Docker MCP Gateway