模型上下文协议（MCP）

通过标准化协议将 Claude Code 连接到外部工具和数据源。

什么是 MCP？

MCP（Model Context Protocol，模型上下文协议）是一个开放标准，让 Claude Code 能够与外部服务通信。MCP 服务器不再需要将数据复制粘贴到提示词中，而是让 Claude 直接访问工具和资源。

可以把 MCP 服务器理解为插件，它们赋予 Claude 超越读写文件的新能力。

配置

推荐用 claude mcp add — 它会根据你指定的作用域自动写入对应的配置文件：

claude mcp add --transport stdio --scope project myserver -- npx @my/server --port 8080
claude mcp list
claude mcp remove myserver

一个项目级的 .mcp.json 长这样：

{
"mcpServers": {
  "db": {
    "command": "npx",
    "args": ["-y", "@bytebase/dbhub", "--dsn", "${DATABASE_URL}"]
  }
}
}

claude mcp add 的所有标志（--transport、--env、--scope、--header）必须放在服务器名称之前，用 -- 与命令分隔。注意：mcpServers 不是 .claude/settings.json 的合法 key —— 必须写在 .mcp.json（project）或 ~/.claude.json（local/user）里。

常用 MCP 服务器

数据库访问

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:[email protected]:5432/analytics"

现在 Claude 可以直接查询你的数据库：这周有多少用户注册？

扩展文件系统

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]
    }
  }
}

GitHub

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

启用功能：列出待处理的 PR、检查 PR #42 的 CI 状态、为这个 bug 创建一个 issue

HTTP / 远程服务器

远程 MCP 服务器优先使用 HTTP transport：

{
  "mcpServers": {
    "my-api": {
      "type": "http",
      "url": "https://mcp.example.com/v1",
      "headers": { "Authorization": "Bearer ${MY_API_TOKEN}" }
    }
  }
}

command、args、env、url、headers 中的 ${VAR} 和 ${VAR:-default} 会在启动时从 shell 环境中展开。

MCP 规范里这种 transport 叫 streamable-http；Claude Code 同时接受 "type": "http" 和 "type": "streamable-http" 两种写法。老的 SSE transport（--transport sse）已废弃 —— 优先用 HTTP。

其他热门服务器

• Slack — 搜索消息、发布更新
• Google Drive — 读取文档和电子表格
• Figma — 提取设计规范和资源
• Linear / Jira — 读取和创建 issue
• Sentry — 查询错误日志和异常

可在 Anthropic Directory↗ 浏览已审核 connectors。

作用域优先级与审批

同名服务器在多个作用域同时存在时，按优先级取最高的那一份定义：

1. Local（~/.claude.json，默认）— 仅你自己、当前项目
2. Project（.mcp.json，提交到 git）— 与团队共享
3. User（~/.claude.json）— 你的所有项目

出于安全考虑，Claude Code 第一次使用项目级 .mcp.json 中的服务器前会弹出确认。要重置选择，运行 claude mcp reset-project-choices。

在 .claude/settings.json 里用以下 key（任意作用域）批准、拒绝或自动接受项目服务器：

{
  "enabledMcpjsonServers": ["db"],
  "disabledMcpjsonServers": ["risky-server"],
  "enableAllProjectMcpServers": false
}

企业级部署还可以通过 managed-settings.json 里的 allowedMcpServers / deniedMcpServers 做组织级 allow/deny。

Hooks 中的 MCP 工具

MCP 工具在所有 hook 事件中都作为普通工具出现，名称格式为 mcp__<服务器>__<工具>：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__playwright__.*",
        "hooks": [{ "type": "command", "command": "echo '浏览器操作' >> audit.log" }]
      }
    ]
  }
}

处理大型工具结果

如果你构建的 MCP tool 需要返回大量数据（schemas、配置、批量记录），在该 tool 的 tools/list entry 中添加 _meta["anthropic/maxResultSizeChars"]。Claude Code 可以把这个 tool 的 inline threshold 提高到最高 500,000 字符：

{
  "name": "get_schema",
  "description": "Returns the full database schema",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

如果你不能控制 server，可以在 shell 里提高 MAX_MCP_OUTPUT_TOKENS，或请 server 作者添加该 annotation。

构建你自己的 MCP 服务器

MCP 服务器是通过 stdio 或 HTTP 通信的简单程序。用对应语言的官方 MCP SDK 构建，定义工具（Claude 可以执行的操作）、资源（Claude 可以读取的数据）和 prompts（可复用模板），再用 claude mcp add 把构建后的命令配置到 Claude Code。

延伸阅读

• Skills — 可以引用 MCP 工具的模块化工作流
• Subagents — 可以使用受限工具权限的隔离 workers
• Hooks — 围绕 MCP 工具使用自动执行操作
• 工作流 — 将 MCP 集成到开发工作流中