3.2 MCP 基础概念和架构

🎯 本节目标

学完本节后，你将能够：

✅ 理解 MCP 的三层架构（Host-Client-Server）
✅ 掌握三种传输类型（HTTP、SSE、Stdio）的区别和选择
✅ 了解配置文件的结构和存储位置
✅ 理解核心原语（Tools、Resources、Prompts）的作用
✅ 能够阅读和编写基本的 MCP 配置

🏗️ MCP 架构全景

三层架构模型

MCP 采用清晰的三层架构，每层职责明确：

┌───────────────────────────────────────────────────────────────┐
│                    📱 MCP Host (主机)                         │
│               Claude Code / Claude Desktop                     │
│                                                                │
│  作用：协调管理所有 MCP 连接                                   │
│  职责：创建客户端、路由请求、管理会话                          │
└───────────────────────────────────────────────────────────────┘
                            │
        ┌───────────────────┼───────────────────┐
        │                   │                   │
┌───────▼────────┐  ┌───────▼────────┐  ┌───────▼────────┐
│ 🔌 MCP Client 1│  │ 🔌 MCP Client 2│  │ 🔌 MCP Client 3│
│   (GitHub)     │  │   (Sentry)     │  │  (Postgres)    │
│                │  │                │  │                │
│ 作用：维护连接  │  │ 作用：维护连接  │  │ 作用：维护连接  │
│ 一对一关系      │  │ 一对一关系      │  │ 一对一关系      │
└───────┬────────┘  └───────┬────────┘  └───────┬────────┘
        │                   │                   │
    MCP Protocol        MCP Protocol        MCP Protocol
   (JSON-RPC 2.0)      (JSON-RPC 2.0)      (JSON-RPC 2.0)
        │                   │                   │
┌───────▼────────┐  ┌───────▼────────┐  ┌───────▼────────┐
│ 🖥️  MCP Server │  │ 🖥️  MCP Server │  │ 🖥️  MCP Server │
│  GitHub API    │  │  Sentry API    │  │   PostgreSQL   │
│   (Remote)     │  │   (Remote)     │  │    (Local)     │
│                │  │                │  │                │
│ 作用：提供工具  │  │ 作用：提供工具  │  │ 作用：提供工具  │
│ 暴露数据和功能  │  │ 暴露数据和功能  │  │ 暴露数据和功能  │
└────────────────┘  └────────────────┘  └────────────────┘

三层详解

Layer 1: MCP Host（主机层）

定义： AI 应用程序本身，负责整体协调。

实例：

Claude Code（命令行 AI 助手）
Claude Desktop（桌面应用）
VS Code + Claude 插件
Zed、Replit、Codeium 等开发工具

核心职责：

会话管理： 跟踪所有活跃的 MCP 连接
客户端创建： 为每个 MCP 服务器创建独立的客户端实例
请求路由： 将 AI 的请求分发给正确的客户端
结果汇总： 整合来自多个服务器的数据

类比： MCP Host 就像交响乐团的指挥，协调所有乐器（MCP 客户端）的演奏。

Layer 2: MCP Client（客户端层）

定义： 维护与单个 MCP 服务器的专用连接。

关键特性：

一对一关系： 每个客户端只连接一个服务器
防止串扰： 严格隔离不同服务器的数据
状态管理： 维护会话状态、认证令牌

生命周期：

1. 初始化：Host 创建 Client
2. 连接：Client 连接到 Server
3. 协商：交换协议版本和能力
4. 工作：处理请求/响应
5. 断开：会话结束或错误

类比： MCP Client 就像外交使节，专门代表 Host 与一个特定国家（Server）打交道。

Layer 3: MCP Server（服务器层）

定义： 提供上下文和功能的程序。

部署方式：

本地服务器（Stdio）： 运行在你的机器上
远程服务器（HTTP）： 云端托管服务

暴露内容：

Tools（工具）： 可执行的函数
Resources（资源）： 可读取的数据
Prompts（提示）： 预定义的提示模板

示例：

GitHub Server： 暴露创建 PR、查看 issue 等工具
PostgreSQL Server： 暴露查询数据库、列出表等工具
Sentry Server： 暴露获取错误报告、分析问题等工具

类比： MCP Server 就像专业服务提供商（律师、医生、会计），提供特定领域的专业工具和数据。

