[!abstract] 目标 将“这个项目需要哪些外部能力”提交到版本控制，同时把密钥和个人机器差异留在安全环境中；每个 Host 使用自己的项目配置文件，不能假定一种格式通用。

[!info] related notes

• 架构背景: MCP 在 Agent Harness 中的配置架构
• 前置概念: MCP 协议, 本地 MCP Server
• 集中代理: Docker MCP Gateway
• 实际工具: CodeGraph, Context7, Nx MCP

项目级 MCP 配置指南

成功状态

新成员检出项目后，可以从仓库看到所需 MCP 能力与用途；在补齐自己的安全环境后，目标 Host 能只加载该项目需要的工具，并通过一条只读调用验证连通性。

先选择“直连”还是“指向 Gateway”

方案	项目配置声明	适用场景
直连 Server	每个 Server 的 command/url	本地轻量工具、项目专属 CLI
Gateway Profile	一条 gateway command + profile	多 Agent 共用容器化工具、统一凭据与治理

无论哪种方案，项目配置都只描述需求和非敏感参数；密钥由 Host 的环境变量、密钥存储或 Gateway 注入。

Host 文件位置不是协议标准

典型项目可同时保存多种 Host 的薄适配文件：

project/
├── .mcp.json            # Claude Code
├── .cursor/mcp.json     # Cursor
├── .vscode/mcp.json     # VS Code / Copilot
├── .codex/config.toml   # Codex（受信项目）
├── .env.example         # 仅变量名，不放秘密
└── AGENTS.md            # 工具选择与验证规则

不要把这当成所有产品都必需的模板。先确认团队实际使用的 Host；没有被任何 Host 读取的配置文件只会形成漂移。

一套项目能力清单

先在 AGENTS.md 或项目文档说明能力用途和最小权限：

能力	推荐工具	默认权限	典型任务
代码关系查询	CodeGraph	只读	调用链、影响范围
Nx 工作区知识	Nx MCP	只读	target、affected、依赖
外部库文档	Context7	网络只读	当前 API、迁移说明
浏览器调试	Chrome DevTools MCP	需审批	页面诊断、自动化

这张表是跨 Host 的真相源；各配置文件只是翻译层。

Claude Code：可提交的 .mcp.json

Claude Code 的 project scope 使用项目根目录 .mcp.json，可由版本控制共享，并会在使用项目配置前要求批准。可用环境变量展开避免提交个人路径和密钥：

{
  "mcpServers": {
    "codegraph": {
      "command": "codegraph",
      "args": ["serve", "--mcp"]
    },
    "docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://mcp.example.com/mcp}",
      "headers": {
        "Authorization": "Bearer ${DOCS_MCP_TOKEN}"
      }
    }
  }
}

变量缺失必须被当作可见的配置问题处理，而非把 literal ${...} 误当凭据。

Codex：受信项目的 .codex/config.toml

Codex 可读取用户级 ~/.codex/config.toml 或项目级 .codex/config.toml。项目配置的重点是明确 cwd、转发哪些变量、允许哪些工具和默认审批模式：

[mcp_servers.codegraph]
command = "codegraph"
args = ["serve", "--mcp"]
cwd = "."
enabled_tools = ["codegraph_explore"]
default_tools_approval_mode = "auto"

[mcp_servers.project_api]
url = "${PROJECT_API_MCP_URL}"
bearer_token_env_var = "PROJECT_API_MCP_TOKEN"
default_tools_approval_mode = "prompt"

enabled_tools 应按项目最小化；写入、部署或生产数据工具不应默认自动批准。配置后用 codex mcp list 或会话内 /mcp 观察实际连接状态。

Gateway Profile：给多 Host 一个受控入口

当同一项目需要 CodeGraph、浏览器、数据库等多项容器化工具时，项目可以只声明 Gateway：

{
  "mcpServers": {
    "project-gateway": {
      "command": "docker",
      "args": ["mcp", "gateway", "run", "--profile", "bodysense", "-q"]
    }
  }
}

Profile 的定义、Server 镜像和 secret 留在 Docker Toolkit/Gateway 控制面；仓库只承诺“此项目需要 bodysense 能力集”。详细边界见 Docker MCP Gateway。

提交前检查清单

• 配置文件确实会被团队使用的 Host 读取。
• 只包含 server 名称、命令、非敏感 URL、目录参数和工具白名单。
• 没有 API key、OAuth token、数据库 DSN 或个人绝对路径。
• 每个 Server 有任务用途和默认风险级别。
• 先执行一条只读调用，再启用写入类工具。
• 配置变更同时更新 AGENTS.md 或本页能力清单。

常见失败

• “配置提交了，但 Codex 没加载。” .mcp.json 是 Claude Code 的项目文件；Codex 应使用 .codex/config.toml 或其用户配置。
• “所有项目都看见了不相关工具。” 把项目专属 Server 从用户级移入项目级或 Profile，缩小暴露面。
• “团队成员不能启动。” 通常是 PATH、Docker、环境变量或批准状态不同；不要把个人路径写死来掩盖。
• “连接成功但工具太多。” 用 Host 的 tool allow-list 或 Gateway Profile 缩减，不要期待模型永远自行选择正确工具。

官方入口

• Claude Code MCP scopes
• Codex MCP configuration