MCP 最小实战用 Python 跑通 Host、Client、Server 与 stdioOKOK大家好欢迎大家来到大鹏 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、桌面助手或自建 AgentClient 位于 Host 内部负责与某一个 MCP Server 建立会话Server 暴露工具、资源或提示并处理结构化请求stdio 是本地集成常用的传输方式客户端启动子进程后通过标准输入输出交换协议消息。最容易犯的错误是把 MCP Server 当成“另一个大模型”。实际上它更像能力适配器模型决定是否需要工具Client 负责协议通信Server 执行被允许的本地或远程能力。准备可复现环境本文使用 Python 3.11 和官方 MCP Python SDK 1.28.1 完成验证。为了避免主版本变化导致示例突然失效练习时应固定依赖范围python-mvenv .venv .\.venv\Scripts\activate pipinstallmcp1.28,2官方 Python SDK 已经发布 2.x如果项目仍按 1.x API 编写明确上限比完全不锁版本更稳。升级主版本时应先阅读迁移说明、单独建分支并重新跑通初始化、工具发现和调用测试。一个文件同时放 Server 和 Client为了让调用链一眼可见先把服务器与测试客户端放在同一个文件中from__future__importannotationsimportasyncioimportsysfrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientfrommcp.server.fastmcpimportFastMCP mcpFastMCP(minimal-calculator)mcp.tool()defadd(a:int,b:int)-int:Add two integers.returnabasyncdefrun_client()-None:paramsStdioServerParameters(commandsys.executable,args[__file__,server],)asyncwithstdio_client(params)as(read_stream,write_stream):asyncwithClientSession(read_stream,write_stream)assession:awaitsession.initialize()toolsawaitsession.list_tools()resultawaitsession.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(transportstdio)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,filesys.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 SDKhttps://github.com/modelcontextprotocol/python-sdkMCP 官方文档https://modelcontextprotocol.io/
MCP 最小实战用 Python 跑通 Host、Client、Server 与 stdioOKOK大家好欢迎大家来到大鹏 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、桌面助手或自建 AgentClient 位于 Host 内部负责与某一个 MCP Server 建立会话Server 暴露工具、资源或提示并处理结构化请求stdio 是本地集成常用的传输方式客户端启动子进程后通过标准输入输出交换协议消息。最容易犯的错误是把 MCP Server 当成“另一个大模型”。实际上它更像能力适配器模型决定是否需要工具Client 负责协议通信Server 执行被允许的本地或远程能力。准备可复现环境本文使用 Python 3.11 和官方 MCP Python SDK 1.28.1 完成验证。为了避免主版本变化导致示例突然失效练习时应固定依赖范围python-mvenv .venv .\.venv\Scripts\activate pipinstallmcp1.28,2官方 Python SDK 已经发布 2.x如果项目仍按 1.x API 编写明确上限比完全不锁版本更稳。升级主版本时应先阅读迁移说明、单独建分支并重新跑通初始化、工具发现和调用测试。一个文件同时放 Server 和 Client为了让调用链一眼可见先把服务器与测试客户端放在同一个文件中from__future__importannotationsimportasyncioimportsysfrommcpimportClientSession,StdioServerParametersfrommcp.client.stdioimportstdio_clientfrommcp.server.fastmcpimportFastMCP mcpFastMCP(minimal-calculator)mcp.tool()defadd(a:int,b:int)-int:Add two integers.returnabasyncdefrun_client()-None:paramsStdioServerParameters(commandsys.executable,args[__file__,server],)asyncwithstdio_client(params)as(read_stream,write_stream):asyncwithClientSession(read_stream,write_stream)assession:awaitsession.initialize()toolsawaitsession.list_tools()resultawaitsession.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(transportstdio)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,filesys.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 SDKhttps://github.com/modelcontextprotocol/python-sdkMCP 官方文档https://modelcontextprotocol.io/
