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)
| 原语 | 作用 | 用途 |
|---|---|---|
| Sampling | AI 模型调用 | 服务器请求 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 管理员控制配置模板:
{
"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 对比
| 维度 | Skills | MCP |
|---|---|---|
| 定位 | 工作流程和指令 | 外部工具和数据 |
| 触发 | / 斜杠命令 | @ 引用或自动调用 |
| 内容 | Markdown 文档 | 可执行服务器程序 |
| 数据 | 静态文件 | 实时 API 调用 |
| 复杂度 | 低(写文档) | 中到高(配置服务器) |
| Token开销 | 高(全文加载) | 低(按需调用) |
| 使用场景 | 代码审查流程 | GitHub/数据库集成 |
组合使用:
Skill(定义流程) + MCP(提供工具) = 强大自动化
示例:
/production-incident (Skill)
→ 调用 @sentry (MCP)
→ 调用 @github (MCP)
→ 调用 @postgres (MCP)
→ 完整故障诊断自动化7. 快速开始三步骤
# 步骤 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
- 需要实时数据
组合示例:
# Skill: deploy-to-production
1. 使用 @github 检查 main 分支状态
2. 使用 @postgres 备份数据库
3. 使用 @sentry 确认无严重错误
4. 执行部署并更新 @linear issueQ2: 如何选择 HTTP 还是 Stdio 传输?
A: 根据服务器位置选择。
| 场景 | 推荐传输 | 原因 |
|---|---|---|
| 云服务(GitHub, Sentry) | HTTP | 原生 OAuth,防火墙友好 |
| 本地工具(数据库, 脚本) | Stdio | 零网络开销,低延迟 |
| 公司内部 API | HTTP | 支持远程访问和认证 |
经验法则:
- 如果需要 OAuth → 用 HTTP
- 如果在同一台机器 → 用 Stdio
Q3: 为什么我的 MCP 服务器连接失败?
A: 按这个清单排查:
1. 检查 Node.js 版本
node --version # 应该 >= 18.172. 验证配置语法
jq empty ~/.claude.json3. 测试命令手动执行
npx -y @modelcontextprotocol/server-postgres4. 检查环境变量
echo $DATABASE_URL5. 查看日志
claude --mcp-debug常见错误 & 解决方案:
| 错误 | 解决方案 |
|---|---|
Command not found: npx | 安装 Node.js |
JSON parse error | 使用 jq 验证语法 |
ENOENT: no such file | 使用绝对路径 |
Permission denied | chmod +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 限制
export MAX_MCP_OUTPUT_TOKENS=50000
claude方案 2:优化查询
-- ❌ 返回所有数据
SELECT * FROM users;
-- ✅ 只返回必要数据
SELECT id, email, name FROM users
WHERE status = 'active'
LIMIT 100;方案 3:使用 Skill 指导
# 查询优化规则
- 始终使用 `LIMIT`
- 只 SELECT 需要的列
- 使用 WHERE 过滤
- 聚合函数优先(COUNT, SUM)Q6: 如何在团队中共享 MCP 配置?
A: 使用项目配置 + 环境变量模板。
1. 创建 .mcp.json(提交到 Git)
{
"mcpServers": {
"project-db": {
"type": "stdio",
"command": "npx",
"args": ["-y", "postgres-server"],
"env": {"DB_URL": "${PROJECT_DB_URL}"}
}
}
}2. 创建 .env.example(提交到 Git)
PROJECT_DB_URL=postgresql://user:password@host:5432/dbname3. 团队成员设置
# 复制模板
cp .env.example .env
# 编辑个人凭据
nano .env
# 启动 Claude
claude
# 批准项目服务器
> (首次会提示,选择 "Allow")4. 添加到 .gitignore
.env
.claude/settings.local.jsonQ7: 企业 IT 阻止了我需要的 MCP 服务器怎么办?
A: 与 IT 管理员沟通。
准备材料:
业务需求: 为什么需要这个服务器?
- 例:需要 GitHub MCP 自动化 PR 创建,节省每天 2 小时
安全说明: 服务器的安全措施
- OAuth 认证
- 最小权限原则
- 审计日志
替代方案: 如果完全不允许,有什么替代方案?
- 使用 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:连接问题
claude mcp get postgres
# 查看配置和状态Level 2:认证问题
> /mcp
# 查看认证状态和权限范围Level 3:执行问题
# 启用调试模式
claude --mcp-debug
# 查看详细日志
[MCP DEBUG] Tool call: postgres_query
[MCP DEBUG] Parameters: {...}
[MCP DEBUG] Response: {...}服务器端日志:
> /mcp
# 选择服务器
# 查看 "Recent Logs"手动验证:
# 直接测试数据库连接
psql $DATABASE_URL
# 直接调用 MCP 服务器
npx -y @modelcontextprotocol/server-postgres
# 发送 JSON-RPC 请求测试Q9: MCP 的性能开销有多大?
A: MCP 显著 减少 开销。
传统工具调用 vs MCP:
| 指标 | 传统方式 | MCP 方式 | 改进 |
|---|---|---|---|
| Token 开销 | 150,000 | 2,000 | 98.7% ↓ |
| 工具列表 | 10,100 | 300-500 | 95-97% ↓ |
| 中间结果 | 50,000 | 0 | 100% ↓ |
| 响应时间 | 5-10秒 | 1-2秒 | 50-80% ↓ |
性能优化技巧:
- 使用
LIMIT限制查询结果 - 启用服务器端缓存
- 并行调用独立工具
- 监控 token 使用(
/context)
Q10: 能否创建自己的 MCP 服务器?
A: 可以!Anthropic 提供了 SDK。
快速开始:
# 安装 MCP SDK
npm install @modelcontextprotocol/sdk
# 创建服务器
npx create-mcp-server my-custom-server最简服务器示例:
// 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();配置使用:
{
"mcpServers": {
"my-server": {
"type": "stdio",
"command": "node",
"args": ["/path/to/server.js"]
}
}
}学习资源:
- 官方文档:https://modelcontextprotocol.io/docs
- GitHub 示例:https://github.com/modelcontextprotocol/servers
- 社区服务器:https://github.com/topics/mcp-server
📋 快速参考指南
指南 1:添加 MCP 服务器
远程服务器(HTTP):
# 基础
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):
# 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
模板:
{
"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:环境变量管理
设置方式:
临时(当前会话):
export DATABASE_URL="postgresql://..."
claude永久(添加到 shell 配置):
echo 'export DATABASE_URL="postgresql://..."' >> ~/.zshrc
source ~/.zshrc项目级(.env 文件):
# .env
DATABASE_URL=postgresql://...
API_KEY=secret123
# 加载
source .env # 或 export $(cat .env | xargs)
claude变量展开语法:
{
"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 服务器
- ✅ 能实现企业级安全
- ✅ 能优化服务器性能
- ✅ 能贡献社区和指导他人
📚 推荐资源
官方资源
核心文档:
- MCP 协议规范:https://modelcontextprotocol.io/docs
- Claude Code 文档:https://docs.claude.com/en/docs/claude-code
- MCP SDK (TypeScript):https://github.com/modelcontextprotocol/typescript-sdk
官方博客:
- 工程博客:https://www.anthropic.com/engineering/code-execution-with-mcp
- 产品公告:https://www.claude.com/blog/claude-code-remote-mcp
- 企业案例:https://www.anthropic.com/news/cognizant-partnership
社区资源
GitHub:
- 官方服务器库:https://github.com/modelcontextprotocol/servers
- 社区服务器:https://github.com/topics/mcp-server
- 问题讨论:https://github.com/modelcontextprotocol/servers/discussions
教程和文章:
- Codecademy 教程:https://www.codecademy.com/article/how-to-use-model-context-protocol-mcp-with-claude-step-by-step-guide-with-examples
- Simon Willison 博客:https://til.simonwillison.net/claude-code/playwright-mcp-claude-code
- Medium 实战:https://medium.com/@ashleyha/claude-code-skills-182230fdb955
视频教程:
- YouTube 搜索:"MCP Claude Code tutorial"
- Anthropic 官方频道
工具和插件
开发工具:
- MCP Inspector:调试 MCP 服务器
- MCP 配置验证器:检查配置文件
- Claude Code 插件市场
预构建服务器(前 10 名):
- GitHub - 代码管理
- Sentry - 错误监控
- PostgreSQL - 数据库查询
- Sequential Thinking - 结构化推理
- Filesystem - 文件操作
- Playwright - 浏览器自动化
- Notion - 知识管理
- Linear - 项目管理
- Slack - 团队通信(通过 Rube)
- 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! 🎉