MCP集成基础

MCP(Model Context Protocol,模型上下文协议)是Claude Code最强大的扩展机制。

通过MCP,Claude Code能连接上百个外部工具和数据源:GitHub、网络搜索、数据库、监控系统等等。

今天详细介绍MCP的概念、工作原理和实际集成方法。

什么是MCP

核心概念

Model Context Protocol（MCP）是Anthropic于2024年11月推出的开放标准和开源框架，旨在标准化AI系统（如大型语言模型）与外部工具、系统和数据源的集成与数据共享方式。

简单来说，MCP就像是一座桥梁：

一端连接着AI助手（如Claude Code）
另一端连接着各种外部服务和数据源
通过这座桥梁，AI可以安全、高效地访问和操作外部资源

MCP的价值

MCP出现前,每个AI工具都要为每个服务写定制代码,导致:

大量重复工作
质量参差不齐
难维护、难扩展

MCP用标准化解决这些问题:

传统方式:
AI工具A → 定制集成 → GitHub
AI工具A → 定制集成 → Slack
AI工具B → 定制集成 → GitHub
AI工具B → 定制集成 → Slack

MCP方式:
AI工具A → MCP客户端 → MCP标准 → GitHub MCP服务器
AI工具B → MCP客户端 → MCP标准 → GitHub MCP服务器
AI工具C → MCP客户端 → MCP标准 → Slack MCP服务器

好处:

一次开发,处处可用: MCP服务器能被所有支持MCP的AI工具用
更安全: 统一的认证和授权机制
生态好: 社区可以一起开发和维护
扩展快: 新工具快速接入现有的MCP服务器网络

行业采用情况

MCP已经获得了广泛的行业支持：

2025年3月：OpenAI正式采用MCP，集成到ChatGPT桌面应用、Agents SDK和Responses API
2025年4月：Google DeepMind CEO Demis Hassabis确认即将在Gemini模型中支持MCP
2025年12月：Anthropic将MCP捐赠给Linux基金会下的Agentic AI Foundation（AAIF），由Anthropic、Block、OpenAI共同创立，获得Google、Microsoft、AWS、Cloudflare和Bloomberg支持

这使得MCP成为2025年AI工具集成的事实标准。

MCP工作原理

架构概览

MCP采用客户端-服务器架构，包含两个主要层次：

┌─────────────────────────────────────────────────────────┐
│                   应用层（Host）                          │
│              （如Claude Code、ChatGPT等）                 │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                  MCP客户端层                              │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│    │客户端1   │  │客户端2   │  │客户端3   │             │
│    └────┬─────┘  └────┬─────┘  └────┬─────┘             │
└─────────┼─────────────┼─────────────┼───────────────────┘
          │             │             │
          │  MCP协议    │  MCP协议    │  MCP协议
          │  (JSON-RPC) │  (JSON-RPC) │  (JSON-RPC)
          │             │             │
┌─────────▼─────────────▼─────────────▼───────────────────┐
│                  MCP服务器层                              │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│    │GitHub    │  │Sentry    │  │Filesystem│             │
│    │服务器    │  │服务器    │  │服务器    │             │
│    └────┬─────┘  └────┬─────┘  └────┬─────┘             │
└─────────┼─────────────┼─────────────┼───────────────────┘
          │             │             │
┌─────────▼─────────────▼─────────────▼───────────────────┐
│                  外部服务层                               │
│    ┌──────────┐  ┌──────────┐  ┌──────────┐             │
│    │GitHub    │  │Sentry    │  │本地文件  │             │
│    │API       │  │API       │  │系统      │             │
│    └──────────┘  └──────────┘  └──────────┘             │
└─────────────────────────────────────────────────────────┘

核心组件

1. 数据层（Data Layer）

数据层定义了基于JSON-RPC的协议，包括：

生命周期管理：

连接建立和断开
会话管理
错误处理

核心原语：

Tools（工具）：可被AI调用的函数或操作
Resources（资源）：可被AI读取的数据或内容
Prompts（提示）：预定义的提示模板
Notifications（通知）：服务器向客户端发送的事件

2. 传输层（Transport Layer）

传输层定义了数据交换机制：

STDIO传输（本地）：

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

HTTP/SSE传输（远程）：

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "transport": "http"
    }
  }
}

通信流程

让我们看一个完整的交互流程：

