aaihubhub
← 文章库
Claude Code 小白进阶课：从第一次对话到可靠协作 · 第 11 课 / 共 20 课 ↗ AI 教程

11｜MCP：连接外部数据、工具与服务

通过服务器配置和调用示例理解 MCP 的能力与风险。

kimi
LESSON BRIEFING11 / 20

通过服务器配置和调用示例理解 MCP 的能力与风险。

模型判断像安检员观察，Hook 像金属探测门：规则明确、每次都会触发。适合拦截密钥、危险命令和未格式化文件，不适合替代所有人工判断。

本课交付物

实现一个只读 Hook，在写入前检查目标是否位于允许目录，并记录不含敏感数据的审计信息；分别测试允许与拒绝路径。

概览

MCP 是 Claude Code 访问外部工具、服务和 API 的标准协议。你可以把 GitHub、数据库、文件系统、聊天系统等都接到 Claude 里。

MCP 架构

MCP 通常由三部分构成：

  1. Claude Code
  2. MCP server
  3. 外部工具或数据源

Claude 会通过 MCP 协议向 server 发起工具调用，并把结果带回当前会话。

MCP 生态

  • GitHub 集成
  • 数据库集成
  • 文件系统集成
  • 组织内部工具
  • 第三方服务

安装方式

HTTP 传输（推荐）

# Basic HTTP connection

# HTTP with authentication header

Stdio 传输（本地）

# Local Node.js server

# With environment variables

SSE 传输（已弃用）

旧版本中可能仍能见到 SSE 方式，但新配置一般优先考虑 HTTP 或 stdio。

WebSocket 传输

适用于需要实时双向通信的场景。

Windows 说明

在 Windows 上配置本地 server 时，要注意 shell、环境变量和路径写法。

OAuth 2.0 认证

对于支持 OAuth 的 MCP server，Claude 可以通过交互式流程或预配置凭据完成认证。

MCP 设置流程

  1. 确认你要接入的服务
  2. 选择 transport
  3. 配置环境变量或认证
  4. 在 Claude Code 中添加 server
  5. 验证工具是否可用

MCP 工具搜索

Claude 会根据当前上下文自动查找可用工具。

动态工具更新

当 MCP server 增加或移除工具时，Claude 可以在运行时感知变化。

MCP 提示补充（Elicitation）

有些 MCP server 会在需要用户补充信息时触发 elicitation，Claude 再把问题转给用户。

工具描述与指令上限

每个 MCP 工具都应该有清晰的描述，帮助 Claude 选择正确的工具。

把 MCP Prompts 暴露成 Slash Commands

/mcp__<server-name>__<prompt-name> [arguments]

例如：

/mcp__github__list_prs
/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug title" high

Server 去重

如果多个配置都指向同一个 server，Claude 会尽量避免重复加载。

通过 @ 提及使用 MCP 资源

你可以把某些资源当作引用对象，在 prompt 中直接提及。

MCP 作用域

MCP 配置通常有不同作用域，例如项目级和用户级。

使用项目作用域

适合把团队共享的 server 配置写进项目内。

MCP 配置管理

添加 MCP server

# Add HTTP-based server

# Add local stdio server

# List all MCP servers

# Get details on specific server

# Remove an MCP server

# Reset project-specific approval choices

# Import from Claude Desktop

可用 MCP Server 表

你可以在配置中维护一张 server 清单，记录用途、认证方式和安装命令。

实战示例

示例 1：GitHub MCP 配置

你可以用 GitHub MCP 做这些事：

  • PR 管理
  • Issue 管理
  • 仓库信息查询
  • commit 操作

环境变量展开

在配置中可以使用环境变量，让同一份配置适配不同环境。

示例 2：数据库 MCP

# Using MCP database tool:

# Results:

示例 3：多 MCP 工作流

适合日常报告、跨系统同步和自动化文档生成。

示例 4：文件系统 MCP 操作

可用于读写文件、批量整理、生成报告或导出结果。

MCP vs Memory：决策矩阵

  • Memory：适合长期规则、偏好和上下文
  • MCP：适合实时工具访问和外部数据

请求 / 响应模式

MCP 一般遵循：

  1. Claude 发起请求
  2. Server 处理
  3. 返回结构化结果

环境变量

常见环境变量包括：

  • API token
  • 数据库地址
  • 服务端口
  • 认证信息

Claude 作为 MCP Server（claude mcp serve）

# Start Claude Code as an MCP server on stdio

受管 MCP 配置（企业）

企业可通过受管设置统一分发 MCP 配置。

插件提供的 MCP Servers

插件可以把自己的 MCP server 一起打包分发。

