中文译本。原文见同目录 README.md

第 16 课：MCP 深潜 —— 把 Agent 连接到外部世界

引言

在 第 14 课 中，我们从高层介绍了 MCP（Model Context Protocol）与 A2A。本课专门深入 MCP——底层如何工作、何时真正带来价值、何时更简单的做法更好，以及如何思考安全。

我们也会触及 AI 工程社区里争论最多的问题之一：何时该用 MCP server，何时让 Agent 直接用 CLI 工具就够了？

ELI5：把 MCP 想成带安全功能的插线板

笔记本可以直接插墙上插座，在家没问题。但在办公室有 50 台设备时，你会想要带浪涌保护、独立开关和断路器的插线板。MCP 就是那块插线板——在 Agent 与所用工具之间加一层管理。你是否需要这层，取决于工具有多少、谁在用，以及你需要多少控制。

核心要点： MCP 是连接 Agent 与外部工具和数据的强大协议，但在成本与复杂度上有真实取舍。搞清何时 MCP 增值、何时更简单做法更好，是 Agent 构建者的关键技能。

MCP Architecture Deep Dive

Watch a request flow through the MCP stack. Toggle transport type and explore cost tradeoffs.

Cost Comparison: CLI vs MCP
CLI Approach
tokens per session
MCP Approach
tokens per session
Verdict
CLI
MCP

MCP 架构 —— 实际如何工作

MCP 采用 client-server 架构，有三个角色：

三个角色

+------------------+     +------------------+     +------------------+
|                  |     |                  |     |                  |
|   MCP Host       |     |   MCP Client     |     |   MCP Server     |
|   (Your app)     |---->|   (Protocol      |---->|   (Tool          |
|                  |     |    handler)       |     |    provider)     |
|                  |     |                  |     |                  |
+------------------+     +------------------+     +------------------+
  • Host（宿主） —— Agent 运行所在的应用（Claude Desktop、IDE、你的自定义应用）。它创建并管理 MCP client。
  • Client（客户端） —— 处理协议通信。与单个 MCP server 维持 1:1 连接。负责能力协商与消息路由。
  • Server（服务端） —— 向 client 暴露 tools、resources 与 prompts。每个 server 通常封装一个具体服务（数据库、API、文件系统）。

通信

所有消息使用 JSON-RPC 2.0。协议支持两种传输机制：

传输 适用场景 工作方式
stdio 本地工具 Server 作为子进程运行，经 stdin/stdout 通信。简单、快、无网络开销。
Streamable HTTP 远程工具 单一 HTTP 端点、双向通信。支持 serverless 部署（Lambda、Cloud Functions）。

注意：原始的 SSE（Server-Sent Events）传输在 2025 年 3 月的规范修订中已弃用。SSE 是单向的，需要两个端点。Streamable HTTP 用单端点、双向设计取而代之。

MCP 原语（primitives）

MCP server 可暴露三类能力：

原语 是什么 谁控制 示例
Tools Agent 可调用的函数 由模型决定何时使用 query_database、send_email、create_file
Resources Agent 可读的数据 由应用或用户选择 数据库 schema、文件内容、API 文档
Prompts 可复用的提示模板 由用户触发 「总结这个代码库」「Review 这个 PR」

实践中，Tools 是远最常用的原语。绝大多数 MCP client 支持 Tools，而 Resources 与 Prompts 的采用率明显更低。

MCP vs CLI 之争

这是当前 AI 工程里讨论最活跃的话题之一。核心问题：若 AI Agent 能跑 shell 命令，为什么还需要 MCP？

支持 CLI 的理由

许多 MCP server 只是对已有优秀 CLI 的薄封装。GitHub MCP Server 重实现了 gh 已有能力。Docker MCP Server 封装 docker 命令。Kubernetes MCP Server 封装 kubectl。

LLM 已经知道怎么用这些 CLI。它们在数百万页 man page、Stack Overflow 回答和 GitHub 仓库上训练过。Agent 用 gh pr list 时，用的是已有知识。用 MCP server 时，需要先把 tool schema 载入上下文窗口。

数字很刺眼：

指标 CLI 做法 MCP 做法
Token 成本（简单查询） ~1,400 tokens ~44,000 tokens（约 32 倍）
初始化成本 近乎为零 schema 加载可达 50,000+ tokens
可靠性（基准测试） 100% 72%
所需设置 无（工具通常已安装） 安装并配置 MCP server

