Skip to content

3.5 本章小结

🎯 核心知识回顾

1. MCP 是什么?

一句话总结:

MCP (Model Context Protocol) 是 AI 工具集成的通用协议标准,让 Claude Code 能够像使用 USB-C 一样连接到任何外部工具、数据库和服务。

核心价值:

问题MCP 解决方案效果
M×N 集成复杂度标准化协议(M+N)线性复杂度
150,000 tokens 开销渐进式加载98.7%减少 → 2,000 tokens
手动数据流转自动工具调用端到端自动化
硬编码集成动态发现自适应和自描述

2. MCP 三层架构

┌─────────────────────────────────────┐
│   📱 MCP Host (Claude Code)         │  ← 协调管理
│   创建客户端 | 路由请求 | 管理会话    │
└────────────────┬────────────────────┘

     ┌───────────┼───────────┐
     │           │           │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Client 1│ │ Client 2│ │ Client 3│  ← 一对一连接
│ GitHub  │ │ Sentry  │ │Postgres │
└────┬────┘ └────┬────┘ └────┬────┘
     │           │           │
┌────▼────┐ ┌────▼────┐ ┌────▼────┐
│ Server 1│ │ Server 2│ │ Server 3│  ← 提供工具和数据
│ GitHub  │ │ Sentry  │ │Postgres │
└─────────┘ └─────────┘ └─────────┘

关键概念:

  • Host: 主机应用(Claude Code)
  • Client: 每服务器一个客户端(1:1 关系)
  • Server: 暴露工具、资源、提示

3. 三种传输类型

传输类型适用场景认证方式推荐度
HTTP远程云服务OAuth 2.1推荐
SSE远程实时更新OAuth⚠️ 已弃用
Stdio本地进程环境变量推荐

选择指南:

  • GitHub/Sentry/Notion → HTTP
  • PostgreSQL/文件系统 → Stdio
  • 旧系统 → 迁移到 HTTP

4. 六大核心原语

服务器暴露(Server-Exposed)

原语作用访问方式
Resources可读数据(文件、API 响应)@mention
Prompts提示模板/命令
Tools可执行函数Claude 自动调用

客户端暴露(Client-Exposed)

原语作用用途
SamplingAI 模型调用服务器请求 AI 推理
Roots文件系统边界安全限制访问范围
Logging调试日志监控和故障排除

5. 配置文件层次

优先级(高 → 低):

1. Local Scope (本地)
   ~/.claude.json
   └─ 个人私有配置

2. Project Scope (项目)
   /project/.mcp.json
   └─ 团队共享配置(Git)

3. User Scope (用户)
   ~/.claude/user-config.json
   └─ 跨项目个人配置

4. Managed (企业托管)
   /etc/claude-code/managed-mcp.json
   └─ IT 管理员控制

配置模板:

json
{
  "mcpServers": {
    "server-name": {
      "type": "http",              // 或 "stdio"
      "url": "https://...",        // HTTP only
      "command": "npx",            // Stdio only
      "args": ["-y", "package"],   // Stdio only
      "env": {                     // 环境变量
        "KEY": "${ENV_VAR}"
      }
    }
  }
}

6. MCP vs Skills 对比

维度SkillsMCP
定位工作流程和指令外部工具和数据
触发/ 斜杠命令@ 引用或自动调用
内容Markdown 文档可执行服务器程序
数据静态文件实时 API 调用
复杂度低(写文档)中到高(配置服务器)
Token开销高(全文加载)低(按需调用)
使用场景代码审查流程GitHub/数据库集成

组合使用:

Skill(定义流程) + MCP(提供工具) = 强大自动化

示例:
/production-incident (Skill)
  → 调用 @sentry (MCP)
  → 调用 @github (MCP)
  → 调用 @postgres (MCP)
  → 完整故障诊断自动化

7. 快速开始三步骤

bash
# 步骤 1:添加远程服务器(5 分钟)
claude mcp add --transport http github https://mcp.github.com/anthropic

# 步骤 2:认证
claude
> /mcp
# 点击 "Login"

# 步骤 3:使用
> 列出我的 GitHub 仓库

8. 核心命令速查

命令作用
claude mcp add添加 MCP 服务器
claude mcp list列出所有服务器
claude mcp get <name>查看服务器详情
claude mcp remove <name>移除服务器
/mcp在 Claude 中查看状态
/permissions管理工具权限
/context查看 token 使用
/clear清除上下文