🔌 三种传输类型详解

MCP 支持三种传输机制，每种适用于不同场景：

对比表

特性	HTTP	SSE	Stdio
适用场景	远程云服务	远程实时更新（已弃用）	本地进程
连接方式	HTTP POST 请求	Server-Sent Events	标准输入/输出流
认证方式	OAuth 2.1、API Key	同 HTTP	OS 进程隔离
网络开销	有（HTTP 请求）	有（持久连接）	无（同机器）
安全性	TLS + OAuth	TLS + OAuth	进程权限
实时通知	否（请求-响应）	是（SSE 流）	是（双向流）
推荐度	✅ 推荐	⚠️ 逐步淘汰	✅ 推荐
典型服务	GitHub, Sentry, Notion	Asana（旧版）	Postgres, Sequential Thinking

1. HTTP Transport（推荐用于远程服务）

工作原理

Claude Code                    Remote MCP Server
    │                                 │
    │  1. HTTP POST /mcp              │
    │  ─────────────────────────────→ │
    │  Body: JSON-RPC 2.0 Request     │
    │                                 │
    │  2. HTTP 200 OK                 │
    │  ←───────────────────────────── │
    │  Body: JSON-RPC 2.0 Response    │
    │                                 │

优势

✅ 原生 OAuth 支持： 安全的用户认证流程
✅ 防火墙友好： 标准 HTTPS 端口 443
✅ 云托管简单： 部署到任何 HTTP 服务器
✅ 全球可达： 无需 VPN 或特殊网络配置

配置示例

方式 1：命令行添加

bash

# 基础配置
claude mcp add --transport http github https://mcp.github.com/anthropic

# 带认证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 带环境变量
claude mcp add --transport http notion https://mcp.notion.com/mcp \
  --env API_KEY=your-key

方式 2：配置文件

json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/anthropic",
      "auth": {
        "type": "oauth2",
        "clientId": "your-client-id"
      }
    },
    "custom-api": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}",
        "X-Custom-Header": "value"
      }
    }
  }
}

OAuth 认证流程

1. 用户：claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
2. Claude Code：配置已保存，但未认证
3. 用户：在 Claude Code 中输入 /mcp
4. Claude Code：显示"未认证"状态，提供"登录"按钮
5. 用户：点击"登录"
6. 浏览器：打开 Sentry OAuth 页面
7. 用户：授权 Claude Code 访问
8. 浏览器：重定向回 Claude Code（带 access token）
9. Claude Code：存储加密的 token
10. 完成：现在可以使用 Sentry 工具了

安全特性

TLS 加密： 所有通信通过 HTTPS
OAuth 2.1： 行业标准认证
Token 刷新： 自动处理过期令牌
作用域限制： 只请求必要的权限

2. SSE Transport（逐步淘汰）

现状

⚠️ 已弃用，正在逐步淘汰。新项目请使用 HTTP。

工作原理

Server-Sent Events 允许服务器主动向客户端推送更新：

Claude Code                    Remote MCP Server
    │                                 │
    │  1. HTTP GET /sse               │
    │  ─────────────────────────────→ │
    │  Headers: Accept: text/event-stream
    │                                 │
    │  2. 持久连接建立                 │
    │  ←───────────────────────────── │
    │                                 │
    │  3. 服务器推送事件                │
    │  ←─────────────────────────────  │
    │  data: {"type": "notification"...}
    │                                 │

为什么被淘汰？

HTTP 已经足够满足大多数场景
实时更新可以通过轮询或 Webhook 实现
双向通信用 Stdio 更高效

迁移建议

bash

# 旧配置（SSE）
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 新配置（HTTP）
claude mcp add --transport http asana https://mcp.asana.com/mcp

3. Stdio Transport（推荐用于本地服务）

工作原理

通过标准输入/输出流直接通信：

Claude Code Process              MCP Server Process
      │                                 │
      │  1. 启动子进程                   │
      │  ─────────────────────────────→ │
      │  Command: npx server-package    │
      │                                 │
      │  2. 通过 STDIN 发送请求          │
      │  ─────────────────────────────→ │
      │  {"jsonrpc": "2.0", "method"...}│
      │                                 │
      │  3. 通过 STDOUT 接收响应         │
      │  ←───────────────────────────── │
      │  {"jsonrpc": "2.0", "result"...}│
      │                                 │