1. 连接建立
   Claude Code → [初始化请求] → MCP服务器
   Claude Code ← [服务器能力] ← MCP服务器

2. 工具发现
   Claude Code → [列出工具] → MCP服务器
   Claude Code ← [工具列表+描述] ← MCP服务器

3. 工具调用
   用户: "查看我的GitHub仓库"
   Claude Code → [调用list_repos工具] → GitHub MCP服务器
   GitHub MCP服务器 → [查询GitHub API] → GitHub
   GitHub → [返回仓库列表] → GitHub MCP服务器
   GitHub MCP服务器 → [格式化结果] → Claude Code
   Claude Code → [展示结果] → 用户

4. 资源读取
   Claude Code → [获取README内容] → GitHub MCP服务器
   GitHub MCP服务器 → [读取文件] → GitHub API
   GitHub MCP服务器 ← [文件内容] ← GitHub API
   Claude Code ← [返回内容] ← GitHub MCP服务器

为什么MCP对Claude Code很重要

突破能力边界

Claude Code本身已经很强大，但受限于：

只能访问本地文件系统
无法直接查询外部API
不能访问需要认证的服务
无法获取实时数据

MCP打破了这些限制：

没有MCP的Claude Code:
用户: "帮我查看Sentry中最近的错误"
Claude: 抱歉，我无法直接访问Sentry。请您手动查看。

有MCP的Claude Code:
用户: "帮我查看Sentry中最近的错误"
Claude: [通过Sentry MCP服务器查询]
      这是最近24小时的错误列表：
      1. TypeError in payment.js (23次)
      2. Network timeout in api.js (15次)
      3. Null reference in user-profile.js (8次)

      需要我帮您分析这些错误吗？

工作流整合

MCP使Claude Code能够真正融入你的开发工作流：

从问题到代码，一气呵成：

1. 从Linear/Jira获取任务详情
   ↓
2. 从GitHub拉取相关代码
   ↓
3. 分析Sentry中的错误日志
   ↓
4. 修改代码解决问题
   ↓
5. 运行测试验证
   ↓
6. 提交代码并更新任务状态

所有这些步骤都可以在Claude Code中完成，无需切换工具。

知识增强

通过MCP，Claude Code可以访问：

企业内部知识库
项目文档和Wiki
监控和日志系统
数据库和数据仓库

这让AI助手具备了企业特定的上下文知识。

内置MCP服务器介绍

Claude Code团队和社区提供了丰富的MCP服务器，涵盖各种常见需求。

开发工具类

GitHub MCP服务器

功能：

列出仓库和分支
读取文件内容
搜索代码
查看Issues和Pull Requests
创建Issues和评论

使用场景：

用户: "查看我的react-app仓库中所有开放的issues"
Claude: [通过GitHub MCP查询]
      你的react-app仓库有5个开放的issues：

      #23 - 修复移动端布局问题
      #21 - 添加暗色模式支持
      #19 - 优化首页加载速度
      #17 - 实现用户头像上传
      #15 - 修复表单验证bug

Git MCP服务器

功能：

读取Git历史
查看提交信息
比较分支差异
操作Git仓库

使用场景：

用户: "查看最近5次提交修改了哪些文件"
Claude: [通过Git MCP查询]
      最近5次提交的文件变更：

      commit abc1234 - "优化性能"
      - src/utils/cache.js
      - src/components/ProductList.js

      commit def5678 - "修复bug"
      - src/api/auth.js

搜索与信息类

Brave Search MCP服务器

功能：

网络搜索
本地商户搜索
图片搜索
视频搜索
新闻搜索
AI摘要

配置示例：

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

使用场景：

用户: "搜索React 19的新特性"
Claude: [通过Brave Search查询最新信息]
      React 19的主要新特性包括：

      1. Actions - 简化表单处理
      2. useOptimistic - 优化用户体验
      3. use API - 简化异步操作
      4. Server Components改进

      来源：react.dev官方博客

文件系统类

Filesystem MCP服务器

功能：

安全的文件读写
可配置的访问控制
目录浏览
文件搜索

安全配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    }
  }
}

只有配置的目录可被访问，确保安全性。

监控与错误追踪类

Sentry MCP服务器

功能：

获取项目信息
分析错误
查看Issue详情
触发Seer AI进行根因分析
支持16种不同的工具调用

