MCP 最小实战：用 Python 跑通 Host、Client、Server 与 stdio
MCP 最小实战：用 Python 跑通 Host、Client、Server 与 stdio
OK，OK，大家好，欢迎大家来到大鹏 AI 教育，我是张大鹏。
不少 MCP 教程一开始就接数据库、浏览器、GitHub，再塞进十几个工具。结果代码看起来很热闹，真正出错时却分不清问题发生在模型、客户端、传输层，还是服务器工具。
这篇文章反过来，只做一个加法工具：服务器暴露add，客户端通过 stdio 启动服务器、完成初始化、发现工具，再调用add(19, 23)。最后的真实运行结果是42。这个例子很小，却覆盖了理解 MCP 最重要的一条调用链。
来源与证据
- 知识依据：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 完成验证。为了避免主版本变化导致示例突然失效，练习时应固定依赖范围：
python-mvenv .venv .\.venv\Scripts\activate pipinstall"mcp>=1.28,<2"官方 Python SDK 已经发布 2.x；如果项目仍按 1.x API 编写，明确上限比完全不锁版本更稳。升级主版本时，应先阅读迁移说明、单独建分支，并重新跑通初始化、工具发现和调用测试。
一个文件同时放 Server 和 Client
为了让调用链一眼可见，先把服务器与测试客户端放在同一个文件中：
from__future__importannotationsimportasyncioimportsysfrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientfrommcp.server.fastmcpimportFastMCP mcp=FastMCP("minimal-calculator")@mcp.tool()defadd(a:int,b:int)->int:"""Add two integers."""returna+basyncdefrun_client()->None:params=StdioServerParameters(command=sys.executable,args=[__file__,"server"],)asyncwithstdio_client(params)as(read_stream,write_stream):asyncwithClientSession(read_stream,write_stream)assession:awaitsession.initialize()tools=awaitsession.list_tools()result=awaitsession.call_tool("add",{"a":19,"b":23},)print("tools:",[tool.namefortoolintools.tools])print("result:",result.content[0].text)if__name__=="__main__":iflen(sys.argv)>1andsys.argv[1]=="server":mcp.run(transport="stdio")else:asyncio.run(run_client())运行：
python mcp_demo.py本地真实输出：
tools: ['add'] result: 42这两行比“进程没有报错”更有价值。第一行证明 Client 已经完成初始化并发现服务器暴露的工具；第二行证明参数经过协议传入 Server，工具完成执行，结果又回到了 Client。
一次调用到底经历了什么
代码虽短，背后至少经历五步：
- Host 运行我们的测试程序；
stdio_client按参数启动 Server 子进程；ClientSession.initialize()完成会话初始化；list_tools()读取服务器能力；call_tool()发送工具名与结构化参数并接收结果。
如果省略初始化直接调用工具，问题不在add函数，而在会话生命周期。排错时应该沿着“进程启动—初始化—能力发现—参数校验—工具执行—结果解析”的顺序检查，不要一上来就怀疑模型。
为什么 Server 不能向 stdout 随便打印
stdio 模式把标准输出当作协议通道。Server 若执行：
print("server started")这段普通文本可能混入协议消息，导致 Client 无法解析。调试信息应该写入标准错误或使用 SDK 的日志能力：
importsysprint("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：https://github.com/modelcontextprotocol/python-sdk
- MCP 官方文档：https://modelcontextprotocol.io/