优势

✅ 零网络开销： 同一台机器，无需 HTTP
✅ OS 级安全： 进程权限隔离
✅ 调试简单： STDERR 直接显示错误
✅ 低延迟： 直接进程间通信

配置示例

方式 1：命令行添加（NPX 包）

bash

# 基础配置
claude mcp add --transport stdio postgres \
  -- npx -y @modelcontextprotocol/server-postgres

# 带环境变量
claude mcp add --transport stdio airtable \
  --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

# 带参数
claude mcp add --transport stdio filesystem \
  -- npx -y @modelcontextprotocol/server-filesystem /allowed/path

重要： -- 参数分隔符

-- 之前：Claude CLI 的选项（--env, --scope）
-- 之后：MCP 服务器的命令和参数

方式 2：配置文件（推荐）

json

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DB_URL": "postgresql://user:pass@localhost/dbname"
      }
    },
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking"
      ]
    },
    "custom-local-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/server/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

平台差异

macOS/Linux：

json

{
  "command": "npx",
  "args": ["-y", "package-name"]
}

Windows：

json

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "package-name"]
}

⚠️ Windows 需要 cmd /c 包装器。

安全考虑

权限隔离：

json

{
  "filesystem": {
    "type": "stdio",
    "command": "npx",
    "args": [
      "-y",
      "@modelcontextprotocol/server-filesystem",
      "/project/data",  // 只允许访问这个目录
      "/project/docs"   // 和这个目录
    ]
  }
}

环境变量保护：

bash

# 不要硬编码敏感信息
# ❌ 错误
{
  "env": {
    "DB_PASSWORD": "super-secret-password"
  }
}

# ✅ 正确：使用环境变量引用
{
  "env": {
    "DB_PASSWORD": "${DB_PASSWORD}"
  }
}

📁 配置文件详解

配置文件位置层次

MCP 配置遵循明确的优先级顺序：

1. 本地配置（Local Scope）        ← 最高优先级
   ~/.claude.json

2. 项目配置（Project Scope）
   /project/.mcp.json
   /project/.claude/settings.local.json

3. 用户配置（User Scope）
   ~/.claude/user-config.json

4. 企业托管配置（Managed）        ← 最低优先级（管理员控制）
   /etc/claude-code/managed-mcp.json

优先级规则： Local > Project > User > Managed

平台特定路径

macOS

个人配置：
  ~/Library/Application Support/Claude/claude_desktop_config.json
  ~/.claude.json

企业托管：
  /Library/Application Support/ClaudeCode/managed-mcp.json

Windows

个人配置：
  %APPDATA%\Claude\claude_desktop_config.json
  C:\Users\YourName\.claude.json

企业托管：
  C:\ProgramData\ClaudeCode\managed-mcp.json

Linux / WSL

个人配置：
  ~/.claude.json
  /home/username/.claude.json

企业托管：
  /etc/claude-code/managed-mcp.json

完整配置文件结构

~/.claude.json 完整示例：

json

{
  "numStartups": 34,
  "autoUpdaterStatus": "enabled",
  "theme": "dark-daltonized",
  "hasCompletedOnboarding": true,
  "lastOnboardingVersion": "0.2.42",

  "customApiKeyResponses": {
    "approved": ["some-id"],
    "rejected": []
  },

  "projects": {
    "/absolute/path/to/project": {
      "allowedTools": ["Read", "Write", "Bash"],
      "history": ["previous", "commands"],
      "mcpServers": {
        "project-specific-server": {
          "type": "stdio",
          "command": "node",
          "args": ["./scripts/mcp-server.js"]
        }
      },
      "exampleFiles": ["example.js", "template.md"]
    }
  },

  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://mcp.github.com/anthropic"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    },
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
    }
  },

  "lastReleaseNotesSeen": "0.2.45",
  "oauthAccount": {
    "accountUuid": "uuid-here",
    "emailAddress": "you@example.com"
  }
}

项目配置：`.mcp.json`

团队共享配置，存储在项目根目录，可提交到版本控制：

json