Token 成本差来自 MCP 需要把完整 tool schema（名称、描述、参数类型、返回类型）载入上下文。一个带 106 个工具的数据库 MCP server 仅初始化就消耗 54,600 tokens——真正干活之前。

支持 MCP 的理由

让 MCP「贵」的那些属性，恰恰也让它可治理：

安全与认证。 CLI 工具以用户的环境权限运行。若 Agent 能执行 rm -rf /，它一旦决定就会去做。MCP 提供权限边界。规范要求基于 HTTP 的 server 使用带 PKCE 的 OAuth 2.1，带来标准化认证、token 轮换与吊销。

多用户环境。 Agent 代表「你」行动时，CLI 的环境权限够用。当 Agent 代表他人行动——读客户的 repo、写他们的 Jira、发他们的 Slack——你需要按用户认证、作用域权限与审计追踪。MCP 为此提供框架。

工具发现。 MCP server 通过 schema 宣告能力。Agent 可在运行时发现可用工具，无需事先硬编码。工具会变、不同用户可用不同工具时，这一点很重要。

结构化 I/O。 MCP tools 有类型化输入输出。CLI 输出是非结构化文本，Agent 必须解析。对简单工具这没问题；对带嵌套 JSON 的复杂 API，结构化输出更可靠。

何时用哪种

场景 推荐做法 原因
开发者本地工作 CLI 零设置，Agent 已懂工具，最便宜
知名工具（git、docker、kubectl、jq） CLI LLM 训练数据强，解析可靠
单用户 Agent CLI 环境权限可接受
多用户 / 多租户 MCP 需要按用户认证与作用域权限
有审计要求的企业 MCP 需要结构化日志与访问控制
高频、窄工具集 MCP schema 成本可被多次调用摊薄
工具面广、偶尔使用 CLI 避免为很少用的工具付 schema 成本
无 CLI 的内部自定义 API MCP 没有现成 CLI 可借力
频繁变化的工具 MCP 动态发现自动应对变更

实务答案

多数生产系统两者都用。例如 Claude Code 既有直接 CLI 访问的 Bash tool，也支持 MCP server。决策按集成逐项做，而不是一刀切。

合理默认：先从 CLI 开始。碰到 MCP 能解决的具体限制时再加 MCP——通常是认证、多租户或结构化工具发现。

mcp2cli：弥合差距

有个有趣的工具叫 mcp2cli，能在运行时把任意 MCP server 转成 CLI。Agent 不必预先加载全部 tool schema，只在需要时查 --list 与 --help。基准测试显示可减少 96–99% token，同时保留底层 MCP 的结构化 API。

MCP 安全 —— 可能出什么问题

MCP 引入了新的攻击面。OWASP Foundation 发布了 MCP Top 10 安全风险列表。对 Agent 构建者最重要的包括：

1. Tool poisoning（工具投毒）

恶意或被攻破的 MCP server 可返回被操控的结果。若 Agent 不验证就信任工具输出，可能被诱导做出有害动作。

缓解： 校验工具输出。关键决策用多源交叉。实现输出过滤。

2. Tool shadowing（工具影子 / 同名混淆）

恶意工具模仿合法工具。若 Agent 能访问两个名字相似的工具——例如可信 server 的 query_database 与不可信的 query_db——可能用错。

缓解： 控制 Agent 可连接的 MCP server。审查工具名与描述。对工具访问使用白名单。

3. Excessive permissions（权限过大）

MCP 没有原生细粒度作用域限制。数据库 MCP server 可能同时暴露读写。Agent 若只需读，仍可能写。

缓解： 构建或使用只暴露所需操作的 MCP server。实现服务端访问控制。在 MCP server 前用 API 网关（如 Apigee）做细粒度权限管理。

4. Context window bloat（上下文膨胀）

太多 MCP 工具会降低 Agent 表现。每个 tool 定义都消耗上下文 token。带 100+ 工具的 server 可能在真正工作开始前就占掉大量上下文。

缓解： 每 server 工具数保持合理（20 以下）。用多个专精 server，而不是一个大杂烩。考虑懒加载 tool schema。

5. Secret exposure（密钥暴露）

对 5,200 个开源 MCP server 的分析发现，超过一半依赖长期静态 API key。只有约 8.5% 使用 OAuth 等现代认证。

缓解： 使用短时、有作用域的凭证。把密钥放在 secret manager（如 Google Cloud Secret Manager），不要放环境变量或配置文件。定期轮换凭证。