使用场景：

用户: "分析Sentry中最严重的3个错误"
Claude: [通过Sentry MCP查询和分析]
      最严重的3个错误：

      1. PaymentError (影响1,234用户)
         - 原因：第三方支付API超时
         - 建议：添加重试机制和超时处理

      2. DatabaseConnectionError (影响856用户)
         - 原因：连接池耗尽
         - 建议：增加连接池大小

      3. NullReferenceError (影响423用户)
         - 原因：用户数据未正确初始化
         - 建议：添加空值检查

数据库类

PostgreSQL MCP服务器

功能：

执行查询
查看表结构
分析数据
生成报表

配置示例：

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

如何连接MCP服务器

方法一：CLI向导（推荐）

Claude Code提供了友好的CLI向导来添加MCP服务器：

# 基本添加命令
claude mcp add github --scope user

# 带环境变量的添加
claude mcp add brave-search \
  -e BRAVE_API_KEY=your-api-key \
  --scope user

# 添加远程服务器
claude mcp add sentry \
  --transport http \
  --url https://mcp.sentry.dev/mcp \
  --scope project

交互流程：

$ claude mcp add github --scope user

? Select server type:
  ❯ Official Server
    Community Server
    Custom Server

? Enter configuration:
  Command: npx
  Args: -y @modelcontextprotocol/server-github

? Environment variables (optional):
  GITHUB_TOKEN: ghp_xxxxxxxxxxxxxxxxxxxx

✓ GitHub MCP server added successfully!
✓ Configuration saved to user scope

Restart Claude Code to apply changes.

方法二：直接编辑配置文件

对于复杂配置，可以直接编辑配置文件：

配置文件位置：

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json

# Windows
%APPDATA%/Claude/claude_desktop_config.json

完整配置示例：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token"
      }
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@brave/brave-search-mcp-server"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key"
      }
    },
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "transport": "http"
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects",
        "/Users/username/documents"
      ]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "POSTGRES_URL": "postgresql://user:pass@localhost:5432/db"
      }
    }
  }
}

配置作用域

MCP服务器可以在三个不同的作用域配置：

Local（本地）作用域

位置：项目根目录的 .claude/mcp.json
用途：项目特定的配置、实验性配置、敏感凭证
特点：不会被Git追踪，仅当前项目可用

claude mcp add database --scope local

Project（项目）作用域

位置：项目根目录的 mcp.json
用途：团队共享的服务器、项目必需的工具
特点：可以提交到Git，团队成员共享

claude mcp add github --scope project

User（用户）作用域

位置：用户配置目录
用途：个人常用工具、跨项目的开发工具
特点：所有项目可用

claude mcp add brave-search --scope user

优先级：Local > Project > User

验证配置

配置完成后，验证MCP服务器：

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

# 输出示例：
# MCP Servers (5):
#   ✓ github (user)
#   ✓ brave-search (user)
#   ✓ sentry (project)
#   ✓ filesystem (local)
#   ✓ postgres (local)

# 测试特定服务器
claude mcp test github

在Claude Code中测试：

claude

# 输入测试命令
> 列出我配置的所有MCP服务器

Claude会显示已连接的服务器列表和可用功能

MCP安全认证和OAuth

为什么需要认证

许多MCP服务器需要访问受保护的资源：

GitHub需要Personal Access Token
Sentry需要用户授权
数据库需要连接凭证

MCP支持多种认证方式，其中OAuth 2.1是最安全和标准化的方式。

OAuth 2.1规范

2025年3月，MCP规范引入了OAuth 2.1支持，包括：

关键安全特性：

强制PKCE：保护所有客户端免受攻击
元数据发现：自动发现OAuth端点
动态客户端注册（DCR）：自动注册新客户端

OAuth认证流程

1. 用户添加需要OAuth的MCP服务器
   ↓
2. Claude Code检测到需要OAuth
   ↓
3. 打开浏览器进行授权
   ┌──────────────────────────────┐
   │  Login to Sentry              │
   │  ┌────────────────────────┐   │
   │  │ Email: user@example.com│   │
   │  │ Password: ************ │   │
   │  └────────────────────────┘   │
   │                                │
   │  [Continue]                    │
   └──────────────────────────────┘
   ↓
