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

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

## 适用场景

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

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

## 模板

项目根目录的 `.mcp.json`：

```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}"]
    }
  }
}
```

## 怎么用 / 怎么改

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