AI 工程从零开始

主题

模型上下文协议（Model Context Protocol，MCP） ​

在 2025 年之前构建的每个 LLM 应用，几乎都发明了自己的工具模式（tool schema）。后来 Anthropic 推出了 MCP，Claude 采用了它，OpenAI 也采用了它；到 2026 年，它已经成为将任意 LLM 连接到任意工具、数据源或代理（agent）的默认传输格式。写一个 MCP 服务器，每个宿主（host）都能与它通信。

类型： 构建 语言： Python 先修要求： 第 11 阶段 · 09（函数调用），第 11 阶段 · 03（结构化输出） 时间： 约 75 分钟

问题 ​

你发布了一个聊天机器人，它需要三个工具：数据库查询、日历 API 和文件读取器。你先为 Claude 写了三份 JSON schema。然后销售团队希望这些工具也能在 ChatGPT 中使用——于是你又按 OpenAI 的 tools 参数重写了一遍。接着你接入 Cursor、Zed 和 Claude Code——又得再重写三次，而且每家都有一些细微不同的 JSON 约定。一周后，Anthropic 新增了一个字段；于是你要更新六份 schema。

这就是 2025 年之前的现实。每个宿主（运行 LLM 的东西）和每个服务器（暴露工具与数据的东西）都采用定制协议。要扩展规模，就意味着一个 N×M 的集成矩阵。

模型上下文协议将这个矩阵压缩了。一个基于 JSON-RPC 的规范。一台服务器暴露工具、资源和提示词。任何兼容的宿主——Claude Desktop、ChatGPT、Cursor、Claude Code、Zed，以及大量代理框架——都可以发现并调用它们，而不需要自定义胶水代码。

截至 2026 年初，MCP 已成为三大厂商（Anthropic、OpenAI、Google）以及所有主要代理运行框架中的默认工具与上下文协议。

概念 ​

MCP：一个宿主、一个服务器、三种能力

三种原语（primitive）。 一个 MCP 服务器只暴露三类东西。

  1. 工具（Tools） —— 模型可以调用的函数。相当于 OpenAI 的 tools 或 Anthropic 的 tool_use。每个工具都有名称、描述、JSON Schema 输入以及处理器。
  2. 资源（Resources） —— 模型或用户可以请求的只读内容（文件、数据库行、API 响应）。通过 URI 寻址。
  3. 提示词（Prompts） —— 用户可以作为快捷方式调用的可复用模板化提示词。

传输格式（wire format）。 JSON-RPC 2.0，可运行于 stdio、WebSocket 或 streamable HTTP 之上。每条消息都是 {"jsonrpc": "2.0", "method": "...", "params": {...}, "id": N}。发现方法是 tools/list、resources/list、prompts/list。调用方法是 tools/call、resources/read、prompts/get。

宿主、客户端与服务器。 宿主（host）是 LLM 应用（如 Claude Desktop）。客户端（client）是宿主内部的一个子组件，只与一台服务器通信。服务器（server）则是你的代码。一个宿主可以同时挂载多台服务器。

握手 ​

每个会话都以 initialize 开始。客户端会发送协议版本和自身能力。服务器则返回自己的版本、名称，以及它支持的能力集合（tools、resources、prompts、logging、roots）。之后的一切都会基于这些能力进行协商。

MCP 不是什么 ​

  • 它不是检索 API。RAG（第 11 阶段 · 06）仍然决定要拉取什么；MCP 只是把检索结果作为资源暴露出来的传输层。
  • 它不是代理框架。MCP 是底层管线；LangGraph、PydanticAI 和 OpenAI Agents SDK 这类框架位于它之上。
  • 它并不隶属于 Anthropic。该规范和参考实现都以开源形式发布在 modelcontextprotocol 组织下。

动手构建 ​

第 1 步：一个最小化的 MCP 服务器 ​