4. 用户同意授权
   ┌──────────────────────────────┐
   │  Claude Code requests access  │
   │                                │
   │  This app wants to:            │
   │  ✓ Read your projects         │
   │  ✓ View error information     │
   │  ✓ Trigger Seer AI analysis   │
   │                                │
   │  [Deny]  [Allow]              │
   └──────────────────────────────┘
   ↓
5. 获取访问令牌
   ↓
6. 令牌安全存储
   ↓
7. 自动刷新令牌

Sentry OAuth配置实例

添加Sentry MCP服务器：

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

首次使用时会触发OAuth流程：

$ claude

> 查看Sentry中的错误

🔐 Authentication Required

Sentry MCP server requires OAuth authentication.

Opening browser for authorization...

✓ Authorization successful!
✓ Access token saved securely

Now fetching Sentry errors...

配置文件（自动生成）：

{
  "mcpServers": {
    "sentry": {
      "url": "https://mcp.sentry.dev/mcp",
      "transport": "http",
      "oauth": {
        "authorizationUrl": "https://sentry.io/oauth/authorize",
        "tokenUrl": "https://sentry.io/oauth/token",
        "clientId": "auto-registered-client-id",
        "scopes": ["project:read", "event:read", "event:write"]
      }
    }
  }
}

API密钥认证

对于不支持OAuth的服务器，使用API密钥：

GitHub Personal Access Token：

# 1. 在GitHub创建Personal Access Token
# Settings → Developer settings → Personal access tokens → Generate new token

# 2. 添加到环境变量
claude mcp add github \
  -e GITHUB_TOKEN=ghp_your_token_here \
  --scope user

Brave Search API Key：

# 1. 在Brave获取API Key
# https://brave.com/search/api/

# 2. 配置到MCP
claude mcp add brave-search \
  -e BRAVE_API_KEY=your_api_key \
  --scope user

安全最佳实践

使用环境变量而非硬编码：

// ❌ 不好
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_hardcoded_token_here"
      }
    }
  }
}

// ✅ 好
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

然后在shell配置中设置：

# ~/.bashrc 或 ~/.zshrc
export GITHUB_TOKEN="ghp_your_token_here"

使用最小权限原则：

GitHub Token只授予必需的权限
数据库账号使用只读权限
API密钥限制访问范围

定期轮换凭证：

定期更新API密钥
使用短期访问令牌
监控异常访问

不要提交敏感信息到Git：

# .gitignore
.claude/mcp.json
.env
*.key
*.token

实际集成案例

让我们通过几个真实案例来看MCP如何提升开发效率。

案例1：使用Sentry MCP调试生产问题

场景：生产环境出现高频错误，需要快速定位和修复。

步骤1：配置Sentry MCP

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

步骤2：启动Claude Code并查询错误

用户: 查看production项目中最近24小时错误率最高的3个问题

Claude: [通过Sentry MCP查询]

查询到production项目的高频错误：

1. TypeError: Cannot read property 'user' of undefined
   - 文件: src/middleware/auth.js:45
   - 发生次数: 1,234次
   - 影响用户: 456人
   - 首次出现: 18小时前

2. ReferenceError: calculateDiscount is not defined
   - 文件: src/services/pricing.js:89
   - 发生次数: 678次
   - 影响用户: 234人
   - 首次出现: 12小时前

3. NetworkError: Request timeout
   - 文件: src/api/payment.js:123
   - 发生次数: 432次
   - 影响用户: 156人
   - 首次出现: 6小时前

步骤3：深入分析第一个错误

用户: 分析第一个错误的根因

Claude: [调用Sentry Seer AI进行根因分析]

根因分析结果：

问题原因：
auth.js中间件在某些情况下没有正确处理session对象为null的情况。
当用户的session过期但cookie仍然存在时，会触发此错误。

错误堆栈：
1. auth.js:45 - req.session.user访问
2. session.js:23 - session已过期返回null
3. cookie-parser:34 - 解析到过期的session cookie

建议修复：
添加空值检查和session有效性验证

步骤4：查看相关代码并修复

用户: 读取src/middleware/auth.js的内容并修复这个问题

Claude: [读取文件内容并生成修复]

我已经读取了auth.js的代码，问题在第45行：

