MCP：连接外部工具

Claude Code 通过 Model Context Protocol (MCP) 连接外部工具和数据源。MCP 是一个开源协议，为 AI 工具集成提供标准接口，让你可以把 Claude Code 接入数据库、API、监控系统等上百种工具。

能做什么

接入 MCP 服务器后，你可以这样使用 Claude Code：

实现 JIRA ENG-4521 中描述的功能，并在 GitHub 创建 PR

检查 Sentry 和 Statsig，查看 ENG-4521 功能的使用情况

根据 PostgreSQL 数据库，找出使用过该功能的 10 个随机用户的邮件地址

根据 Figma 新设计稿更新标准邮件模板

给这 10 个用户创建 Gmail 草稿，邀请他们参与新功能的反馈

添加 MCP 服务器

方式一：HTTP 服务器（推荐）

HTTP 是最广泛支持的传输方式，适合连接云端服务。

# 基本语法
claude mcp add --transport http <名称> <URL>

# 连接 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带 Bearer Token 认证
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

方式二：SSE 服务器（已废弃）

提示：SSE 传输已废弃，请使用 HTTP 方式。

claude mcp add --transport sse asana https://mcp.asana.com/sse

方式三：本地 stdio 服务器

本地进程方式，适合需要直接系统访问或自定义脚本的工具。

# 基本语法
claude mcp add [options] <名称> -- <命令> [参数...]

# 添加 Airtable 服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

重要：--transport、--env、--scope、--header 等选项必须放在服务器名称前面，--（双破折号）后面才是传给 MCP 服务器的命令和参数。

Windows 用户注意：原生 Windows（非 WSL）下，使用 npx 的本地 MCP 服务器需要加 cmd /c 包装：

# 正确写法
claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

管理服务器

# 列出所有已配置服务器
claude mcp list

# 查看特定服务器详情
claude mcp get github

# 删除服务器
claude mcp remove github

# 在 Claude Code 内查看服务器状态
/mcp

配置作用域

每个 MCP 服务器都可以指定存储位置（--scope）：

作用域	存储位置	适用场景
local（默认）	~/.claude.json 下项目路径	仅当前项目，不与他人共享
project	项目根目录的 .mcp.json	与团队共享，提交到 git
user	~/.claude.json	跨项目使用，个人专属

# 项目范围（可以提交到 git 共享给团队）
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 用户范围（跨所有项目可用）
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

生成的 .mcp.json 文件示例：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

安全提示：加载项目 .mcp.json 中的服务器前，Claude Code 会要求你确认。用 claude mcp reset-project-choices 重置审批记录。

环境变量扩展

.mcp.json 支持环境变量占位符：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

• ${VAR} — 展开为环境变量值
• ${VAR:-default} — 未设置时使用默认值

OAuth 认证

许多云端 MCP 服务器需要 OAuth 2.0 认证：

1. 添加服务器：claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. 在 Claude Code 内运行 /mcp，按提示完成浏览器登录

认证令牌会安全存储并自动刷新。在 /mcp 菜单中选"Clear authentication"可以撤销访问。

固定回调端口

claude mcp add --transport http \
  --callback-port 8080 \
  my-server https://mcp.example.com/mcp

从 JSON 添加服务器

# HTTP 服务器
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

# stdio 服务器
claude mcp add-json local-weather '{"type":"stdio","command":"/path/to/weather-cli","args":["--api-key","abc123"],"env":{"CACHE_DIR":"/tmp"}}'

从 Claude Desktop 导入

claude mcp add-from-claude-desktop

仅支持 macOS 和 WSL。同名服务器会添加数字后缀（如 server_1）。

实战示例

连接 Sentry 监控错误

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

认证后使用：

最近 24 小时最常见的错误是什么？
给我看看错误 ID abc123 的调用栈
哪次部署引入了这些新错误？

连接 GitHub 做代码审查

claude mcp add --transport http github https://api.githubcopilot.com/mcp/

审查 PR #456 并提出改进建议
为刚发现的 bug 创建新 issue
列出分配给我的所有开放 PR

连接 PostgreSQL 数据库

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

本月总收入是多少？
显示 orders 表的结构
找出 90 天内没有购买记录的用户

使用 MCP 资源

MCP 服务器可以暴露可引用的资源，用 @ 语法引用：

分析 @github:issue://123 并建议修复方案
查阅 @docs:file://api/authentication 中的 API 文档
对比 @postgres:schema://users 和 @docs:file://database/user-model

使用 MCP 提示词作为命令

MCP 服务器暴露的 prompt 可以变成 / 命令：

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "登录流程 bug" high

MCP 工具搜索（大量工具时）

MCP 工具多时，工具定义会占用大量上下文窗口。MCP Tool Search 在需要时按需加载工具。

当 MCP 工具描述超过上下文窗口的 10% 时自动启用。

ENABLE_TOOL_SEARCH 值	行为
未设置（默认）	自动启用，第三方 Base URL 时禁用
true	始终启用
auto	超过 10% 阈值时激活
auto:5	超过 5% 时激活
false	禁用，始终预加载所有工具

# 设置 5% 阈值
ENABLE_TOOL_SEARCH=auto:5 claude

# 完全禁用工具搜索
ENABLE_TOOL_SEARCH=false claude

将 Claude Code 作为 MCP 服务器

Claude Code 本身也可以作为 MCP 服务器运行：

claude mcp serve

在 Claude Desktop 的 claude_desktop_config.json 中配置：

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

企业级管理

方式一：托管 MCP 配置（独占控制）

部署到系统目录，用户无法修改：

系统	路径
macOS	/Library/Application Support/ClaudeCode/managed-mcp.json
Linux/WSL	/etc/claude-code/managed-mcp.json
Windows	C:\Program Files\ClaudeCode\managed-mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "company-internal": {
      "type": "stdio",
      "command": "/usr/local/bin/company-mcp-server",
      "args": ["--config", "/etc/company/mcp-config.json"]
    }
  }
}

方式二：基于策略的控制（白名单/黑名单）

{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" },
    { "serverUrl": "https://*.internal.corp/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "dangerous-server" },
    { "serverUrl": "https://*.untrusted.com/*" }
  ]
}

• allowedMcpServers: []（空数组）= 完全禁止所有 MCP 服务器
• allowedMcpServers 未定义 = 不限制
• 黑名单（deniedMcpServers）优先于白名单

输出限制

设置	默认值
警告阈值	10,000 tokens
最大输出	25,000 tokens

# 增加输出上限
export MAX_MCP_OUTPUT_TOKENS=50000
claude

常见问题

服务器连接失败

• 检查 URL 和认证凭据是否正确
• 运行 /mcp 查看服务器状态和错误信息
• 使用 MCP_TIMEOUT 环境变量增加超时时间：MCP_TIMEOUT=10000 claude

Windows 下 "Connection closed" 错误

• 本地 stdio 服务器需要 cmd /c 包装：-- cmd /c npx -y @some/package

工具太多导致上下文溢出

• 启用 MCP Tool Search（默认已开启），或设置 ENABLE_TOOL_SEARCH=true

相关资源

• 设置：完整配置参考
• 权限：工具权限控制
• Hooks：自动化工作流