一个add工具，终于跑明白MCP的Host、Client、Server

只写一个 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。为了避免主版本变化导致示例失效，练习时最好固定依赖范围：

python -m venv .venv
.venv\Scripts\activate
pip install "mcp>=1.28,<2"

官方 Python SDK 已经发布 2.x；如果项目仍然沿用 1.x API，明确写上上限比完全不锁版本要稳妥。升级主版本时，先看迁移说明，单独建分支，然后重新跑通初始化、工具发现和调用测试。

一个文件同时放 Server 和 Client

为了让调用链更直观，把服务器和测试客户端放在同一个文件中：

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())

直接执行：

python mcp_demo.py

本地真实输出：

tools: ['add']
result: 42

这两行比“进程没有报错”更有价值。第一行证明 Client 已经完成初始化并发现了服务器暴露的工具；第二行证明参数经过协议传入 Server，工具执行完毕，结果又回到了 Client。

一次调用到底经历了什么

代码虽然短，背后至少经历了五步：

1. Host 运行测试程序；
2. stdio_client 按参数启动 Server 子进程；
3. ClientSession.initialize() 完成会话初始化；
4. list_tools() 读取服务器能力；
5. call_tool() 发送工具名与结构化参数并接收结果。

如果跳过初始化直接调用工具，问题不在 add 函数，而在会话生命周期。排错时应该沿着“进程启动—初始化—能力发现—参数校验—工具执行—结果解析”的顺序检查，而不是一上来就怀疑模型。

为什么 Server 不能向 stdout 随便打印

stdio 模式把标准输出当作协议通道。Server 如果执行：

print("server started")

这段普通文本可能混入协议消息，导致 Client 无法解析。调试信息应该写入标准错误，或者使用 SDK 的日志能力：

import sys
print("server started", file=sys.stderr)

这是本地 MCP 最典型的坑之一：工具逻辑完全正确，但一条调试输出就破坏了传输层。

从最小工具扩展到真实项目

确认最小闭环之后，再逐步增加复杂度：

• 先增加一个带边界校验的纯函数工具；
• 再接入只读文件或公开 API；
• 然后补充超时、错误类型和结构化日志；
• 最后才考虑远程 Streamable HTTP、认证、限流和部署。

每加一层，都留一个可以独立验证的检查点。这样出错时能判断是工具业务逻辑、协议会话还是外部基础设施的问题，而不是在几十个组件之间盲目猜测。

安全边界不能交给模型猜

MCP 把连接方式标准化了，但这不等于自动解决权限问题。真实服务器至少要明确：

• 哪些目录允许读取或写入；
• 哪些命令允许执行；
• 哪些参数需要白名单校验；
• 凭据从哪里读取，是否会进入日志；
• 远程传输如何认证、限流和审计；
• 具有副作用的工具是否需要人工批准。

工具描述是给模型看的语义提示，不是强制安全控制。真正的边界仍然落在 Server 的参数校验、操作系统权限、网络策略和审批流程中。

常见失败与定位办法

客户端一直等在那里

先确认 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/