{
  "mcpServers": {
    "project-database": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-postgres"
      ],
      "env": {
        "DB_URL": "${PROJECT_DB_URL}"
      }
    },
    "team-docs": {
      "type": "http",
      "url": "https://docs.company.com/mcp",
      "headers": {
        "X-Team-Token": "${TEAM_DOC_TOKEN}"
      }
    }
  }
}

项目配置特性：

✅ 团队共享（Git 提交）
✅ 项目特定设置
⚠️ 需要用户审批（首次使用）

审批流程：

1. 克隆包含 .mcp.json 的项目
2. Claude Code 检测到项目配置
3. 提示："项目要求使用 MCP 服务器 'project-database'，是否允许？"
4. 用户选择：
   [✅ 允许] [❌ 拒绝] [🔍 查看详情]
5. 选择被保存，下次不再询问

重置审批：

bash

claude mcp reset-project-choices

环境变量展开

配置支持环境变量引用：

语法：

${VAR}           → 展开为环境变量 VAR 的值
${VAR:-default}  → 如果 VAR 未设置，使用 default

示例：

json

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    },
    "database": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postgres-server"],
      "env": {
        "DB_HOST": "${DB_HOST:-localhost}",
        "DB_PORT": "${DB_PORT:-5432}",
        "DB_NAME": "${DB_NAME}",
        "DB_USER": "${DB_USER}",
        "DB_PASS": "${DB_PASS}"
      }
    }
  }
}

设置环境变量：

bash

# macOS/Linux
export API_TOKEN="your-token-here"
export DB_HOST="production.database.com"
claude

# Windows (PowerShell)
$env:API_TOKEN = "your-token-here"
claude

配置作用域详解

Local Scope（本地作用域）

bash

claude mcp add --scope local --transport http github https://mcp.github.com

特性：

只对当前用户有效
不包含在项目配置中
存储在 ~/.claude.json
私密配置（API keys、个人服务器）

适用场景：

个人 API 密钥
私有服务器
实验性配置

Project Scope（项目作用域）

bash

cd /project
claude mcp add --scope project --transport stdio postgres -- npx -y postgres-server

特性：

团队共享
存储在项目根目录 .mcp.json
可提交到版本控制
需要用户审批

适用场景：

项目数据库连接
团队共享工具
标准开发环境

User Scope（用户作用域）

bash

claude mcp add --scope user --transport http notion https://mcp.notion.com/mcp

特性：

跨项目可用
用户私有
存储在用户配置目录

适用场景：

个人生产力工具（Notion, Todoist）
常用开发工具
个人偏好设置

企业托管配置

IT 管理员控制的全局配置：

/etc/claude-code/managed-mcp.json:

json

{
  "allowedMcpServers": [
    {"serverName": "github"},
    {"serverName": "sentry"},
    {"serverName": "company-internal-api"}
  ],
  "deniedMcpServers": [
    {"serverName": "filesystem"},  // 阻止文件系统访问
    {"serverName": "shell"}        // 阻止 shell 执行
  ],
  "requiredMcpServers": {
    "security-scanner": {
      "type": "http",
      "url": "https://security.company.com/mcp"
    }
  }
}

规则：

allowedMcpServers 未定义 → 无限制
allowedMcpServers: [] → 完全锁定
deniedMcpServers 优先级最高（始终阻止）
requiredMcpServers 自动添加，用户无法移除

🧩 MCP 核心原语系统

MCP 定义了标准化的"原语"用于上下文交换：

原语概览

MCP 原语（Primitives）
│
├─ 服务器暴露（Server-Exposed）
│  ├─ Resources（资源）  → 可读数据
│  ├─ Prompts（提示）    → 提示模板
│  └─ Tools（工具）      → 可执行函数
│
└─ 客户端暴露（Client-Exposed）
   ├─ Sampling（采样）   → AI 模型调用
   ├─ Roots（根目录）    → 文件系统边界
   └─ Logging（日志）    → 调试信息

1. Resources（资源）

定义： AI 可以读取的任何数据。

特性：

应用程序控制访问（需显式请求）
不会自动加载到上下文
通过 @ 提及引用

资源类型示例：

📄 文件内容
🗄️ 数据库记录
🌐 API 响应
📊 传感器数据
💾 缓存计算结果

访问方法：

resources/list   → 列出所有可用资源
resources/read   → 读取特定资源内容

使用示例：

用户："分析 @github:issue://123 的描述"

