claude code接入mcp

一、什么是 MCP？它解决了什么问题？

Model Context Protocol (MCP) 是一个开源标准，用于在 AI 工具与外部数据源、工具之间建立安全、双向的连接。在 Claude Code 中，MCP 让 Claude 能够直接读取和操作你的数据库、问题跟踪器、监控仪表板、云服务等，而不仅仅是通过你粘贴过去的文本被动工作。

核心价值：从“复制粘贴”到“直接操作”

传统工作流	MCP 增强工作流
手动复制 JIRA 问题描述粘贴给 Claude	Claude 直接读取 JIRA 问题并开始编码
查询数据库，复制结果发给 Claude	Claude 直接查询 PostgreSQL 并分析数据
打开 Sentry 查看错误，手动截图或复制堆栈	Claude 直接拉取错误详情并提出修复方案
编写邮件草稿，复制到 Gmail	Claude 直接生成并发送邮件草稿

---

二、MCP 的核心功能与作用

1. 连接数百种外部工具

通过 MCP 服务器，Claude 可以访问：

• 代码托管：GitHub、GitLab
• 项目管理：JIRA、Linear、Asana
• 数据库：PostgreSQL、MySQL、MongoDB
• 监控：Sentry、DataDog、Statsig
• 协作：Slack、Notion、Google Workspace
• 支付：Stripe、PayPal

2. 实时双向通信

• 主动拉取：Claude 在需要时调用工具读取数据。
• 被动推送（Channels）：MCP 服务器可以将外部事件（如 CI 结果、监控告警、聊天消息）主动推送到你的会话中，让 Claude 对外部事件做出反应。

3. 动态工具发现与按需加载

通过 工具搜索（Tool Search），MCP 服务器无需在会话启动时加载所有工具定义。Claude 仅在需要时搜索并加载相关工具，大幅节省上下文令牌预算。

4. 自动化复杂工作流

串联多个 MCP 工具，实现端到端自动化。例如：

“根据 PostgreSQL 中标记为‘高优先级’的 10 个用户，在 GitHub 创建 Issue，然后生成 Slack 草稿通知团队。”

---

三、如何安装与配置 MCP 服务器

Claude Code 支持四种 MCP 服务器传输方式：HTTP（推荐）、SSE（已弃用）、本地 Stdio 和 WebSocket。

方式一：添加远程 HTTP 服务器（推荐）

HTTP 是连接云服务和远程 MCP 服务器最广泛支持的方式。

# 基本语法
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"

方式二：添加本地 Stdio 服务器

Stdio 服务器作为本地进程运行，适合需要直接访问本地文件系统或自定义脚本的工具。

# 基本语法（注意：-- 分隔 Claude 自身参数与服务器命令）
claude mcp add --transport stdio <名称> -- <命令> [参数...]

# 示例：连接 Airtable
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

重要提示：

• – 之后的所有内容原封不动传递给服务器。
• –env KEY=value 可设置环境变量。
• 服务器运行时，环境变量 CLAUDE_PROJECT_DIR 会被设置为项目根目录，便于解析相对路径。

方式三：使用 JSON 直接配置

# 基本语法
claude mcp add-json <名称> '<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"]}'

管理命令

命令	作用
claude mcp list	列出所有配置的服务器
claude mcp get<name>	查看特定服务器详情
claude mcp remove<name>	删除服务器
claude mcp login<name>	在命令行完成 OAuth 认证
claude mcp logout<name>	清除存储的凭证
/mcp（在 Claude Code 内）	交互式管理面板

---

四、安装范围（Scope）：控制服务器在何处加载

MCP 服务器可在三个层级配置，决定加载位置和是否与团队共享。

范围	存储位置	共享	适用场景
本地（默认）	~/.claude.json（当前项目路径下）	❌ 否	个人开发服务器、实验性配置
项目	项目根目录的.mcp.json	✅ 是（提交到 Git）	团队共享工具（如数据库连接）
用户	~/.claude.json（全局）	❌ 否	跨项目使用的个人实用工具

bash

# 添加项目级服务器（团队共享）
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

优先级：本地 > 项目 > 用户。同名服务器，高优先级覆盖低优先级。

---

五、实际应用示例

示例 1：Sentry 错误监控

bash

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# 在 Claude Code 中运行 /mcp 进行 OAuth 认证

认证后，直接在聊天中提问：

• “过去 24 小时内最常见的错误是什么？”
• “显示错误 ID abc123 的完整堆栈跟踪”
• “哪个部署版本引入了这些新错误？”

示例 2：GitHub 代码管理与 PR 审查

bash

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

使用场景：

• “审查 PR #456 并给出改进建议”
• “为我们刚发现的登录 Bug 创建一个新 Issue”
• “显示所有分配给我的开放 PR”

示例 3：PostgreSQL 数据库查询

bash

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

自然语言查询：

• “本月我们的总收入是多少？”
• “显示 orders 表的完整 Schema”
• “找出 90 天内未进行购买的客户列表”

示例 4：端到端工作流（JIRA → GitHub → Slack）

想象一个场景：“根据 JIRA-123 的描述实现功能，创建 PR，然后通知团队。” —— 只需配置 JIRA、GitHub 和 Slack 的 MCP 服务器，用一句话驱动整个流程。

---

六、如何创建自己的 MCP 服务器

方法一：使用官方 mcp-server-dev 插件（零代码搭建）

这是目前最快的方式，Claude 会引导你完成搭建。

1. 安装插件：
   bash

   /plugin install mcp-server-dev@claude-plugins-official
   /reload-plugins