MCP 部署安全清单

  • 审计 Agent 连接了哪些 MCP server
  • 审查 tool schema 是否权限过宽
  • 远程 MCP server 使用 OAuth 2.1
  • 密钥放 secret manager，不要放 env vars
  • 行动前校验并清洗工具输出
  • 限制每 server 的工具数量
  • 记录所有工具调用以便审计
  • 用对抗输入测试（tool poisoning、经工具结果的 prompt injection）
  • 企业 MCP 部署使用 API 网关
  • 尽可能在沙箱环境运行 MCP server

Google Cloud 上的 MCP

Google Cloud 为 MCP 提供多个集成点：

ADK 与 MCP

Google 的 Agent Development Kit（ADK）内置支持 MCP tools。你可以连接任意 MCP server，并在 ADK Agent 中使用其工具。

在 ADK 中配置 MCP tools 的细节，见 ADK MCP Tools 文档。

用 Apigee 做 MCP 网关

对企业部署，Apigee 可作为 MCP 的 API / Agent 网关，提供：

  • 限流与配额管理
  • 认证与授权策略
  • 分析与监控
  • 工具注册与发现
  • 跨多个 MCP server 的流量管理

当许多团队都在部署 MCP server、需要集中治理时特别有用。

Model Armor

Model Armor 可过滤并校验经 MCP 工具调用流动的输入输出，加强对 prompt injection 以及经工具交互的数据外泄的防护。

构建 MCP server —— 关键决策

若决定为自己的服务构建 MCP server，关键决策包括：

传输选择

问题 stdio Streamable HTTP
Server 是否与 Agent 同机本地？ 是 均可
是否需要远程访问？ 否 是
是否需要 serverless 部署？ 否 是
延迟是否关键？ 是 相对次要

工具粒度

偏好细粒度工具，而不是粗粒度：

  • 好：get_user_by_id、list_users、create_user、update_user_email
  • 差：manage_users（一个靠 mode 参数包办一切的工具）

细粒度工具给 LLM 更清晰的选择，结果更好。但总数要可控——每 server 5–20 个工具是合理区间。

命名与描述

工具名与描述是 LLM 决定用哪个工具的主要依据。花时间写清楚：

  • 名称应描述动作：search_documents_by_topic，而不是 search
  • 描述应说明何时用、返回什么、重要约束
  • 参数描述应包含类型、合法范围与示例
  • 错误信息应帮助 LLM 恢复：「User not found. Try searching by email instead of ID.」

输出设计

保持工具输出简洁。输出会进入 Agent 上下文窗口，大响应会吃掉预算。

  • 只返回 Agent 做下一步决策所需内容
  • 对大结果集分页
  • 摘要，而不是倾倒原始数据
  • 用结构化格式（JSON）便于机器解析

汇总 —— 决策树

决定如何把 Agent 接到外部服务时：

Do you need to connect to an external service?
|
+-- Is there a well-known CLI for it? (git, docker, aws, gcloud, kubectl)
|   |
|   +-- Yes: Does the agent need multi-user auth or audit trails?
|   |   |
|   |   +-- No: Use the CLI directly
|   |   +-- Yes: Use MCP with OAuth
|   |
|   +-- No: Continue below
|
+-- Is there an existing MCP server for it?
|   |
|   +-- Yes: Is it actively maintained and from a trusted source?
|   |   |
|   |   +-- Yes: Use the MCP server
|   |   +-- No: Consider building your own or using CLI/API directly
|   |
|   +-- No: Continue below
|
+-- Does the service have a REST API?
    |
    +-- Yes: Build an MCP server or use ADK OpenAPI tools
    +-- No: Build a custom function tool or MCP server

关键要点

  • MCP 提供带 schema、认证与发现的结构化工具集成——但有 token 成本
  • 对知名开发者工具，CLI 往往更便宜、更可靠
  • 决策按集成逐项做，不是一刀切——多数生产 Agent 同时用 MCP 与 CLI
  • 默认从 CLI 起步；需要认证、多租户或工具发现时再加 MCP
  • MCP 安全需要主动关注——审计 server、限制权限、校验输出
  • 在 Google Cloud 上，ADK 原生支持 MCP，Apigee 可作企业 MCP 网关
  • 保持 MCP server 聚焦：每 server 5–20 个描述清楚的工具、简洁输出、清晰错误信息

延伸阅读

上一课：AGENTS.md | 下一课：Agent Skills ->