❓ 常见问题(FAQ)

Q1: MCP 和 Skills 应该用哪个?

A: 两者结合使用效果最好。

使用 Skills 当:

  • 需要标准化工作流程(如代码审查)
  • 提供项目特定的指令和模板
  • 不需要外部 API 或实时数据

使用 MCP 当:

  • 需要访问外部服务(GitHub, Sentry, Notion)
  • 需要查询数据库或 API
  • 需要实时数据

组合示例:

markdown
# Skill: deploy-to-production

1. 使用 @github 检查 main 分支状态
2. 使用 @postgres 备份数据库
3. 使用 @sentry 确认无严重错误
4. 执行部署并更新 @linear issue

Q2: 如何选择 HTTP 还是 Stdio 传输?

A: 根据服务器位置选择。

场景推荐传输原因
云服务(GitHub, Sentry)HTTP原生 OAuth,防火墙友好
本地工具(数据库, 脚本)Stdio零网络开销,低延迟
公司内部 APIHTTP支持远程访问和认证

经验法则:

  • 如果需要 OAuth → 用 HTTP
  • 如果在同一台机器 → 用 Stdio

Q3: 为什么我的 MCP 服务器连接失败?

A: 按这个清单排查:

1. 检查 Node.js 版本

bash
node --version  # 应该 >= 18.17

2. 验证配置语法

bash
jq empty ~/.claude.json

3. 测试命令手动执行

bash
npx -y @modelcontextprotocol/server-postgres

4. 检查环境变量

bash
echo $DATABASE_URL

5. 查看日志

bash
claude --mcp-debug

常见错误 & 解决方案:

错误解决方案
Command not found: npx安装 Node.js
JSON parse error使用 jq 验证语法
ENOENT: no such file使用绝对路径
Permission deniedchmod +x 或检查权限

Q4: OAuth 认证失败怎么办?

A: 尝试以下步骤:

步骤 1:清除旧认证
> /mcp
# 选择服务器 → Clear authentication

步骤 2:重新登录
# 点击 "Login" → 浏览器完成 OAuth

步骤 3:检查权限范围
# 确保授予了必要的 scopes
# GitHub 需要:repo, read:user
# Sentry 需要:project:read, event:read

步骤 4:验证 token
> /mcp
# 查看 "Authenticated as" 和 "Scopes"

Q5: 工具调用返回太多数据,超过 token 限制怎么办?

A: 三种解决方案:

方案 1:增加 token 限制

bash
export MAX_MCP_OUTPUT_TOKENS=50000
claude

方案 2:优化查询

sql
-- ❌ 返回所有数据
SELECT * FROM users;

-- ✅ 只返回必要数据
SELECT id, email, name FROM users
WHERE status = 'active'
LIMIT 100;

方案 3:使用 Skill 指导

markdown
# 查询优化规则

- 始终使用 `LIMIT`
- 只 SELECT 需要的列
- 使用 WHERE 过滤
- 聚合函数优先(COUNT, SUM)

Q6: 如何在团队中共享 MCP 配置?

A: 使用项目配置 + 环境变量模板。

1. 创建 .mcp.json(提交到 Git)

json
{
  "mcpServers": {
    "project-db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postgres-server"],
      "env": {"DB_URL": "${PROJECT_DB_URL}"}
    }
  }
}

2. 创建 .env.example(提交到 Git)

bash
PROJECT_DB_URL=postgresql://user:password@host:5432/dbname

3. 团队成员设置

bash
# 复制模板
cp .env.example .env

# 编辑个人凭据
nano .env

# 启动 Claude
claude