背后发生：
1. Claude 调用 resources/list，发现 github:issue://123
2. Claude 调用 resources/read(uri="github:issue://123")
3. GitHub 服务器返回 issue 内容
4. Claude 分析内容并回复

配置示例：

json

{
  "resources": [
    {
      "uri": "file:///project/README.md",
      "name": "项目说明",
      "description": "项目的主要文档",
      "mimeType": "text/markdown"
    },
    {
      "uri": "postgres://localhost/users/table/schema",
      "name": "用户表结构",
      "description": "用户数据库表的 schema",
      "mimeType": "application/json"
    }
  ]
}

2. Prompts（提示）

定义： 服务器提供的结构化消息和指令模板。

特性：

可重用的提示模板
支持参数化
用于标准化常见任务

发现和使用：

prompts/list  → 列出所有可用提示
prompts/get   → 获取特定提示内容（支持参数）

示例：GitHub PR Review 提示

json

{
  "prompts": [
    {
      "name": "review-pr",
      "description": "Review a GitHub pull request",
      "arguments": [
        {
          "name": "pr_number",
          "description": "Pull request number",
          "required": true
        },
        {
          "name": "focus",
          "description": "Review focus area (security, performance, style)",
          "required": false
        }
      ]
    }
  ]
}

调用示例：

用户："使用 GitHub 的 PR 审查提示检查 PR #456"

背后发生：
1. Claude 调用 prompts/get(name="review-pr", arguments={"pr_number": 456})
2. GitHub 服务器返回结构化提示：
   "Review PR #456:
    - Check for security vulnerabilities
    - Verify test coverage
    - Assess code quality
    - Review documentation updates"
3. Claude 使用此提示进行审查

3. Tools（工具）

定义： AI 可以调用的可执行函数。

关键特性：

模型控制： AI 自动决定何时调用（需用户批准）
自描述： 每个工具包含语义描述和参数 schema
动态适配： 参数变化时客户端自动适应

工具结构：

json

{
  "name": "github_create_pr",
  "description": "Create a new pull request in a GitHub repository",
  "inputSchema": {
    "type": "object",
    "properties": {
      "title": {
        "type": "string",
        "description": "Pull request title"
      },
      "body": {
        "type": "string",
        "description": "Pull request description"
      },
      "base": {
        "type": "string",
        "description": "Base branch (default: main)"
      },
      "head": {
        "type": "string",
        "description": "Head branch containing changes"
      }
    },
    "required": ["title", "head"]
  }
}

发现和调用：

tools/list  → 列出所有可用工具
tools/call  → 调用特定工具

调用流程：

用户："创建一个 PR 把 feature-branch 合并到 main"

背后发生：
1. Claude 理解意图
2. Claude 调用 tools/list，发现 github_create_pr
3. Claude 构造参数：
   {
     "title": "Merge feature-branch into main",
     "body": "...",
     "base": "main",
     "head": "feature-branch"
   }
4. 请求用户批准："允许调用 github_create_pr 工具吗？"
5. 用户批准
6. 调用 tools/call(name="github_create_pr", arguments={...})
7. GitHub 服务器创建 PR 并返回结果
8. Claude 报告："PR #789 已创建：https://github.com/repo/pull/789"

4. Sampling（采样）

定义： 允许服务器请求 AI 模型补全。

用途：

服务器需要 AI 推理时的"回调"
保持模型独立性（服务器不绑定特定模型）
客户端控制模型选择、成本、隐私

示例场景：

MCP Tool "code_analyzer" 执行时：
1. 工具读取代码文件
2. 工具请求 Sampling："这段代码的主要问题是什么？"
3. Claude 生成补全
4. 工具使用 AI 分析结果继续处理
5. 返回最终结果

5. Roots（根目录）

定义： 客户端暴露给服务器的文件系统边界。

安全用途：

客户端声明：
roots = ["/Users/you/projects/my-app/"]

服务器只能访问：
✅ /Users/you/projects/my-app/src/index.js
✅ /Users/you/projects/my-app/package.json

服务器不能访问：
❌ /Users/you/Documents/private.txt
❌ /etc/passwd
❌ /Users/you/.ssh/id_rsa

6. Logging（日志）

定义： 服务器向客户端发送日志消息。

日志级别：

debug: 详细调试信息
info: 一般信息
warning: 警告消息
error: 错误消息