Subagent 作用域 MCP

某些 MCP 只允许特定 subagent 使用。

MCP 输出限制

如果输出过大，可以限制 token 数或分页获取。

增大最大输出

# Increase the max output to 50,000 tokens

用代码执行解决上下文膨胀

当重复把大量数据回传给 Claude 会浪费 token 时，可以把 MCP 当作代码 API 来用，减少来回传输。

问题

  • 两个信息源都在耗 token
  • 大数据集不适合全量塞进上下文

方案

  • 用 MCP 工具做实时查询
  • 只把必要结果传给 Claude

工作方式

Claude 通过工具调用从外部系统取回需要的数据，而不是把所有数据先写进上下文。

好处

  • 更少 token 浪费
  • 更清晰的数据边界
  • 更适合大规模查询

示例：过滤大数据集

示例：循环而不做 round-trip

取舍

  • 实现复杂度更高
  • 需要维护 server
  • 但扩展性更好

MCPorter：MCP 工具组合运行时

这是更高级的工具编排思路，可以把多个 MCP 工具串成一个流程。

最佳实践

安全注意事项

应该做的

  • 只授权必要的工具
  • 优先使用最小权限
  • 检查输出是否可信

不要做的

  • 不要把高风险 token 写死在仓库里
  • 不要默认开放所有工具
  • 不要忽视网络和认证风险

配置建议

  • 给每个 server 写清楚用途
  • 用环境变量存认证信息
  • 把项目级配置版本化

性能建议

  • 避免一次性拉回过多数据
  • 优先做过滤和分页
  • 只返回 Claude 真正需要的结果

安装说明

前置条件

  • Claude Code
  • 对应的 MCP server
  • 必要的认证信息

分步设置

  1. 安装 server
  2. 设置环境变量
  3. 添加到 Claude
  4. 测试工具

特定服务的安装

不同服务会有不同的安装命令和认证方式。

故障排查

找不到 MCP Server

  • 检查是否安装
  • 检查路径
  • 检查配置是否正确

认证失败

  • 检查环境变量是否设置
  • 确认 token 权限正确
  • 重新导出变量后再试

连接超时

  • 检查网络
  • 检查 server 是否可用

MCP Server 崩溃

  • 查看 server 日志
  • 降低并发
  • 简化请求

相关概念

  • Memory 中文指南
  • Subagents 中文参考
  • Plugins 中文指南

更多资源

本站实战工作台

模型判断与确定性门禁

你可以提醒 Agent“不要提交密钥”，但提醒依赖每次判断都正确。Hook 更像机场金属探测门：在特定事件必然运行一段确定性检查。适合拦截危险命令、检查写入范围、格式化已改文件和记录脱敏审计；不适合替你判断复杂产品取舍。

先选事件，再写脚本

列出需要保护的时刻：工具执行前、工具完成后、会话结束。写入前 Hook 可以验证目标是否位于允许目录；执行后 Hook 可以对改动文件跑格式化；结束 Hook 可以提醒仍有失败测试。不要把所有逻辑塞进一个万能脚本。

PreToolUse  → 参数与路径检查 → 允许 / 拒绝并解释
PostToolUse → 读取真实结果   → 格式化 / 记录 / 提醒
Stop        → 汇总未完成项   → 正常结束 / 阻止误报完成

实现只读路径门禁

在临时仓库写一个脚本，接收目标路径，解析为规范绝对路径，确认它位于练习目录内。测试三类输入：合法子目录、使用 …/ 越界、符号链接指向外部。字符串以允许前缀开头并不等于安全，必须经过路径规范化并处理符号链接。

拒绝输出要说明规则与目标，但不要打印文件内容、令牌或完整环境。退出码必须稳定，让调用方能区分允许、拒绝和脚本故障。

失败策略决定 Hook 是否可靠

安全门禁自身崩溃时，应默认拒绝高风险动作；纯提示 Hook 失败可以告警后继续。明确 fail-open 或 fail-closed，不要让异常处理偶然决定。

还要防止递归：Hook 记录日志时不应再次触发同一个 Hook；遥测入口要排除自己的请求。加入超时，避免一个网络检查冻结所有工具。

验证四条路径

合法写入被允许，越界被拒绝，脚本错误按策略处理，日志不含敏感数据。最后暂时禁用 Hook 再执行一次，确认保护确实来自 Hook 而不是测试环境碰巧安全。

何时不要用 Hook

“是否应该发布这个设计”需要上下文与人类判断；“发布前测试必须为绿”适合确定性门禁。把模糊政策硬编码会产生大量误报，最终让团队习惯绕过 Hook。窄、快、可解释的门禁更持久。