当前代码：
```javascript
const userId = req.session.user.id;

修复后：

// 检查session和user对象是否存在
if (!req.session || !req.session.user) {
  return res.status(401).json({
    error: 'Session expired. Please login again.'
  });
}

const userId = req.session.user.id;

是否应用这个修复？


**步骤5：应用修复并验证**

用户: 是的，请应用修复

Claude: ✓ 已应用修复到src/middleware/auth.js ✓ 添加了session有效性检查 ✓ 添加了友好的错误响应

建议：

运行单元测试验证修复
在staging环境测试
部署后监控Sentry确认错误消失

### 案例2：使用Linear MCP管理开发任务

**场景**：从Linear任务直接生成实现代码。

**配置Linear MCP**：
```json
{
  "mcpServers": {
    "linear": {
      "url": "https://mcp.linear.app",
      "transport": "http"
    }
  }
}

工作流演示：

用户: 查看分配给我的高优先级任务

Claude: [通过Linear MCP查询]

你有3个高优先级任务：

1. [PROJ-123] 实现用户头像上传功能
   优先级: High
   状态: In Progress
   描述: 允许用户上传和更新个人头像，支持裁剪和压缩

2. [PROJ-124] 优化首页加载速度
   优先级: High
   状态: Todo
   描述: 首页加载时间超过3秒，需要优化到1秒内

3. [PROJ-125] 修复移动端表单验证
   优先级: High
   状态: Todo
   描述: 移动端表单验证不生效，需要修复

────────────────────────────────────────

用户: 开始实现PROJ-123

Claude: [获取任务详情]

任务PROJ-123详情：

标题: 实现用户头像上传功能

详细需求:
- 支持JPG、PNG格式
- 文件大小限制5MB
- 前端裁剪为正方形
- 自动压缩为200x200
- 上传到S3存储
- 更新用户profile

技术栈:
- React前端
- Node.js后端
- AWS S3存储

我建议按以下步骤实现：
1. 创建前端上传组件
2. 实现图片裁剪和压缩
3. 创建后端API端点
4. 实现S3上传逻辑
5. 更新数据库

开始实现第一步吗？

────────────────────────────────────────

用户: 是的，开始实现

Claude: [创建Avatar上传组件]

✓ 创建 src/components/AvatarUpload.jsx
✓ 添加图片选择功能
✓ 集成react-image-crop裁剪库
✓ 实现预览功能

代码已创建，包含：
- 文件选择和验证
- 图片裁剪界面
- 实时预览
- 上传按钮

下一步创建后端API？

────────────────────────────────────────

[继续实现...]

────────────────────────────────────────

用户: 实现完成，更新Linear任务状态

Claude: [通过Linear MCP更新任务]

✓ PROJ-123状态已更新为 "Done"
✓ 添加了实现说明
✓ 标记为已完成

任务完成摘要：
- 创建了5个新文件
- 修改了3个现有文件
- 添加了单元测试
- 更新了API文档

案例3：结合多个MCP服务器的综合工作流

场景：从Figma设计到完整实现的全流程。

用户: 根据Figma设计实现新的产品展示页面

Claude: [检测到需要多个MCP服务器]

这个任务需要：
✓ Figma MCP - 获取设计
✓ GitHub MCP - 访问代码库
✓ Brave Search MCP - 查找最佳实践
✓ Filesystem MCP - 创建文件

开始执行...

步骤1: 从Figma获取设计
[通过Figma MCP读取设计规范]
✓ 获取到布局规范
✓ 提取颜色方案
✓ 导出图标资源

步骤2: 查找React最佳实践
[通过Brave Search查询]
✓ 找到产品展示页面的最佳实践
✓ 了解最新的性能优化技巧

步骤3: 创建组件文件
[通过Filesystem MCP创建]
✓ src/pages/ProductShowcase.jsx
✓ src/components/ProductCard.jsx
✓ src/styles/showcase.css

步骤4: 实现响应式布局
✓ 桌面端布局 (1200px+)
✓ 平板端布局 (768px-1199px)
✓ 移动端布局 (<768px)

步骤5: 优化性能
✓ 图片懒加载
✓ 代码分割
✓ CSS优化

步骤6: 提交代码
[通过GitHub MCP]
✓ 创建feature分支
✓ 提交代码
✓ 创建Pull Request

Pull Request已创建: #234
标题: "实现产品展示页面"
链接: https://github.com/yourorg/repo/pull/234

所有完成！需要我做什么其他的吗？

