MCP协议如何用于AI开发：工具暴露与上下文传递的实践

MCP协议如何用于AI开发，答案往往藏在两个动作里：把本地能力封装成模型看得懂的工具，再把调用结果按需放回上下文。这篇从 Host、Client、Server 的分工讲起，落到 stdio 与 HTTP 两种传输的取舍，给出可以直接抄用的工具定义、一段能跑的示例，以及几条常见故障的排查顺序，尽量只写能落地的部分。

三层分工：Host、Client 与 Server

协议把责任切得很干净。Host 是用户真正打开的那个 AI 应用，负责会话状态、权限确认与模型调用；Client 由 Host 创建，一个 Client 对应一条 Server 连接；Server 才是暴露 tools、resources、prompts 的那一端。

MCP协议如何用于AI开发，落点就在这条边界上：读写文件、查数据库、调内部接口的逻辑放进 Server，权限弹窗与上下文裁剪留在 Host。换模型时只改 Host，工具代码一行不动。

一个 Host 可以同时挂多个 Client，各连各的 Server，工具清单在 Host 侧汇总。这样拆的好处是某个 Server 崩了，其余能力还在，会话不必整段重开。

Server 端工具定义：把能力写成 tools

MCP协议如何用于AI开发，工具定义是最容易写坏的一环。每个 tool 要有名字、一句能让人读懂用途的描述、以及 JSON Schema 形式的入参约束。描述含糊，模型就会在错误的时机调用它，或者在缺参数时硬猜。

参数这一层常被忽略。命名用动词加名词，入参尽量扁平，必填项越少越好。返回值给结构化字段，不要拼一段自然语言，模型读字段比读散文稳。

入参里少放裸路径和裸 SQL，换成受限的枚举或句柄，越权调用的概率会低不少。

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("file-tools")

@mcp.tool()
def read_head(path: str, lines: int = 20) -> str:
    """Return the first N lines of a UTF-8 text file."""
    with open(path, encoding="utf-8") as f:
        return "".join(f.readlines()[:lines])

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

装饰器把函数签名翻成 schema，docstring 直接成为工具描述，类型注解决定字段类型。mcp.run() 的默认传输与可用参数会随 SDK 版本调整，具体写法以官方文档为准。

用 stdio 启动本地服务

stdio 传输适合本机工具：Host 拉起子进程，请求走标准输入与标准输出，不需要端口和证书。虚拟环境的激活脚本在 Windows 上位于 .venv/Scripts/ 目录，路径写错会出现命令找不到。

python -m venv .venv
source .venv/bin/activate
pip install "mcp[cli]"
python server.py

依赖装完直接运行，Server 会把能力清单交给 Client。日志一律写标准错误，标准输出留给协议帧，两者混写会破坏连接。

也可以单独把 Server 跑起来，用官方 Inspector 手工调一次工具：执行 npx @modelcontextprotocol/inspector python server.py，浏览器会打开调试面板，逐个工具填参试跑，确认入参与返回都符合预期，再接进 Host 更省时间。

客户端怎么发现并调用工具

MCP协议如何用于AI开发的调用链路其实很短：连接建立后，Client 先做一次能力协商，拿到 Server 声明的 tools 列表。列表里只有元数据，真正的调用要带上工具名与参数对象，一个请求对应一个响应。

调用结果通常包含内容数组和一个错误标记。业务失败与协议失败要分开处理：前者放回结果交给模型去解释，后者才值得中断连接。

从调用层面看，MCP协议如何用于AI开发的答案就是三件事：发现、调用、回填。工具名、描述、参数说明三者对齐，模型才愿意在正确的时机动手。

工具变多之后，按领域拆 Server 比堆在一个进程里好维护。文件类、查询类、发布类各自独立，权限也能分别收紧，出问题时的排查范围小得多。

Server 写好了，Host 从哪里读它？多数 Host 用一份 JSON 声明要启动的 Server，路径必须写绝对路径：

{
  "mcpServers": {
    "file-tools": {
      "command": "python",
      "args": ["/abs/path/server.py"]
    }
  }
}

Windows 下手写路径要用双反斜杠或统一改成正斜杠，相对路径经常在 Host 换了工作目录之后失效。

上下文与调用链：resources 与 prompts 的分工

上下文不是越多越好。resources 提供可读取的数据，由 Host 决定何时把哪一段放进提示；prompts 提供可复用模板，把常用指令骨架固化下来，减少每次重写的偏差。

多轮调用后的上下文裁剪

调用链上，一次提问可能触发多轮工具调用。每轮结果都要回填进消息历史，窗口随之膨胀，截断与摘要策略必须提前定好，否则后半程的对话会突然丢信息。

MCP协议如何用于AI开发，真正吃经验的就是这一段：哪些结果原样保留，哪些压成摘要，哪些只留一个引用让模型再取一次。

把大块文本换成句柄加摘要很常见。模型需要细节时再发一次读取请求，代价可控，也避免一次把窗口塞满导致前面的系统提示被挤掉。

传输方式怎么选

stdio 适合单机、单用户，进程生命周期跟着 Host 走，Host 退出子进程一起结束。远程场景用 Streamable HTTP：它在单个端点上同时处理请求与流式返回，2025-03-26 版规范起已取代早期的 HTTP+SSE 写法，按旧方式配远程 Server 常常在握手阶段就失败。FastMCP 里写 mcp.run(transport="streamable-http") 即可，对外通常挂在 /mcp 路径下。

stdio 这一侧没有鉴权环节，谁能起进程谁就能用全部工具，所以它只适合本机可信环境。把这类 Server 直接暴露到局域网，等于把文件读写权限一起交出去。

MCP协议如何用于AI开发，选传输前先问一句：这个 Server 是给一个人用，还是给一群人用。跨网络时把它放在内网，前面挂一层反向代理，只暴露必要路径，请求体大小与超时都显式配置。

常见故障的排查顺序

接不上先看进程有没有起来，再看握手阶段有没有返回能力清单。工具调用报参数错误，多数是 schema 与实现不一致，用最小参数复现最快。

日志混进标准输出是最隐蔽的一种。协议帧被污染之后，现象是连接随机断开而不是明确报错，把日志重定向到标准错误就能定位。

MCP协议如何用于AI开发，最后都落回几件事：边界划清、描述写准、传输选对、日志分开。工具跑通只是起点，稳定调用才算交付。