.mcp.json 项目级 MCP 配置示例

用项目根目录的 .mcp.json 为团队共享 MCP 服务器，示例包含远程 HTTP、带令牌的请求头和本地 stdio 数据库，并说明环境变量、审批与优先级。

适用场景

团队希望所有人用同一套外部工具：查错误监控、读 GitHub Issue、查开发库。如果每个人各自用命令添加服务器，配置很快会五花八门。把它们写进项目根目录的 .mcp.json 并提交，新同事拉代码后就拥有同样的工具集。

MCP（Model Context Protocol，模型上下文协议）是让智能体连接外部工具和数据源的标准方式。

模板

项目根目录的 .mcp.json：

{
  "mcpServers": {
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp"
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT}"
      }
    },
    "db": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL_READONLY}"]
    }
  }
}

怎么用 / 怎么改

三种写法对应三类服务器。 远程服务器要写 "type": "http" 和 url；本地进程（stdio）不写 type，只写 command、args 和可选的 env。有 url 却没写 type 是配置错误，该条目会被当成 stdio 并被跳过。sse 已被弃用，优先用 http。
密钥放环境变量。 ${VAR} 取变量值，${VAR:-默认值} 在未设置时取默认值，可用于 command、args、env、url 和 headers。令牌绝不写进 .mcp.json。在你自己的 shell 配置或不被提交的本地文件里设置 GITHUB_PAT 与 DATABASE_URL_READONLY。
数据库连接用只读账号。 官方示例也强调这一点。哪怕提示词再小心，账号权限才是真正的保险。
不想手写也行。 命令行等价写法是 claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/ --header "Authorization: Bearer ..."，--scope project 会写入 .mcp.json。注意命令里带明文令牌会留在 shell 历史里，更推荐手写变量引用。
首次使用要批准。 交互式会话里，Claude Code 会先让你批准项目 .mcp.json 里的服务器。批准前 claude mcp list 显示「待批准」。想重置批准选择，运行 claude mcp reset-project-choices。
在会话里查看状态。 用 /mcp 查看各服务器的连接状态、完成授权（如 Sentry 的 OAuth 登录）以及启用或停用。
限制具体工具。 权限规则里，mcp__db__* 匹配 db 服务器的全部工具，mcp__db__<工具名> 匹配单个工具。写规则前先在 /mcp 里确认真实的工具名。

常见问题或注意事项

变量没设置会怎样。 服务器仍会加载，但 ${VAR} 会以字面文字传递，claude mcp list 和 /mcp 会给出警告。看到连接失败，先检查变量。
某些变量名会被读成空。 在远程服务器的 url 与 headers 里，类似 ANTHROPIC_API_KEY、NPM_TOKEN、HTTPS_PROXY 的凭据类变量名即使已设置也会被读成空，防止仓库配置外泄它们。想用，就复制到一个自己命名的变量再引用，GITHUB_PAT 这类普通名字不受影响。
作用域与优先级。 默认的「本地」范围存于 ~/.claude.json，不共享；project 写入 .mcp.json；user 存于 ~/.claude.json 并对所有项目生效。同名服务器按本地、项目、用户的顺序取最高优先级的一条整体使用，字段不会合并。
批准设置不能由仓库自己下发。 把 enableAllProjectMcpServers 或 enabledMcpjsonServers 提交进项目的 .claude/settings.json，在不受信任的文件夹里不会生效，这样克隆来的仓库无法替你批准自己的服务器。要批准，请放进你的用户设置。
非交互运行不弹批准。 claude -p 这类无法弹窗的运行会直接加载项目服务器。不想让某个服务器在这些场景加载，用 disabledMcpjsonServers 禁用，或者用 --strict-mcp-config。
输出很大会被限制。 工具输出默认上限为 25,000 个 token，可通过环境变量 MAX_MCP_OUTPUT_TOKENS 调高，但更好的做法是让查询自己缩小范围。
服务器就是一段会运行的代码。 只启用你信任的服务器，对第三方提供的 stdio 包尤其要审阅来源后再放进团队共享文件。

.mcp.json 项目级 MCP 配置示例

适用场景

模板

怎么用 / 怎么改

常见问题或注意事项

参考来源