# 批准项目服务器
> (首次会提示,选择 "Allow"

4. 添加到 .gitignore

.env
.claude/settings.local.json

Q7: 企业 IT 阻止了我需要的 MCP 服务器怎么办?

A: 与 IT 管理员沟通。

准备材料:

  1. 业务需求: 为什么需要这个服务器?

    • 例:需要 GitHub MCP 自动化 PR 创建,节省每天 2 小时
  2. 安全说明: 服务器的安全措施

    • OAuth 认证
    • 最小权限原则
    • 审计日志
  3. 替代方案: 如果完全不允许,有什么替代方案?

    • 使用 Skills 封装手动流程
    • 请求 IT 提供安全的内部 MCP 服务器

示例请求邮件:

主题:请求允许 GitHub MCP 服务器访问

您好,

我是 [团队名称] 的 [你的角色]。我请求允许使用 GitHub MCP 服务器,
理由如下:

业务需求:
- 自动化 PR 创建和代码审查流程
- 预计每周节省 10+ 小时手动操作时间

安全措施:
- 使用 GitHub OAuth 认证(无需存储密码)
- 只请求最小权限(repo, read:user)
- 所有操作有审计日志

技术细节:
- 服务器 URL: https://mcp.github.com/anthropic
- 传输类型:HTTPS(端口 443)
- 数据不存储在本地

请批准此请求。如有疑问,我很乐意详细说明。

谢谢!
[你的名字]

Q8: 如何调试 MCP 服务器内部的问题?

A: 使用三级调试方法。

Level 1:连接问题

bash
claude mcp get postgres
# 查看配置和状态

Level 2:认证问题

> /mcp
# 查看认证状态和权限范围

Level 3:执行问题

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

# 查看详细日志
[MCP DEBUG] Tool call: postgres_query
[MCP DEBUG] Parameters: {...}
[MCP DEBUG] Response: {...}

服务器端日志:

> /mcp
# 选择服务器
# 查看 "Recent Logs"

手动验证:

bash
# 直接测试数据库连接
psql $DATABASE_URL

# 直接调用 MCP 服务器
npx -y @modelcontextprotocol/server-postgres
# 发送 JSON-RPC 请求测试

Q9: MCP 的性能开销有多大?

A: MCP 显著 减少 开销。

传统工具调用 vs MCP:

指标传统方式MCP 方式改进
Token 开销150,0002,00098.7% ↓
工具列表10,100300-50095-97% ↓
中间结果50,0000100% ↓
响应时间5-10秒1-2秒50-80% ↓

性能优化技巧:

  • 使用 LIMIT 限制查询结果
  • 启用服务器端缓存
  • 并行调用独立工具
  • 监控 token 使用(/context

Q10: 能否创建自己的 MCP 服务器?

A: 可以!Anthropic 提供了 SDK。

快速开始:

bash
# 安装 MCP SDK
npm install @modelcontextprotocol/sdk

# 创建服务器
npx create-mcp-server my-custom-server

最简服务器示例:

javascript
// server.js
const { MCPServer } = require('@modelcontextprotocol/sdk');

const server = new MCPServer({
  name: 'my-custom-server',
  version: '1.0.0',

  tools: [{
    name: 'hello',
    description: 'Say hello',
    inputSchema: {
      type: 'object',
      properties: {
        name: { type: 'string' }
      }
    },
    async execute({ name }) {
      return { greeting: `Hello, ${name}!` };
    }
  }]
});

server.listen();

配置使用:

json
{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/server.js"]
    }
  }
}

学习资源:


📋 快速参考指南

指南 1:添加 MCP 服务器

远程服务器(HTTP):

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

# 带认证头
claude mcp add --transport http api https://api.example.com/mcp \
  --header "Authorization: Bearer ${TOKEN}"

# 指定作用域
claude mcp add --scope project --transport http sentry https://mcp.sentry.dev/mcp

本地服务器(Stdio):

bash
# NPM 包
claude mcp add --transport stdio postgres \
  --env DB_URL=${DATABASE_URL} \
  -- npx -y @modelcontextprotocol/server-postgres

# 本地脚本
claude mcp add --transport stdio custom \
  -- node /path/to/server.js

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

指南 2:配置文件编辑

位置: ~/.claude.json

模板:

json
{
  "mcpServers": {
    "服务器名": {
      "type": "http | stdio",

      // HTTP 配置
      "url": "https://...",
      "headers": {"Key": "Value"},

      // Stdio 配置
      "command": "npx | node | python",
      "args": ["arg1", "arg2"],

      // 通用
      "env": {
        "ENV_VAR": "${VALUE}"
      },
      "disabled": false  // 临时禁用
    }
  }
}

指南 3:环境变量管理

设置方式:

临时(当前会话):

bash
export DATABASE_URL="postgresql://..."
claude

永久(添加到 shell 配置):

bash
echo 'export DATABASE_URL="postgresql://..."' >> ~/.zshrc
source ~/.zshrc

项目级(.env 文件):

bash
# .env
DATABASE_URL=postgresql://...
API_KEY=secret123

# 加载
source .env  # 或 export $(cat .env | xargs)
claude

变量展开语法:

