# 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 服务器提供工具定义：
````

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

**资源定义**

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
{
  "permissions": {
    "tools": ["read", "write"],
    "resources": ["database://users"],
    "operations": ["query", "update"]
  }
}
```

## 调试和监控

### 日志记录

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

```

```

```