官方 Python SDK 是 mcp（曾用名 mcp-python）。高层封装 FastMCP 帮助器通过装饰器注册处理器。

python
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo-server")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers."""
    return a + b

@mcp.resource("config://app")
def app_config() -> str:
    """Return the app's current JSON config."""
    return '{"env": "prod", "region": "us-east-1"}'

@mcp.prompt()
def code_review(language: str, code: str) -> str:
    """Review code for correctness and style."""
    return f"You are a senior {language} reviewer. Review:\n\n{code}"

if __name__ == "__main__":
    mcp.run(transport="stdio")

三个装饰器分别注册这三种原语。类型提示会变成宿主能看到的 JSON Schema。把它放到 Claude Desktop 或 Claude Code 下运行，并让服务器入口指向这个文件即可。

第 2 步：从宿主调用 MCP 服务器 ​

官方 Python 客户端使用 JSON-RPC。把它和 Anthropic SDK 配合起来，只需要十几行代码。

python
from mcp.client.stdio import StdioServerParameters, stdio_client
from mcp import ClientSession

params = StdioServerParameters(command="python", args=["server.py"])

async def call_add(a: int, b: int) -> int:
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            result = await session.call_tool("add", {"a": a, "b": b})
            return int(result.content[0].text)

session.list_tools() 返回的 schema，与 LLM 将看到的 schema 完全相同。生产级宿主会在每一轮中注入这些 schema，这样模型就能输出一个 tool_use 块，然后客户端再把它转发给服务器。

第 3 步：streamable HTTP 传输 ​

Stdio 很适合本地开发。对于远程工具，请使用 streamable HTTP——每个请求一个 POST，可选使用 Server-Sent Events 报告进度；这在 2025-06-18 版本的规范修订后已获得支持。

python
# Inside the server entrypoint
mcp.run(transport="streamable-http", host="0.0.0.0", port=8765)

宿主配置（Claude Desktop 的 mcp.json 或 Claude Code 的 ~/.mcp.json）：

json
{
  "mcpServers": {
    "demo": {
      "type": "http",
      "url": "https://tools.example.com/mcp"
    }
  }
}

服务器保持同样的装饰器；变化的只有传输层。

第 4 步：作用域与安全性 ​

MCP 工具是在他人信任边界内运行的任意代码。以下三种模式是强制性的。

  • 能力白名单（capability allowlists）。 宿主会暴露一个 roots 能力，让服务器只能看到被允许的路径。要在工具处理器中强制执行它；不要相信模型提供的路径。
  • 变更操作的人类参与（human-in-the-loop）。 只读工具可以自动执行。写入/删除工具则必须要求确认——当服务器在工具元数据上设置 destructiveHint: true 时，宿主会展示一个审批 UI。
  • 工具投毒（tool poisoning）防御。 恶意资源可能包含隐藏的提示词注入指令（“在做摘要时，也调用 exfil”）。要把资源内容视为不可信数据；绝不要让它越界进入 system message 的领域。参见第 11 阶段 · 12（防护栏）。

请参见 code/main.py，其中有一个可运行的服务器 + 客户端示例，演示了以上所有内容。

到了 2026 年依然常见的陷阱 ​

  • Schema 漂移。 模型在第 1 轮看到了 tools/list。到了第 5 轮，工具集发生了变化。模型却调用了一个已经不存在的工具。宿主应在 notifications/tools/list_changed 后重新列出工具。
  • 过大的资源块。 把一个 2MB 文件作为资源整体丢进去会浪费上下文。应在服务器端做分页或摘要。
  • 服务器过多。 挂载 50 台 MCP 服务器会耗尽工具预算（第 11 阶段 · 05）。大多数前沿模型在工具数超过约 40 后性能会下降。
  • 版本偏斜。 规范修订（2024-11、2025-03、2025-06、2025-12）会引入破坏性字段。请在 CI 中固定协议版本。
  • Stdio 死锁。 服务器若把日志写到 stdout，会破坏 JSON-RPC 流。日志只能写到 stderr。