2. 运行构建 Skill：
   bash

   /mcp-server-dev:build-mcp-server

   Claude 会询问你的用例，自动搭建一个远程 HTTP 或本地 Stdio 服务器脚手架，包括基本的工具定义和连接逻辑。

方法二：手动遵循 MCP 规范构建

1. 学习基础知识：阅读官方 MCP 服务器指南 了解协议基础。
2. 身份验证与测试：参考 Claude 连接器构建文档 实现 OAuth 2.0、API Key 等认证方式。
3. 提交到 Directory：构建完成后，可提交到 Anthropic Directory 供社区使用。

构建时的进阶配置建议

为了让你的服务器在 Claude Code 中表现更佳，可以在工具的 tools/list 响应中添加以下 _meta 注释：

1. 为大型输出提高限制（anthropic/maxResultSizeChars）

当工具返回的数据量很大（如完整数据库 Schema），可以声明允许更大的结果，避免 Claude 只看到文件引用而非实际内容。

json

{
  "name": "get_full_schema",
  "description": "返回完整数据库结构",
  "_meta": {
    "anthropic/maxResultSizeChars": 200000
  }
}

2. 强制每次调用需用户批准（anthropic/requiresUserInteraction）

用于“同意操作”、“授权访问”等必须有人类参与的敏感工具。

json

{
  "name": "grant_production_access",
  "description": "授予生产环境临时访问权限",
  "_meta": {
    "anthropic/requiresUserInteraction": true
  }
}

3. 始终加载该工具（anthropic/alwaysLoad）

如果 Claude 在每个回合都可能用到该工具（如“读取当前时间”），可以绕过工具搜索，直接预加载到上下文。

json

{
  "name": "get_current_time",
  "_meta": {
    "anthropic/alwaysLoad": true
  }
}

4. 处理根级组合器（anyOf/oneOf/allOf）

Claude API 不接受架构根目录的 anyOf/oneOf。Claude Code v2.1.195+ 会自动展平此类架构，并在工具描述中提示哪些参数组属于一起。如果你要编写兼容的服务器，推荐在 properties 内部使用组合器，而非顶层。

---

七、高级功能与调优

1. 工具搜索（Tool Search）：优化上下文使用

• 默认启用：MCP 工具延迟加载，Claude 按需搜索。
• 阈值模式：ENABLE_TOOL_SEARCH=auto:5 表示若所有工具定义占用上下文不足 5%，则预加载，否则延迟。
• 强制预加载：若服务器工具极少且关键，设置 alwaysLoad: true。
• 彻底禁用：ENABLE_TOOL_SEARCH=false。

2. 动态标头认证（headersHelper）

适用于 Kerberos、短期 Token 等非 OAuth 动态认证。Claude Code 执行脚本获取 JSON 格式的请求头。

json

{
  "mcpServers": {
    "internal-api": {
      "type": "http",
      "url": "https://mcp.internal.example.com",
      "headersHelper": "/opt/bin/get-mcp-auth-headers.sh"
    }
  }
}

3. OAuth 2.0 深度配置

• 固定回调端口：–callback-port 8080（用于预注册重定向 URI）。
• 预配置客户端凭证：–client-id + –client-secret（用于不支持动态注册的服务器）。
• 限制 OAuth 范围：在配置中设置 oauth.scopes 限制权限范围。
• 无浏览器模式：claude mcp login –no-browser（适用于 SSH 环境）。

4. 错误重试与自动重连

• HTTP/SSE 服务器断连后自动以指数退避重试（最多 5 次）。
• 工具调用若返回 401/403，Claude Code 会尝试刷新 Token 或重新运行 headersHelper 并重试一次。

5. 输出限制

默认 MCP 工具输出上限为 25,000 个 Token。超出会显示警告。可通过 MAX_MCP_OUTPUT_TOKENS=50000 claude 提高上限。

6. 超时控制

• 工具执行超时：在 .mcp.json 中设置 “timeout”: 600000（毫秒）。
• 空闲超时：HTTP 服务器默认为 5 分钟，Stdio 为 30 分钟。可通过 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT 调整。

---

八、故障排除与最佳实践

问题	可能原因	解决方案
服务器显示“待批准”	项目级服务器未获信任	在 Claude Code 中接受工作区信任对话框
出现spawn ENOENT	command 路径错误	使用which claude 找到绝对路径写入配置
OAuth 认证失败	重定向 URI 不匹配	使用–callback-port 固定端口，并在服务器后台注册该 URI
工具输出被截断	超过MAX_MCP_OUTPUT_TOKENS	提高环境变量值，或让服务器添加anthropic/maxResultSizeChars 注释
服务器启动慢/超时	网络或命令执行慢	设置MCP_TIMEOUT=30000（30 秒）
根级anyOf 导致工具不可见	Claude API 不支持顶层组合器	将组合器移到properties 内部，或升级到 v2.1.195+（自动展平）

---

结语

MCP 是 Claude Code 连接外部世界的“神经系统”。它将 Claude 从只能处理文本的聊天机器人，升级为能够直接操作数据库、管理项目工单、监控生产环境、驱动 CI/CD 的自主开发代理。

• 起步：从一个简单的工具开始（如 GitHub 或 Sentry），感受“一句话驱动”的体验。
• 进阶：使用 mcp-server-dev 插件快速搭建自定义服务器，将内部 API 或专属脚本封装为 MCP 工具。
• 规模化：通过项目级 .mcp.json 与团队共享配置，通过托管设置在企业范围部署标准化工具。

现在，选择你的第一个 MCP 服务器，让 Claude 真正成为你手中的“全能开发工程师”。