MCP的实际应用场景

1. 全栈开发

适用工具组合：

GitHub/Git MCP - 代码管理
PostgreSQL/MongoDB MCP - 数据库操作
Sentry MCP - 错误监控
Brave Search MCP - 技术查询

典型工作流：

需求 → Linear任务
  ↓
设计 → Figma MCP获取
  ↓
开发 → Claude Code + 多个MCP
  ↓
测试 → 自动化测试
  ↓
部署 → GitHub MCP提交
  ↓
监控 → Sentry MCP追踪

2. 数据分析

适用工具组合：

PostgreSQL MCP - 数据查询
Brave Search MCP - 外部数据
Filesystem MCP - 本地数据文件

应用示例：

用户: 分析最近30天的用户增长趋势

Claude: [通过PostgreSQL MCP查询]

执行查询:
SELECT DATE(created_at) as date,
       COUNT(*) as new_users
FROM users
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY DATE(created_at)
ORDER BY date;

结果分析：
- 总新增用户: 1,234
- 日均增长: 41.1人
- 增长趋势: 上升13%
- 峰值日期: 2025-12-15 (89人)

需要我生成可视化图表吗？

3. DevOps自动化

适用工具组合：

Sentry MCP - 监控告警
GitHub MCP - 自动修复
Slack MCP - 通知团队

自动化流程：

Sentry检测到错误
  ↓
Claude Code通过Sentry MCP获取详情
  ↓
分析根因
  ↓
通过GitHub MCP创建修复PR
  ↓
通过Slack MCP通知团队

4. 知识管理

适用工具组合：

Notion MCP - 文档管理
GitHub MCP - 代码文档
Brave Search MCP - 外部知识

应用示例：

用户: 为新员工创建React开发入门文档

Claude: 我会整合多个来源创建全面的文档：

1. [Brave Search] 最新React最佳实践
2. [GitHub MCP] 我们项目的代码规范
3. [Notion MCP] 现有团队文档

正在生成文档...

✓ 创建了完整的入门指南
✓ 包含代码示例
✓ 添加了项目特定的注意事项
✓ 已保存到Notion

文档链接: notion.so/react-onboarding

常见问题排查

问题1：MCP服务器无法连接

症状：

Error: Failed to connect to MCP server "github"
Connection timeout after 30s

排查步骤：

检查配置：

# 查看配置
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# 验证JSON格式
python3 -m json.tool claude_desktop_config.json

检查网络：

# 对于HTTP传输，测试URL可访问性
curl https://mcp.sentry.dev/mcp

# 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

检查依赖：

# 确保npx可用
npx --version

# 手动运行MCP服务器测试
npx -y @modelcontextprotocol/server-github

查看详细日志：

# 启用调试模式
claude --verbose

# 或设置环境变量
export DEBUG=mcp:*
claude

问题2：认证失败

症状：

Error: Authentication failed for GitHub MCP server
401 Unauthorized

解决方案：

验证Token有效性：

# 测试GitHub token
curl -H "Authorization: token YOUR_TOKEN" \
  https://api.github.com/user

# 测试Brave API key
curl -H "X-Subscription-Token: YOUR_KEY" \
  https://api.search.brave.com/res/v1/web/search?q=test

检查Token权限：

GitHub需要 repo 和 read:user 权限
确保Token未过期
检查组织访问权限

重新授权OAuth：

# 删除已保存的token
claude mcp remove sentry

# 重新添加触发新的OAuth流程
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

问题3：环境变量未加载

症状：

Error: GITHUB_TOKEN is not defined

解决方案：

检查环境变量：

# 查看当前环境变量
echo $GITHUB_TOKEN

# 检查shell配置
cat ~/.bashrc | grep GITHUB_TOKEN
cat ~/.zshrc | grep GITHUB_TOKEN

正确设置环境变量：

# 添加到shell配置
echo 'export GITHUB_TOKEN="ghp_your_token"' >> ~/.zshrc

# 重新加载配置
source ~/.zshrc

# 验证
echo $GITHUB_TOKEN

在配置中直接设置（仅用于测试）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_actual_token_here"
      }
    }
  }
}

注意：生产环境应使用环境变量而非硬编码。

问题4：MCP服务器响应慢

症状：

MCP server response time: 15s (expected < 3s)

优化方案：