json
{
  "env": {
    "REQUIRED": "${ENV_VAR}",           // 必须设置
    "OPTIONAL": "${ENV_VAR:-default}"   // 可选,默认值
  }
}

指南 4:故障排除 Checklist

服务器无法连接:

  • [ ] 检查 Node.js 版本(node --version >= 18.17)
  • [ ] 验证 JSON 语法(jq empty ~/.claude.json
  • [ ] 测试命令手动执行
  • [ ] 检查环境变量(echo $VAR
  • [ ] 查看日志(claude --mcp-debug

认证失败:

  • [ ] 清除旧认证(/mcp → Clear authentication)
  • [ ] 重新登录(浏览器 OAuth)
  • [ ] 检查权限范围(Scopes)
  • [ ] 验证 token 未过期

工具调用失败:

  • [ ] 检查工具权限(/permissions
  • [ ] 查看服务器日志(/mcp → Recent Logs)
  • [ ] 启用调试(claude --mcp-debug
  • [ ] 验证输入参数类型
  • [ ] 检查企业策略(managed-mcp.json)

🛤️ 学习路径建议

路径 1:初学者(1-2 周)

目标: 能够使用现成的 MCP 服务器。

Week 1:基础

  • [ ] 完成 3.1 - 本章介绍(理解 MCP 价值)
  • [ ] 完成 3.2 - 基础概念和架构(掌握核心概念)
  • [ ] 添加第一个远程服务器(GitHub)
  • [ ] 完成 OAuth 认证流程
  • [ ] 尝试 3-5 个工具调用

Week 2:实践

  • [ ] 完成 3.3 示例 1(远程服务器)
  • [ ] 完成 3.3 示例 2(本地服务器)
  • [ ] 配置 2-3 个常用 MCP 服务器
  • [ ] 解决至少 1 个配置问题
  • [ ] 将 MCP 整合到日常工作流

成功标准:

  • ✅ 能添加和配置 MCP 服务器
  • ✅ 能完成 OAuth 认证
  • ✅ 能使用 /mcp/permissions 管理
  • ✅ 能解决基本连接问题

路径 2:进阶用户(2-3 周)

目标: 掌握高级配置和性能优化。

Week 1-2:基础 + 高级配置

  • [ ] 完成初学者路径
  • [ ] 完成 3.3 示例 3(多服务器工作流)
  • [ ] 配置多环境(开发/测试/生产)
  • [ ] 使用项目配置(.mcp.json)
  • [ ] 创建团队共享配置

Week 3:优化和最佳实践

  • [ ] 学习 3.4 性能优化策略
  • [ ] 实施 token 管理
  • [ ] 配置审计日志
  • [ ] 学习三级调试方法
  • [ ] 优化查询和缓存

成功标准:

  • ✅ 能管理多环境配置
  • ✅ 能优化 token 使用
  • ✅ 能系统化排查问题
  • ✅ 能指导团队成员使用

路径 3:专家级(3-4 周)

目标: 创建自定义 MCP 服务器和企业集成。

Week 1-3:基础 + 进阶

  • [ ] 完成进阶用户路径
  • [ ] 深入学习 JSON-RPC 2.0 协议
  • [ ] 研究 MCP SDK 文档
  • [ ] 阅读开源 MCP 服务器代码

Week 4:开发和部署

  • [ ] 创建第一个自定义 MCP 服务器
  • [ ] 实现 Tools、Resources、Prompts
  • [ ] 添加认证和安全措施
  • [ ] 编写测试用例
  • [ ] 部署到生产环境

进阶主题:

  • [ ] 实现服务器端缓存
  • [ ] 添加监控和告警
  • [ ] 集成企业 SSO
  • [ ] 创建可重用插件
  • [ ] 贡献开源 MCP 服务器

成功标准:

  • ✅ 能创建自定义 MCP 服务器
  • ✅ 能实现企业级安全
  • ✅ 能优化服务器性能
  • ✅ 能贡献社区和指导他人

📚 推荐资源

官方资源

核心文档:

官方博客:

社区资源

GitHub:

教程和文章:

视频教程:

  • YouTube 搜索:"MCP Claude Code tutorial"
  • Anthropic 官方频道

工具和插件

开发工具:

  • MCP Inspector:调试 MCP 服务器
  • MCP 配置验证器:检查配置文件
  • Claude Code 插件市场

预构建服务器(前 10 名):

  1. GitHub - 代码管理
  2. Sentry - 错误监控
  3. PostgreSQL - 数据库查询
  4. Sequential Thinking - 结构化推理
  5. Filesystem - 文件操作
  6. Playwright - 浏览器自动化
  7. Notion - 知识管理
  8. Linear - 项目管理
  9. Slack - 团队通信(通过 Rube)
  10. Perplexity - 实时搜索

学习社区

Discord/Slack:

  • Claude 官方 Discord
  • MCP 开发者社区

Reddit:

  • r/ClaudeAI
  • r/MachineLearning

Stack Overflow:

  • Tag: [mcp] [claude-code]

🎯 下一步行动建议

立即行动(今天)

如果你是完全新手:

1. 添加第一个 MCP 服务器
   → claude mcp add --transport http github https://mcp.github.com/anthropic

2. 完成 OAuth 认证
   → claude 后输入 /mcp

3. 尝试第一个工具调用
   → "列出我的 GitHub 仓库"

如果你已有基础:

1. 配置项目级 .mcp.json

2. 添加 2-3 个本地服务器
   - PostgreSQL
   - Sequential Thinking
   - Filesystem

3. 创建第一个使用 MCP 的 Skill

如果你是进阶用户:

1. 实施多环境配置

2. 优化 token 使用
   - 添加查询优化 Skill
   - 监控 /context

3. 设置审计日志

本周计划

目标 1: 整合 MCP 到日常工作流

  • [ ] 确定 3 个最常用的外部服务
  • [ ] 配置对应的 MCP 服务器
  • [ ] 创建 Skill 封装常见任务

目标 2: 提升团队效率

  • [ ] 在团队中分享 MCP 设置
  • [ ] 创建团队 .mcp.json 配置
  • [ ] 编写内部 MCP 使用指南

目标 3: 掌握故障排除

  • [ ] 尝试故意破坏配置并修复
  • [ ] 练习三级调试方法
  • [ ] 记录常见问题和解决方案

本月计划

Week 1: 基础巩固

  • 完成所有示例
  • 配置 5+ MCP 服务器
  • 解决 3+ 配置问题

Week 2: 实战应用

  • 用 MCP 完成 10+ 实际任务
  • 创建 3+ 工作流 Skills
  • 优化配置和性能

Week 3: 高级主题

  • 学习性能优化
  • 实施安全最佳实践
  • 探索企业集成

Week 4: 知识分享

  • 撰写内部文档
  • 指导团队成员
  • 贡献社区(可选)

🏆 结语

恭喜你完成了 Module 3: MCP 深度解析

你现在已经掌握了:

MCP 的核心概念 - 架构、传输、原语 ✅ 配置和使用 - 远程和本地服务器 ✅ 实战技能 - 三个递进式案例 ✅ 高级技巧 - 性能、安全、团队协作 ✅ 问题解决 - 三级调试方法论

MCP 是 Claude Code 生态的核心能力之一。 它让 AI 从孤立的对话工具变成了真正连接你整个工作环境的智能助手。

记住关键原则:

🎯 从简单开始 - 先用一个远程服务器 ⚡ 按需扩展 - 只添加真正需要的工具 🔒 安全第一 - 最小权限、环境变量、审计 👥 团队协作 - .mcp.json + .env.example + 文档 🛠️ 持续优化 - 监控、调试、改进

下一站:Module 4

在下一个模块中,我们将学习:

  • 高级工作流设计
  • Claude Code 插件开发
  • AI 辅助架构设计
  • 企业级部署策略

MCP 为这些高级主题奠定了基础。你对 MCP 的深入理解将使后续学习更加顺畅。


💬 反馈和支持

遇到问题?

  • 重新阅读相关章节
  • 查看 FAQ
  • 搜索社区讨论
  • 提问到 GitHub Discussions

想要贡献?

  • 分享你的 MCP 配置
  • 报告文档错误
  • 提议新示例
  • 创建社区教程

保持学习:

  • 关注 Anthropic 官方博客
  • 订阅 MCP 更新
  • 参与社区讨论
  • 实践、实践、再实践

🚀 最后的建议: MCP 的真正价值在于使用。不要只是收集服务器配置 —— 找到一个真实的问题,用 MCP 解决它。每解决一个问题,你都会发现 MCP 的新可能性。开始使用,持续优化,享受自动化的力量!


Happy Coding with Claude + MCP! 🎉

基于 MIT 许可证发布。内容版权归作者所有。