用途：

调试 MCP 服务器行为
监控工具执行
错误诊断

🔄 MCP 协议通信流程

初始化序列

Client                                Server
  │                                     │
  │  1. initialize                      │
  │  ─────────────────────────────────→ │
  │  {                                  │
  │    "protocolVersion": "2024-11-05", │
  │    "capabilities": {...},           │
  │    "clientInfo": {                  │
  │      "name": "Claude Code",         │
  │      "version": "0.2.45"            │
  │    }                                │
  │  }                                  │
  │                                     │
  │  2. initialize response             │
  │  ←───────────────────────────────── │
  │  {                                  │
  │    "protocolVersion": "2024-11-05", │
  │    "capabilities": {...},           │
  │    "serverInfo": {                  │
  │      "name": "GitHub MCP",          │
  │      "version": "1.0.0"             │
  │    }                                │
  │  }                                  │
  │                                     │
  │  3. initialized notification        │
  │  ─────────────────────────────────→ │
  │  (表示客户端准备就绪)                │
  │                                     │
  │  4. 正常工作：请求/响应              │
  │  ←─────────────────────────────────→│
  │                                     │

能力协商（Capabilities）

客户端和服务器声明支持的功能：

客户端能力示例：

json

{
  "capabilities": {
    "roots": {
      "listChanged": true
    },
    "sampling": {}
  }
}

服务器能力示例：

json

{
  "capabilities": {
    "resources": {
      "subscribe": true,
      "listChanged": true
    },
    "tools": {
      "listChanged": true
    },
    "prompts": {
      "listChanged": true
    }
  }
}

listChanged 通知： 当服务器声明 "listChanged": true 时，可以发送实时更新通知：

json

// 工具列表发生变化
{
  "method": "notifications/tools/list_changed"
}

// 客户端自动重新调用 tools/list 获取最新列表

JSON-RPC 2.0 消息格式

MCP 使用 JSON-RPC 2.0 作为通信协议。

请求示例：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

响应示例：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "github_create_pr",
        "description": "Create a pull request",
        "inputSchema": {...}
      }
    ]
  }
}

错误响应：

json

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "details": "Missing required parameter 'title'"
    }
  }
}

通知（Notification）：

json

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

通知不需要 id 字段，也不期望响应。

📊 最小可行配置示例

示例 1：无需认证的本地服务器

json

{
  "mcpServers": {
    "sequential-thinking": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sequential-thinking"
      ]
    }
  }
}

使用：

bash

# 保存上述配置到 ~/.claude.json
# 重启 Claude Code
claude

# 服务器自动连接
# 使用 /mcp 查看状态

示例 2：需要 API Key 的服务器

json

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

设置：

bash

# 1. 生成 GitHub Personal Access Token
#    https://github.com/settings/tokens

# 2. 设置环境变量
export GITHUB_TOKEN="ghp_your_token_here"

# 3. 启动 Claude
claude

示例 3：远程 OAuth 服务器

json

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

设置：

bash

# 1. 添加配置
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. 启动 Claude 并认证
claude
> /mcp
# 点击 "Login to Sentry"
# 浏览器完成 OAuth 流程

🎯 本节核心要点

1. MCP 三层架构

Host（主机）→ 协调管理所有连接
  ├─ Client（客户端）→ 一对一连接服务器
  │   └─ Server（服务器）→ 提供工具和数据

2. 三种传输类型选择

场景	推荐传输
云服务（GitHub, Sentry）	HTTP
本地工具（数据库、脚本）	Stdio
旧系统	~~SSE~~（已弃用）

3. 配置文件优先级

Local > Project > User > Managed

4. 六大核心原语

原语	暴露方	作用
Resources	Server	可读数据
Prompts	Server	提示模板
Tools	Server	可执行函数
Sampling	Client	AI 模型调用
Roots	Client	文件系统边界
Logging	Server	调试日志

5. 关键命令

bash

claude mcp add            # 添加服务器
claude mcp list           # 列出所有服务器
claude mcp get <name>     # 查看服务器详情
claude mcp remove <name>  # 移除服务器
/mcp                      # 在 Claude 中查看状态

🚀 下一步

现在你已经掌握了 MCP 的核心架构和配置基础。

在 3.3 创建你的第一个 MCP 集成 中，我们将动手实践：