使用本地缓存：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "CACHE_TTL": "300"
      }
    }
  }
}

选择合适的传输方式：

本地服务器：使用STDIO（更快）
远程服务器：使用HTTP + SSE（支持流式）

限制查询范围：

❌ "分析所有仓库的所有issues"
✅ "分析react-app仓库最近7天的issues"

问题5：权限错误

症状：

Error: Permission denied: /path/to/file
Filesystem MCP server cannot access this location

解决方案：

检查文件系统配置：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/allowed/path1",
        "/allowed/path2"
      ]
    }
  }
}

添加访问路径：

# 重新配置包含需要的路径
claude mcp remove filesystem
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path1 /path2 /path3

检查文件权限：

# 确保文件可读
ls -la /path/to/file

# 修改权限（如需要）
chmod +r /path/to/file

问题6：版本不兼容

症状：

Error: MCP protocol version mismatch
Server: v1.0, Client: v0.9

解决方案：

更新Claude Code：

# 检查版本
claude --version

# 更新到最新版
npm install -g @anthropic/claude-code@latest

更新MCP服务器：

# 清除npx缓存
npx clear-npx-cache

# 强制使用最新版本
npx -y @modelcontextprotocol/server-github@latest

锁定版本（如需要）：

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-github@1.0.0"
      ]
    }
  }
}

调试技巧

启用详细日志：

export DEBUG=mcp:*
export MCP_LOG_LEVEL=debug
claude --verbose

单独测试MCP服务器：

# 直接运行服务器
npx -y @modelcontextprotocol/server-github

# 应该看到服务器启动信息

使用MCP Inspector（即将推出）：

# MCP调试工具
claude mcp inspect github

查看Claude Code日志：

# macOS
tail -f ~/Library/Logs/Claude/mcp.log

# Linux
tail -f ~/.local/share/Claude/logs/mcp.log

最佳实践建议

1. 合理组织MCP服务器

按使用频率和作用域组织：

用户级（常用工具）：

claude mcp add brave-search --scope user
claude mcp add github --scope user

项目级（团队共享）：

claude mcp add sentry --scope project
claude mcp add postgres --scope project

本地级（敏感配置）：

claude mcp add database --scope local

2. 安全管理凭证

# 使用密钥管理工具
# macOS Keychain
security add-generic-password \
  -a "$USER" \
  -s "github_token" \
  -w "ghp_your_token"

# 在配置中引用
export GITHUB_TOKEN=$(security find-generic-password \
  -a "$USER" \
  -s "github_token" \
  -w)

3. 监控MCP使用情况

# 定期审查配置
claude mcp list

# 删除不用的服务器
claude mcp remove unused-server

4. 文档化团队配置

在项目的 README.md 中记录：

## MCP服务器配置

本项目使用以下MCP服务器：