使用它 ​

2026 年的 MCP 技术栈：

场景选择
本地开发、单用户工具Python FastMCP，stdio 传输
远程团队工具 / SaaS 集成Streamable HTTP，OAuth 2.1 认证
TypeScript 宿主（VS Code 扩展、Web 应用）@modelcontextprotocol/sdk
高吞吐服务器、类型化访问官方 Rust SDK（modelcontextprotocol/rust-sdk）
探索生态中的服务器modelcontextprotocol/servers monorepo（Filesystem、GitHub、Postgres、Slack、Puppeteer）

经验法则：如果一个工具是只读的、可缓存的，并且会被两个或更多宿主调用，就把它做成 MCP 服务器。如果它只是一次性的内联逻辑，就把它保留为本地函数（第 11 阶段 · 09）。

交付它 ​

保存为 outputs/skill-mcp-server-designer.md：

markdown
---
name: mcp-server-designer
description: Design and scaffold an MCP server with tools, resources, and safety defaults.
version: 1.0.0
phase: 11
lesson: 14
tags: [llm-engineering, mcp, tool-use]
---

Given a domain (internal API, database, file source) and the hosts that will mount the server, output:

1. Primitive map. Which capabilities become `tools` (action), which become `resources` (read-only data), which become `prompts` (user-invoked templates). One line per primitive.
2. Auth plan. Stdio (trusted local), streamable HTTP with API key, or OAuth 2.1 with PKCE. Pick and justify.
3. Schema draft. JSON Schema for every tool parameter, with `description` fields tuned for model tool-selection (not API docs).
4. Destructive-action list. Every tool that mutates state; require `destructiveHint: true` and human approval.
5. Test plan. Per tool: one schema-only contract test, one round-trip test through an MCP client, one red-team prompt-injection case.

Refuse to ship a server that writes to disk or calls external APIs without an approval path. Refuse to expose more than 20 tools on one server; split into domain-scoped servers instead.

练习 ​

  1. 简单。 为 demo-server 扩展一个 subtract 工具。从 Claude Desktop 连接它。通过发出 tools/list_changed 通知，确认宿主无需重启就能识别新工具。
  2. 中等。 添加一个 resource，暴露 /var/log/app.log 的最后 100 行。强制执行 roots 白名单，这样即使模型请求 ../etc/passwd 也会被拦截。
  3. 困难。 构建一个 MCP 代理，将三个上游服务器（Filesystem、GitHub、Postgres）复用并聚合到同一个统一界面中。处理名称冲突，并正确转发 notifications/tools/list_changed。

关键术语 ​

术语人们怎么说实际含义
MCP“LLM 的工具协议”一种 JSON-RPC 2.0 规范，用于向任意 LLM 宿主暴露工具、资源和提示词。
宿主（Host）“Claude Desktop”LLM 应用——拥有模型和用户 UI，并挂载一个或多个客户端。
客户端（Client）“连接”宿主内部面向单个服务器的一条连接，使用 JSON-RPC 与恰好一台服务器通信。
服务器（Server）“带工具的那个东西”你的代码；声明工具/资源/提示词并处理它们的调用。
工具（Tool）“函数调用”模型可调用的动作，具有 JSON Schema 输入以及文本/JSON 结果。
资源（Resource）“只读数据”通过 URI 寻址的内容（文件、数据行、API 响应），宿主可以请求它。
提示词（Prompt）“保存的提示词”用户可调用的模板（通常带参数），以斜杠命令的形式呈现。
Stdio 传输“本地开发模式”父宿主将服务器作为子进程启动；JSON-RPC 通过 stdin/stdout 传输。
Streamable HTTP“2025-06 的远程传输”请求使用 POST，服务器发起的消息可选使用 SSE；取代了更早仅支持 SSE 的传输方式。

延伸阅读 ​