11.4 MCP 工作原理
了解 MCP 的工作原理有助于更好地使用和调试 MCP 服务器，充分发挥其扩展能力。
MCP 架构
客户端-服务器模型
MCP 采用标准的客户端-服务器架构，实现了 Claude Code 与外部工具的解耦和通信：
┌─────────────────┐ ┌─────────────────┐
│ Claude Code │ │ MCP 服务器 │
│ (客户端) │◄──────►│ (服务器) │
└─────────────────┘ └─────────────────┘
│ │
│ │
└─────────┬─────────────────┘
│
▼
┌──────────────┐
│ 外部服务 │
└──────────────┘组件说明
Claude Code (客户端):
- 发起工具调用请求
- 处理服务器响应
- 管理服务器连接
- 提供用户界面
MCP 服务器:
- 提供工具和资源
- 执行工具调用
- 返回结果
- 处理错误
外部服务:
- 数据库（PostgreSQL、MySQL、MongoDB 等）
- API（GitHub、AWS、Slack 等）
- 文件系统（本地和远程）
- 其他服务（CI/CD、监控、测试等）
通信流程
初始化流程
- 用户启动 Claude Code
- Claude Code 加载配置
- 自动连接已配置的 MCP 服务器
- 发现可用工具和资源
- 准备接收用户请求
工具调用流程
1. 用户发起请求
↓
2. Claude Code 分析请求
↓
3. 选择合适的 MCP 工具
↓
4. 构建工具调用请求
↓
5. 发送到 MCP 服务器
↓
6. MCP 服务器执行工具
↓
7. 返回执行结果
↓
8. Claude Code 处理结果
↓
9. 返回给用户错误处理流程
1. 工具调用失败
↓
2. MCP 服务器捕获错误
↓
3. 构建错误响应
↓
4. 返回给 Claude Code
↓
5. Claude Code 显示错误
↓
6. 提供恢复建议传输方式
HTTP 传输
特点:
- 基于 HTTP 协议
- 支持远程服务器
- 适合云服务
- 易于监控和调试
流程:
Claude Code → HTTP 请求 → MCP 服务器
↓ ↓
HTTP 响应 ← 工具执行示例:
claude mcp add --transport http github https://api.githubcopilot.com/mcp/优势:
- 易于部署和扩展
- 支持负载均衡
- 适合云服务集成
- 跨平台兼容性好
限制:
- 需要稳定的网络连接
- 可能存在网络延迟
- 需要处理超时和重试
SSE 传输
特点:
- 基于 Server-Sent Events
- 支持实时更新
- 已弃用，不建议使用
注意: SSE 传输已弃用，建议使用 HTTP 传输替代。
stdio 传输
特点:
- 基于标准输入输出
- 本地进程通信
- 适合本地工具集成
流程:
Claude Code → stdout → MCP 服务器
↓ ↓
stdin ← 工具执行示例:
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub优势:
- 无需网络连接
- 低延迟响应
- 安全性高（本地通信）
- 适合敏感数据操作
限制:
- 仅限本地使用
- 需要进程管理
- 资源占用较高
- 不适合分布式系统
数据格式
JSON-RPC
MCP 使用 JSON-RPC 2.0 协议进行通信，这是一种轻量级的远程过程调用协议。
请求格式:
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "tool_name",
"arguments": {
"param1": "value1"
}
}
}响应格式:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"content": [
{
"type": "text",
"text": "Tool result"
}
]
}
}错误格式:
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found"
}
}}
### 工具定义
MCP 服务器提供工具定义：
json
{ "tools": [ { "name": "query_database", "description": "Query the database", "inputSchema": { "type": "object", "properties": { "query": { "type": "string", "description": "SQL query" } }, "required": ["query"] } } ] }
资源定义
MCP 服务器提供资源定义：
{
"resources": [
{
"uri": "database://users",
"name": "Users Table",
"description": "User data",
"mimeType": "application/json"
}
]
}状态管理
连接状态
MCP 服务器有多种连接状态：
状态检查
# 检查 MCP 服务器状态
/mcp
# 输出示例
MCP 服务器状态：
- github: 已连接
- sentry: 已连接
- database: 连接错误重连机制
MCP 服务器支持自动重连：
连接断开
↓
等待重试间隔
↓
尝试重连
↓
成功 → 已连接
失败 → 继续重试性能优化
连接池
MCP 使用连接池提高性能：
┌─────────────────┐
│ 连接池 │
├─────────────────┤
│ 连接 1 │
│ 连接 2 │
│ 连接 3 │
└─────────────────┘优势:
- 减少连接开销
- 提高响应速度
- 支持并发请求
缓存机制
MCP 支持结果缓存：
请求 → 检查缓存
↓
命中 → 返回缓存
未命中 → 执行请求
↓
缓存结果
↓
返回结果缓存策略:
- 基于时间的过期
- 基于大小的限制
- 基于键的失效
批处理
MCP 支持批量操作：
{
"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 支持多种身份验证方式：
- OAuth 2.0:
Claude Code → OAuth 流程 → 访问令牌
↓
使用令牌访问- API 密钥:
Claude Code → API 密钥 → 服务器- 证书:
Claude Code → 证书 → 服务器加密传输
MCP 支持加密传输：
Claude Code → 加密数据 → MCP 服务器
↓
解密数据支持的加密:
- TLS/SSL
- 自定义加密
权限控制
MCP 提供细粒度权限控制：
{
"permissions": {
"tools": ["read", "write"],
"resources": ["database://users"],
"operations": ["query", "update"]
}
}调试和监控
日志记录
MCP 服务器记录详细日志：
# 启用详细日志
claude --verbose
# 日志示例
[INFO] MCP server connected: github
[DEBUG] Tool call: query_database
[INFO] Tool result: 10 rows性能监控
MCP 提供性能监控功能，帮助用户了解工具调用的效率和质量。
# 查看性能指标
显示 MCP 性能统计
# 输出示例
MCP 性能统计：
- github: 平均响应时间 100ms，成功率 98%
- database: 平均响应时间 50ms，成功率 99.5%
- sentry: 平均响应时间 200ms，成功率 95%错误追踪
MCP 提供详细的错误追踪功能，帮助用户定位和解决问题。
# 查看错误日志
显示 MCP 错误日志
# 输出示例
MCP 错误日志：
- database: 连接超时 (3 次)，最后一次 5 分钟前
- github: API 限流 (1 次)，最后一次 10 分钟前
- sentry: 认证失败 (2 次)，最后一次 15 分钟前调试技巧
启用调试模式
# 启用调试模式
claude --debug-mcp查看详细日志
# 查看详细 MCP 日志
claude --verbose测试服务器连接
# 测试 MCP 服务器连接
/mcp test