1. **Sentry** - 错误监控
   ```bash
   claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

PostgreSQL - 数据库访问

claude mcp add postgres \
  -e POSTGRES_URL="postgresql://localhost:5432/db" \
  --scope project

## 下一步探索

掌握MCP集成后，你可以：

1. **探索更多MCP服务器**
   - [官方MCP服务器仓库](https://github.com/modelcontextprotocol/servers)
   - [社区MCP服务器列表](https://github.com/punkpeye/awesome-mcp-servers)

2. **开发自定义MCP服务器**
   - 查看 [MCP协议规范](https://modelcontextprotocol.io/specification)
   - 学习 [开发自定义服务器](/claude-code/03-高级特性/custom-mcp)

3. **深入实战应用**
   - [使用MCP构建AI工作流](/claude-code/04-实战案例/mcp-workflows)
   - [企业级MCP部署](/claude-code/05-最佳实践/enterprise-mcp)

## 总结

MCP是Claude Code生态的核心扩展机制:

✅ **标准化集成** - 统一协议,广泛兼容
✅ **安全认证** - OAuth 2.1支持,保护数据
✅ **丰富生态** - 数百个现成MCP服务器
✅ **易于配置** - CLI向导和配置文件
✅ **实际价值** - 显著提升开发效率

合理配置和使用MCP服务器,Claude Code就能成为连接整个开发工具链的智能中枢。

## 参考资源

### 官方文档
- [Model Context Protocol官方网站](https://modelcontextprotocol.io/)
- [Claude Code MCP文档](https://code.claude.com/docs/en/mcp)
- [MCP规范](https://modelcontextprotocol.io/specification)

### MCP服务器
- [官方MCP服务器集合](https://github.com/modelcontextprotocol/servers)
- [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers)
- [Sentry MCP文档](https://docs.sentry.io/product/sentry-mcp/)
- [Brave Search MCP](https://github.com/brave/brave-search-mcp-server)

### 教程和指南
- [MCP配置最佳实践](https://scottspence.com/posts/configuring-mcp-tools-in-claude-code)
- [添加MCP服务器到Claude Code](https://mcpcat.io/guides/adding-an-mcp-server-to-claude-code/)
- [MCP与OAuth集成](https://stytch.com/blog/oauth-for-mcp-explained-with-a-real-world-example/)

---

**延伸阅读**：
- [CLAUDE.md配置](/claude-code/03-高级特性/claude-md)
- [自定义MCP服务器开发](/claude-code/03-高级特性/custom-mcp)
- [Slash命令系统](/claude-code/02-核心功能/slash-commands)

什么是MCP​

核心概念​

MCP的价值​

行业采用情况​

MCP工作原理​

架构概览​

核心组件​

1. 数据层（Data Layer）​

2. 传输层（Transport Layer）​

通信流程​

为什么MCP对Claude Code很重要​

突破能力边界​

工作流整合​

知识增强​

内置MCP服务器介绍​

开发工具类​

GitHub MCP服务器​

Git MCP服务器​

搜索与信息类​

Brave Search MCP服务器​

文件系统类​

Filesystem MCP服务器​

监控与错误追踪类​

Sentry MCP服务器​

数据库类​

PostgreSQL MCP服务器​

如何连接MCP服务器​

方法一：CLI向导（推荐）​

方法二：直接编辑配置文件​

配置作用域​

Local（本地）作用域​

Project（项目）作用域​

User（用户）作用域​

验证配置​

MCP安全认证和OAuth​

为什么需要认证​

OAuth 2.1规范​

OAuth认证流程​

Sentry OAuth配置实例​

API密钥认证​

安全最佳实践​

实际集成案例​

案例1：使用Sentry MCP调试生产问题​

案例3：结合多个MCP服务器的综合工作流​

MCP的实际应用场景​

1. 全栈开发​

2. 数据分析​

3. DevOps自动化​

4. 知识管理​

常见问题排查​

问题1：MCP服务器无法连接​

问题2：认证失败​

问题3：环境变量未加载​

问题4：MCP服务器响应慢​

问题5：权限错误​

问题6：版本不兼容​

调试技巧​

最佳实践建议​

1. 合理组织MCP服务器​

2. 安全管理凭证​

3. 监控MCP使用情况​

4. 文档化团队配置​

什么是MCP

核心概念

MCP的价值

行业采用情况

MCP工作原理

架构概览

核心组件

1. 数据层（Data Layer）

2. 传输层（Transport Layer）

通信流程

为什么MCP对Claude Code很重要

突破能力边界

工作流整合

知识增强

内置MCP服务器介绍

开发工具类

GitHub MCP服务器

Git MCP服务器

搜索与信息类

Brave Search MCP服务器

文件系统类

Filesystem MCP服务器

监控与错误追踪类

Sentry MCP服务器

数据库类

PostgreSQL MCP服务器

如何连接MCP服务器

方法一：CLI向导（推荐）

方法二：直接编辑配置文件

配置作用域

Local（本地）作用域

Project（项目）作用域

User（用户）作用域

验证配置

MCP安全认证和OAuth

为什么需要认证

OAuth 2.1规范

OAuth认证流程

Sentry OAuth配置实例

API密钥认证

安全最佳实践

实际集成案例

案例1：使用Sentry MCP调试生产问题

案例3：结合多个MCP服务器的综合工作流

MCP的实际应用场景

1. 全栈开发

2. 数据分析

3. DevOps自动化

4. 知识管理

常见问题排查

问题1：MCP服务器无法连接

问题2：认证失败

问题3：环境变量未加载

问题4：MCP服务器响应慢

问题5：权限错误

问题6：版本不兼容

调试技巧

最佳实践建议

1. 合理组织MCP服务器

2. 安全管理凭证

3. 监控MCP使用情况

4. 文档化团队配置