示例 1（5 分钟）： 添加远程 GitHub 服务器并创建 PR
示例 2（30 分钟）： 配置本地 PostgreSQL 服务器并查询数据
示例 3（60 分钟）： 构建完整的开发工作流（多服务器集成）

准备好动手了吗？ 让我们开始创建你的第一个 MCP 集成！

💡 实践建议： 不要试图一次理解所有概念。先从最简单的远程服务器开始（只需一行命令），然后逐步添加更复杂的配置。MCP 的强大之处在于渐进式采用——从简单开始，按需扩展。

3.2 MCP 基础概念和架构 ​

🎯 本节目标 ​

🏗️ MCP 架构全景 ​

三层架构模型 ​

三层详解 ​

Layer 1: MCP Host（主机层） ​

Layer 2: MCP Client（客户端层） ​

Layer 3: MCP Server（服务器层） ​

🔌 三种传输类型详解 ​

对比表 ​

1. HTTP Transport（推荐用于远程服务） ​

工作原理 ​

优势 ​

配置示例 ​

OAuth 认证流程 ​

安全特性 ​

2. SSE Transport（逐步淘汰） ​

现状 ​

工作原理 ​

为什么被淘汰？ ​

迁移建议 ​

3. Stdio Transport（推荐用于本地服务） ​

工作原理 ​

优势 ​

配置示例 ​

平台差异 ​

安全考虑 ​

📁 配置文件详解 ​

配置文件位置层次 ​

平台特定路径 ​

macOS ​

Windows ​

Linux / WSL ​

完整配置文件结构 ​

项目配置：.mcp.json ​

环境变量展开 ​

配置作用域详解 ​

Local Scope（本地作用域） ​

Project Scope（项目作用域） ​

User Scope（用户作用域） ​

企业托管配置 ​

🧩 MCP 核心原语系统 ​

原语概览 ​

1. Resources（资源） ​

2. Prompts（提示） ​

3. Tools（工具） ​

4. Sampling（采样） ​

5. Roots（根目录） ​

6. Logging（日志） ​

🔄 MCP 协议通信流程 ​

初始化序列 ​

能力协商（Capabilities） ​

JSON-RPC 2.0 消息格式 ​

📊 最小可行配置示例 ​

示例 1：无需认证的本地服务器 ​

示例 2：需要 API Key 的服务器 ​

示例 3：远程 OAuth 服务器 ​

🎯 本节核心要点 ​

1. MCP 三层架构 ​

2. 三种传输类型选择 ​

3. 配置文件优先级 ​

4. 六大核心原语 ​

5. 关键命令 ​

🚀 下一步 ​

3.2 MCP 基础概念和架构

🎯 本节目标

🏗️ MCP 架构全景

三层架构模型

三层详解

Layer 1: MCP Host（主机层）

Layer 2: MCP Client（客户端层）

Layer 3: MCP Server（服务器层）

🔌 三种传输类型详解

对比表

1. HTTP Transport（推荐用于远程服务）

工作原理

优势

配置示例

OAuth 认证流程

安全特性

2. SSE Transport（逐步淘汰）

现状

工作原理

为什么被淘汰？

迁移建议

3. Stdio Transport（推荐用于本地服务）

工作原理

优势

配置示例

平台差异

安全考虑

📁 配置文件详解

配置文件位置层次

平台特定路径

macOS

Windows

Linux / WSL

完整配置文件结构

项目配置：`.mcp.json`

环境变量展开

配置作用域详解

Local Scope（本地作用域）

Project Scope（项目作用域）

User Scope（用户作用域）

企业托管配置

🧩 MCP 核心原语系统

原语概览

1. Resources（资源）

2. Prompts（提示）

3. Tools（工具）

4. Sampling（采样）

5. Roots（根目录）

6. Logging（日志）

🔄 MCP 协议通信流程

初始化序列

能力协商（Capabilities）

JSON-RPC 2.0 消息格式

📊 最小可行配置示例

示例 1：无需认证的本地服务器

示例 2：需要 API Key 的服务器

示例 3：远程 OAuth 服务器

🎯 本节核心要点

1. MCP 三层架构

2. 三种传输类型选择

3. 配置文件优先级

4. 六大核心原语

5. 关键命令

🚀 下一步