11.4 MCP 工作原理

了解 MCP 的工作原理有助于更好地使用和调试 MCP 服务器，充分发挥其扩展能力。

MCP 架构#

客户端-服务器模型#

MCP 采用标准的客户端-服务器架构，实现了 Claude Code 与外部工具的解耦和通信：

bash
复制
┌─────────────────┐         ┌─────────────────┐
│   Claude Code   │         │  MCP 服务器     │
│   (客户端)      │◄──────►│   (服务器)       │
└─────────────────┘         └─────────────────┘
│                           │
│                           │
└─────────┬─────────────────┘
│
▼
┌──────────────┐
│  外部服务    │
└──────────────┘

组件说明#

1. Claude Code (客户端):

   • 发起工具调用请求
   • 处理服务器响应
   • 管理服务器连接
   • 提供用户界面

2. MCP 服务器:

   • 提供工具和资源
   • 执行工具调用
   • 返回结果
   • 处理错误

3. 外部服务:

   • 数据库（PostgreSQL、MySQL、MongoDB 等）
   • API（GitHub、AWS、Slack 等）
   • 文件系统（本地和远程）
   • 其他服务（CI/CD、监控、测试等）

通信流程#

初始化流程#

1. 用户启动 Claude Code
2. Claude Code 加载配置
3. 自动连接已配置的 MCP 服务器
4. 发现可用工具和资源
5. 准备接收用户请求

工具调用流程#

bash
复制
1. 用户发起请求
↓
2. Claude Code 分析请求
↓
3. 选择合适的 MCP 工具
↓
4. 构建工具调用请求
↓
5. 发送到 MCP 服务器
↓
6. MCP 服务器执行工具
↓
7. 返回执行结果
↓
8. Claude Code 处理结果
↓
9. 返回给用户

错误处理流程#

bash
复制
1. 工具调用失败
↓
2. MCP 服务器捕获错误
↓
3. 构建错误响应
↓
4. 返回给 Claude Code
↓
5. Claude Code 显示错误
↓
6. 提供恢复建议

传输方式#

HTTP 传输#

特点:

• 基于 HTTP 协议
• 支持远程服务器
• 适合云服务
• 易于监控和调试

流程:

bash
复制
Claude Code → HTTP 请求 → MCP 服务器
          ↓              ↓
      HTTP 响应 ←      工具执行

示例:

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

优势:

• 易于部署和扩展
• 支持负载均衡
• 适合云服务集成
• 跨平台兼容性好

限制:

• 需要稳定的网络连接
• 可能存在网络延迟
• 需要处理超时和重试

SSE 传输#

特点:

• 基于 Server-Sent Events
• 支持实时更新
• 已弃用，不建议使用

注意: SSE 传输已弃用，建议使用 HTTP 传输替代。

stdio 传输#

特点:

• 基于标准输入输出
• 本地进程通信
• 适合本地工具集成

流程:

bash
复制
Claude Code → stdout → MCP 服务器
          ↓              ↓
      stdin ←          工具执行

示例:

bash
复制
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub

优势:

• 无需网络连接
• 低延迟响应
• 安全性高（本地通信）
• 适合敏感数据操作

限制:

• 仅限本地使用
• 需要进程管理
• 资源占用较高
• 不适合分布式系统

数据格式#

JSON-RPC#

MCP 使用 JSON-RPC 2.0 协议进行通信，这是一种轻量级的远程过程调用协议。

请求格式:

json
复制
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1"
    }
  }
}

响应格式:

json
复制
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Tool result"
      }
    ]
  }
}

错误格式:

json
复制
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32601,
    "message": "Method not found"
  }
}

}

bash
复制
### 工具定义
MCP 服务器提供工具定义：

json

{ "tools": [ { "name": "query_database", "description": "Query the database", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "SQL query" } }, "required": ["query"]

bash
复制
  }
}

] }

资源定义

MCP 服务器提供资源定义：

json
复制
{
  "resources": [
    {
      "uri": "database://users",
      "name": "Users Table",
      "description": "User data",
      "mimeType": "application/json"
    }
  ]
}

状态管理#

连接状态#

MCP 服务器有多种连接状态：

状态检查

bash
复制
# 检查 MCP 服务器状态/mcp

# 输出示例MCP 服务器状态：
- github: 已连接
- sentry: 已连接
- database: 连接错误

重连机制

MCP 服务器支持自动重连：

bash
复制
连接断开
↓
等待重试间隔
↓
尝试重连
↓
成功 → 已连接
失败 → 继续重试

性能优化#

连接池#

MCP 使用连接池提高性能：

bash
复制
┌─────────────────┐
│   连接池        │
├─────────────────┤
│ 连接 1         │
│ 连接 2         │
│ 连接 3         │
└─────────────────┘

优势:

• 减少连接开销
• 提高响应速度
• 支持并发请求

缓存机制#

MCP 支持结果缓存：

bash
复制
请求 → 检查缓存
↓
命中 → 返回缓存
未命中 → 执行请求
↓
缓存结果
↓
返回结果

缓存策略:

• 基于时间的过期
• 基于大小的限制
• 基于键的失效

批处理#

MCP 支持批量操作：

json
复制
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "batch_query",
    "arguments": {
      "queries": [
        "SELECT * FROM users LIMIT 10",
        "SELECT * FROM orders LIMIT 10"
      ]
    }
  }
}

安全机制#

身份验证#

MCP 支持多种身份验证方式：

1. OAuth 2.0:

bash
复制
Claude Code → OAuth 流程 → 访问令牌
↓
使用令牌访问

1. API 密钥:

bash
复制
Claude Code → API 密钥 → 服务器

1. 证书:

bash
复制
Claude Code → 证书 → 服务器

加密传输#

MCP 支持加密传输：

bash
复制
Claude Code → 加密数据 → MCP 服务器
↓
解密数据

支持的加密:

• TLS/SSL
• 自定义加密

权限控制#

MCP 提供细粒度权限控制：

json
复制
{

调试和监控#

日志记录#

MCP 服务器记录详细日志：

bash
复制
# 启用详细日志claude --verbose

# 日志示例[INFO] MCP server connected: github
[DEBUG] Tool call: query_database
[INFO] Tool result: 10 rows

性能监控#

MCP 提供性能监控功能，帮助用户了解工具调用的效率和质量。

bash
复制
# 查看性能指标显示 MCP 性能统计

# 输出示例MCP 性能统计：
- github: 平均响应时间 100ms，成功率 98%
- database: 平均响应时间 50ms，成功率 99.5%
- sentry: 平均响应时间 200ms，成功率 95%

错误追踪#

MCP 提供详细的错误追踪功能，帮助用户定位和解决问题。

bash
复制
# 查看错误日志显示 MCP 错误日志

# 输出示例MCP 错误日志：
- database: 连接超时 (3 次)，最后一次 5 分钟前
- github: API 限流 (1 次)，最后一次 10 分钟前
- sentry: 认证失败 (2 次)，最后一次 15 分钟前

调试技巧#

启用调试模式#

bash
复制
# 启用调试模式claude --debug-mcp

查看详细日志#

bash
复制
# 查看详细 MCP 日志claude --verbose

测试服务器连接#

bash
复制
# 测试 MCP 服务器连接/mcp test