MCP

三层原语：不是命名，是控制权

背景与原理

MCP server 能暴露三种原语，区别不在功能而在控制轴：

• Tools = model-controlled：模型自己决定何时调用（带副作用的动作：发邮件、写文件、查数据库）。每个 tool 都消耗一次模型决策。
• Resources = application-controlled：由 client/host 决定把哪些数据塞进 context（只读上下文：文件内容、schema、文档）。模型不主动「调用」它。
• Prompts = user-controlled：用户显式触发的可复用模板，host 通常渲染成 slash command / 快捷动作。

多数人把一切都做成 Tool，于是把「读一份配置文件」也变成一次模型 tool call——既浪费一次决策，又给 tool selection 增加噪声。正确做法：只读数据 → Resource，有副作用的动作 → Tool，需要用户显式发起的工作流 → Prompt。

这条控制轴同时是信任轴：model-controlled 的 Tool 风险最高（模型可能在你没预期时触发副作用），所以 host 普遍对 Tool 加 permission gate；application-controlled 的 Resource 由 host 策展，注入什么、何时注入都可控；user-controlled 的 Prompt 由人主动发起，信任度最高。把动作错放成 Resource，等于绕过了本该有的审批；把数据错放成 Tool，等于把一个本来零风险的读操作丢进了需要审批的高风险通道。原语选择不只是 UX，是权限边界。

实战示例

# 设计 server 前先归类——贴在 server 文件顶部
# 这个能力会改变外部状态吗？      → 是 → Tool
# 它只是「让模型看到」某些数据吗？  → 是 → Resource
# 它需要用户主动点一下才发生吗？    → 是 → Prompt
# 拿不准：默认 Resource（最便宜，不污染 tool 列表）

30 行自建 Server：docstring 就是 prompt

背景与原理

官方 Python SDK 的 FastMCP 把 JSON-RPC、schema 生成、transport 全自动化，你只写三个装饰器。关键工程点和 Day 4 Tool Use 一脉相承：参数描述 > 参数名字，docstring 是给模型读的不是给人读的。type hint 会自动转成 JSON Schema，docstring 会自动变成 tool description——这两样直接决定模型选不选对、传不传对参数。

自动化的边界要心里有数：简单 type hint（str / int / list[str]）转 schema 很干净，但复杂参数光靠类型名表达不了约束（取值范围、格式、互斥关系），这些必须写进 docstring 或用 pydantic 的 Field 补描述。换句话说，schema 自动生成省的是样板代码，省不掉「把约束讲清楚给模型」这件认知工作——后者恰恰是 server 质量的分水岭。一个把每个参数的边界、单位、示例都写进描述的 server，和一个只有类型名的 server，模型调用成功率能差出一截。

实战示例

# pip install "mcp[cli]"
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def get_forecast(city: str, days: int = 3) -> str:
    """查询某城市未来天气预报。

    Args:
        city: 城市名，用英文，如 'Tokyo'
        days: 预报天数，1-7，默认 3
    """
    return _call_weather_api(city, days)

@mcp.resource("config://units")
def units() -> str:
    """当前温度单位偏好（只读，自动进 context）"""
    return "celsius"

@mcp.prompt()
def trip_brief(city: str) -> str:
    """生成出行天气简报（用户触发的模板）"""
    return f"用一句话总结 {city} 适不适合户外活动。"

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

stdio vs Streamable HTTP：transport 决定进程模型

背景与原理

MCP 用 JSON-RPC 2.0，跑在两种标准 transport 上：

• stdio：client 把 server 当子进程拉起，靠 stdin/stdout 收发、换行分隔。零网络、零认证、延迟最低，但天然 1:1——一个 client 一个进程，无法多租户。本地工具（文件、Git、本地 DB）首选。
• Streamable HTTP：远程 server 暴露单个 /mcp 端点，同时接 POST 和 GET，可选用 SSE 流式推送多条消息。可扩展、可多租户，但要自己处理 auth。注意：旧的 HTTP+SSE 双端点 transport 已在 2025-03 弃用，新项目直接用 Streamable HTTP。

两种 transport 之上跑的是同一套协议生命周期：连接后先 initialize 握手——client 和 server 交换协议版本，并协商各自支持的能力（server 声明有没有 tools / resources / prompts、支不支持 list 动态变更通知）。这意味着接同一个 server，不同 client 看到的能力面可能不同；也意味着你的 server 要老实声明 capability，否则 client 不会去拉对应的 list。能力协商是 MCP「N+M 复用」得以成立的根：client 不需要预知 server 长什么样，握手时问一次即可。

实战示例

// 本地 stdio：Claude Desktop / Claude Code 配置
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["weather_server.py"]
    }
  }
}

Context 税：MCP 最大的 production 失败模式

背景与原理

MCP 的便利有隐藏成本，且这个成本是双重的。其一是前置加载：client 通常在开场就把每个连接 server 的全部 tool schema 灌进 context，这是固定开销，与用户问什么无关。其二更隐蔽——中间结果累积：agentic loop 里每次 tool 调用的返回值都留在 context 供下一轮参考，调一次大返回的工具就把几千行 JSON 永久钉进后续每一轮的输入。两者叠加：tool 越多开场越贵，调用越多过程越胀，到长任务后期 context 塞满了早已用不上的 schema 和中间数据，既烧钱又稀释模型注意力（回到 Day 2 lost-in-the-middle）。Anthropic 2025-11 的工程博客 Code execution with MCP 给了一个反直觉的解法：把 MCP server 暴露成代码 API，让 agent 写代码去调，按需 import 用到的工具、在执行环境里处理中间数据再回传。他们报告一个原本约 150k token 的工作流降到约 2k token（约 98.7% 削减）。核心 insight：tool 目录不该常驻 context，应该 progressive disclosure（按需发现）。

实战示例

# 不做 code execution 也能立刻省的三招：
# 1. 只接当前任务需要的 server，用完即关
#    （Claude Code: 别把全部 MCP 写进全局 settings）
# 2. 一个 server 别堆几十个 tool——按职责拆，或合并同类
# 3. 大返回值在 server 端先裁剪/摘要，别让原始 JSON
#    几千行直接穿过 context