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/

资讯详情