我只写了一个 add 工具，终于把 MCP 的 Host、Client、Server 跑明白了
最近我在排查 MCP 工具调用时遇到一个很尴尬的问题：服务器能启动，Agent 却一直拿不到结果。日志越加越多，数据库、浏览器、模型和工具混在一起，最后连故障发生在哪一层都说不清。
我索性删掉所有业务代码，只保留一个 add 工具。客户端通过 stdio 启动服务器、完成初始化、发现工具，再调用 add(19, 23)，真实运行结果是 42。这个最小实验反而把 Host、Client、Server 和传输层的边界彻底讲清楚了。
如果你正在接 Claude Code、Codex、Cursor 或自建 Agent，建议先跑通这个闭环，再接数据库和浏览器。
来源与证据
- 知识依据：RuyiBookCourse 中《RAG 生产级实战》"7.1 模型上下文协议架构"，用于核对 Host、Client、Server 与传输层的职责边界。
- 实践依据：本文示例在 Python 3.11、MCP Python SDK 1.28.1 环境中实际运行，工具发现结果为
tools: ['add']，调用结果为result: 42。 - 官方资料：Model Context Protocol 官方文档 与 MCP Python SDK。
先把三个角色说清楚
MCP 采用客户端---服务器架构，但开发时经常会把 Host 和 Client 混为一谈。
- Host 是承载 AI 智能体的应用，例如 IDE、桌面助手或自建 Agent；
- Client 位于 Host 内部，负责与某一个 MCP Server 建立会话；
- Server 暴露工具、资源或提示，并处理结构化请求；
- stdio 是本地集成常用的传输方式，客户端启动子进程后，通过标准输入输出交换协议消息。
最容易犯的错误，是把 MCP Server 当成"另一个大模型"。实际上它更像能力适配器：模型决定是否需要工具，Client 负责协议通信，Server 执行被允许的本地或远程能力。
准备可复现环境
本文使用 Python 3.11 和官方 MCP Python SDK 1.28.1 完成验证。为了避免主版本变化导致示例突然失效，练习时应固定依赖范围：
bash
python -m venv .venv
.\.venv\Scripts\activate
pip install "mcp>=1.28,<2"官方 Python SDK 已经发布 2.x；如果项目仍按 1.x API 编写，明确上限比完全不锁版本更稳。升级主版本时，应先阅读迁移说明、单独建分支，并重新跑通初始化、工具发现和调用测试。
一个文件同时放 Server 和 Client
为了让调用链一眼可见，先把服务器与测试客户端放在同一个文件中：
python
from __future__ import annotations
import asyncio
import sys
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("minimal-calculator")
@mcp.tool()
def add(a: int, b: int) -> int:
"""Add two integers."""
return a + b
async def run_client() -> None:
params = StdioServerParameters(
command=sys.executable,
args=[__file__, "server"],
)
async with stdio_client(params) as (read_stream, write_stream):
async with ClientSession(read_stream, write_stream) as session:
await session.initialize()
tools = await session.list_tools()
result = await session.call_tool(
"add",
{"a": 19, "b": 23},
)
print("tools:", [tool.name for tool in tools.tools])
print("result:", result.content[0].text)
if __name__ == "__main__":
if len(sys.argv) > 1 and sys.argv[1] == "server":
mcp.run(transport="stdio")
else:
asyncio.run(run_client())运行：
bash
python mcp_demo.py本地真实输出：
text
tools: ['add']
result: 42这两行比"进程没有报错"更有价值。第一行证明 Client 已经完成初始化并发现服务器暴露的工具；第二行证明参数经过协议传入 Server，工具完成执行，结果又回到了 Client。
一次调用到底经历了什么
代码虽短，背后至少经历五步：
- Host 运行我们的测试程序；
stdio_client按参数启动 Server 子进程；ClientSession.initialize()完成会话初始化；list_tools()读取服务器能力；call_tool()发送工具名与结构化参数并接收结果。
如果省略初始化直接调用工具，问题不在 add 函数，而在会话生命周期。排错时应该沿着"进程启动---初始化---能力发现---参数校验---工具执行---结果解析"的顺序检查，不要一上来就怀疑模型。
为什么 Server 不能向 stdout 随便打印
stdio 模式把标准输出当作协议通道。Server 若执行：
python
print("server started")这段普通文本可能混入协议消息，导致 Client 无法解析。调试信息应该写入标准错误或使用 SDK 的日志能力：
python
import sys
print("server started", file=sys.stderr)这是本地 MCP 最典型的坑之一：工具逻辑完全正确，但一条调试输出破坏了传输层。
从最小工具扩展到真实项目
确认最小闭环后，再逐步增加复杂度：
- 先增加一个带边界校验的纯函数工具；
- 再接入只读文件或公开 API；
- 然后补充超时、错误类型和结构化日志；
- 最后才考虑远程 Streamable HTTP、认证、限流和部署。
每增加一层，都保留一个可以独立验证的检查点。这样出错时能判断是工具业务逻辑、协议会话还是外部基础设施，而不是在几十个组件之间盲猜。
安全边界不能交给模型猜
MCP 标准化了连接方式，不等于自动解决权限问题。真实服务器至少要明确：
- 哪些目录允许读取或写入；
- 哪些命令允许执行；
- 哪些参数需要白名单校验；
- 凭据从哪里读取，是否会进入日志；
- 远程传输如何认证、限流和审计；
- 具有副作用的工具是否需要人工批准。
工具描述是给模型看的语义提示，不是强制安全控制。真正的边界仍应落在 Server 的参数校验、操作系统权限、网络策略和审批流程中。
常见失败与定位办法
Client 一直等待
先确认 Server 是否真正启动，以及 stdout 是否被普通日志污染。再检查 Python 解释器路径和脚本参数。
能发现工具但调用失败
查看工具名和参数 Schema 是否一致。不要用字符串 "19" 代替整数 19，也不要假设 SDK 会自动修复所有类型错误。
在 IDE 中能用，换一个 Host 就失败
比较两个 Host 使用的 Server 命令、工作目录、环境变量和作用域。MCP 统一了协议，不会自动统一每台机器的运行环境。
工具越加越多，模型越容易选错
按任务启用最小工具集，使用明确、互不重叠的工具名和描述。工具数量不是能力成熟度指标，可发现、可验证、可治理才是。
验收清单
一个最小 MCP 服务至少应证明：
- Server 可以被 Client 稳定启动和关闭；
- 初始化成功；
- 工具列表中只有预期能力；
- 合法参数得到确定结果；
- 非法参数返回可解释错误；
- stdout 没有协议外内容；
- 日志和异常不包含凭据；
- 进程退出后没有遗留子进程。
总结
理解 MCP 的捷径不是先搭一套庞大的 Agent 平台，而是亲手跑通一次最小闭环。Host 承载智能体，Client 管理协议会话，Server 暴露能力，stdio 负责本地进程通信。把这四个边界看清楚，再扩展数据库、浏览器和远程服务，系统会更容易调试，也更容易守住权限边界。
参考资料：
- RuyiBookCourse《从 RAG 到 AI 智能体》"模型上下文协议架构"
- MCP 官方 Python SDK：github.com/modelcontex...
- MCP 官方文档：modelcontextprotocol.io/