第 3 篇《MCP Python SDK v2 实战》用不到十行代码起了一个合规的 server,第 4 篇《MCP handler 内幕:Context 与 Resolve》又把 handler 从纯函数养成带进度、带共享状态、能向用户提问的运行时参与者。但代码写得再顺,离交付还差最后一公里:模型传来的参数工具接不接得住,宿主能不能把进程稳稳拉起,改了一行代码之后怎么确认协议面没被弄坏。本篇是《MCP 协议与实现》第 5 篇、Server 开发层收官篇,把这一公里拆成测试三件套与宿主接入两段走完,按"可测性 → 三件套总览 → mcp dev 与 Inspector → 进程内测试 → 宿主接入 → 分层策略 → 实战"组织,并给第 3 篇的知识库 server 补一套完整 pytest,口径均以 mcp 2.3.0 源码与官方文档站为准(本文写作时 2026 年 11 月)。
1、协议标准化带来可测性
先回答一个容易被忽略的问题:为什么 MCP server 的测试体验比大多数网络服务好?传统服务难测,难在业务逻辑与接入方式耦合——要验证一个 HTTP 接口,要么起全套依赖环境,要么照着某家客户端的私有格式手写 mock,测试代码比业务代码还长。MCP 把这层耦合拆掉了,带来三个红利。
其一,协议统一,客户端现成。你的 server 对外的全部世界就是一个讲标准协议的客户端,而这个客户端不用自己造:官方 SDK 直接提供了 Client 类,Inspector 提供了可视化界面,真实宿主提供了最终验收环境。其二,类型即文档——第 3 篇讲过,工具名、描述、参数 schema 全部从函数签名推导,断言 schema 就等于断言接口,不存在"实现与文档各说各话"。其三,传输便宜:stdio 模式下拉起子进程即是环境,进程内更是内存直连、毫秒级往返。
第 2 篇的无状态内核还送了一份隐形福利:旧协议测试前要先走 initialize 握手铺垫会话,新内核下第一个请求就是业务请求,测试用例天然短——没有会话建立、没有状态清理,一个用例只关心一次调用。
2、测试三件套总览
验证手段按"谁来操作、回答什么问题"摆开,三件套的定位对比如下。
| 工具 | 形态 | 回答的问题 |
|---|---|---|
| mcp dev | CLI 命令 | 我的 server 在真实客户端眼里长什么样 |
| MCP Inspector | 浏览器可视化客户端 | 手动过一遍三原语、看原始报文 |
| 进程内 Client | pytest 内存直连 | 改动之后协议行为有没有回归 |
三者的关系是接力而非替代:mcp dev 是入口,它负责把 Inspector 拉起来;Inspector 是开发期的眼和手,适合探索与排错;Client 是自动化的回归网,适合固化成测试用例。Inspector 与 Client 消费的是同一套协议实现,"眼见的"与"断言的"不会各说各话——这是标准化给测试的底层保证。
3、mcp dev 与 Inspector
第 3 篇用过 uv run mcp dev server.py,本节按 2.3.0 源码把这条命令拆开(源码见 python-sdk 仓库的 mcp/cli/cli.py)。它依次做三件事:先 import 你的文件、按 mcp 名字找 server 对象——所以 if __name__ == "__main__" 守卫不能省,也支持 server.py:mymcp 后缀指定别的对象名;再把 server 的 dependencies 属性并入依赖清单;最后构造一条 uv 命令,交给 Inspector。完整链路如下。
解读:uv 命令是 uv run --with mcp==2.3.0 mcp run server.py——钉住的正是你当前运行的 SDK 版本。源码注释解释了为什么必须钉:uv run --with mcp 在全新环境里解析依赖,不钉版本会拿到最新稳定版,未必与你本地装的一致,预发布版更是永远选不中。Inspector 本体是 Node.js 应用,命令最终执行 npx @modelcontextprotocol/inspector,由它拉起 uv 子进程并在浏览器里给出操作界面——PATH 里没有 npx 会直接退出(Windows 上源码会依次找 npx.cmd)。额外依赖用 --with 包名 带上,本地开发装可编辑包用 --with-editable 目录。
Inspector 的操作流:Connect 之后 Tools、Resources、Prompts 三页对应三原语,工具页的输入表单由你的类型提示生成,填完调用即得结果;底部的报文历史能看到完整的 JSON-RPC 请求与响应。第 1、2 篇讲的三原语分工、_meta 元数据、Mcp-Method 头,都能在这里对着真实报文看一遍——它是系列理论篇的落地观察点,详见 Inspector 仓库。
4、进程内 Client 直连
Inspector 好用,但每次都要人手点,回归必须自动化。v1 时代要手工组装内存传输对(create_connected_server_and_client_session),v2 把这堆样板收口成一个 Client 类:把 server 对象直接传给它,协议调用在进程内完成,不起子进程、不占端口,定位类似 FastAPI 的 TestClient。Client 的构造目标与连接方式如下。
| 构造目标 | 连接方式 |
|---|---|
| URL 字符串 | Streamable HTTP 连远端 |
| StdioServerParameters | 拉起子进程走 stdio |
| Transport 实例 | 直接复用传入传输 |
| MCPServer 实例 | 进程内内存直连 |
也就是说同一个 Client 类覆盖了"连远程、连子进程、连自己"三种形态,写测试用最后一种。给第 3 篇的加法工具写第一个测试,代码如下。
import pytest
from mcp import Client
from server import mcp
@pytest.fixture
def anyio_backend():
return "asyncio"
@pytest.fixture
async def client():
async with Client(mcp, raise_exceptions=True) as c:
yield c
@pytest.mark.anyio
async def test_call_add(client: Client):
result = await client.call_tool("add", {"a": 1, "b": 2})
assert not result.is_error
assert result.content[0].text == "3"
逐行解读(写法与官方测试文档一致):Client 从 mcp 顶层导入,mcp.client 路径也可;Client(mcp) 传 server 对象即内存直连;async with 管理连接生命周期,fixture 里 yield 出去供各用例复用;anyio_backend fixture 声明异步后端,@pytest.mark.anyio 标记异步用例,用 trio 的话把返回值换成 "trio" 即可;call_tool(名字, 参数字典) 返回 CallToolResult,content 是内容块列表,is_error 标记成败。常用的还有 list_tools() 列工具与 read_resource(uri) 读资源,第 7 节实战都会用到。
raise_exceptions=True 值得单独讲:默认情况下工具体抛出的异常会被消毒成 "Internal server error" 结果,真实错误只在服务端日志里;开了它,异常以真实面目抛进测试——失败的用例直接指向病根。调用链与协议时代也有关联:Client 会自动识别新旧协议路径,要钉旧协议语义用 mode="legacy";call_tool 还收 progress_callback 与 input_responses 参数,正好配合第 4 篇的进度上报与 MRTR 多轮往返做客户端侧验证。
注意:
raise_exceptions=True只给测试用。生产客户端不要开——把异常细节原样递给对端,等于把内部实现泄漏给外部。
5、宿主接入两种配置
自动化测试过后是真实宿主。宿主的概念回第 1 篇:承载大模型、内含 Client 的应用。接入的本质只有一句话——告诉宿主用什么命令拉起你的子进程。两大官方宿主的接入方式对比如下。
| 宿主 | 配置载体 | 写入方式 |
|---|---|---|
| Claude Desktop | claude_desktop_config.json | mcp install 自动写或手写 |
| Claude Code | CLI 注册表 | claude mcp add 命令 |
5.1、Claude Desktop 配置
配置文件在 macOS 是 ~/Library/Application Support/Claude/claude_desktop_config.json,Windows 是 %APPDATA%\Claude\claude_desktop_config.json。SDK 提供自动写入:uv run mcp install server.py,它生成的条目长这样(以知识库 server 为例,版本号取当前 SDK)。
{
"mcpServers": {
"内部知识库": {
"command": "/usr/local/bin/uv",
"args": [
"run",
"--frozen",
"--with",
"mcp[cli]==2.3.0",
"mcp",
"run",
"/srv/kb/server.py"
]
}
}
}
解读:mcpServers 下每个键是一个 server,command 用 uv 的绝对路径,args 里的 --frozen 防止宿主拉起时改写锁文件,mcp[cli]==2.3.0 钉死版本,最后是 server 文件的绝对路径——手写配置照这个骨架来,路径一律绝对,宿主从自己的工作目录拉进程,相对路径是最常见的接入失败原因。需要环境变量时安装命令带 -v API_KEY=abc123,会记进条目的 env 字段;--name 可覆盖条目名。配置改完必须完全退出 Claude Desktop 再重开,只关窗口不够。
5.2、Claude Code 注册
Claude Code 不用碰配置文件,命令行注册(详见 Claude Code 的 MCP 文档),命令如下。
claude mcp add kb -- uv run --with "mcp[cli]" mcp run /srv/kb/server.py
解读:-- 之后是原样传给 server 的启动命令,Claude 自己的选项都在前面——比如 --env KEY=value 注环境变量、--transport stdio 显式声明传输。作用域分三档:默认 local 只在当前项目生效;--scope project 写进项目根的 .mcp.json、随版本库与团队共享;--scope user 跟随账号全局可用。验证两步:会话里跑 /mcp,看到 Connected 即通;命令行 claude mcp list、claude mcp get kb 可查健康状态,claude mcp remove kb 移除。完整的接入排查口径见宿主接入文档:动宿主配置前先把启动命令自己跑一遍——stdio server 静默等待就是正常;再查路径是否全绝对;最后回忆第 3 篇的告诫,stdout 是协议线,多余的 print 会污染报文流。
6、测试策略分层
三件套与宿主接入合起来,正好构成一张测试金字塔,分层如下。
| 层级 | 被测对象 | 跑法 |
|---|---|---|
| 单元 | handler 纯函数与工具函数 | pytest 直接调函数 |
| 集成 | 协议面行为 | Client 进程内直连 |
| 端到端 | 宿主真实链路 | Claude Code 与 Desktop 实测 |
分层的原则是成本与保真度同涨:单元层不起协议、毫秒级完成,占用例大头,专攻业务逻辑;集成层把"函数"换成"server",验证 schema 推导、错误语义、资源读取这些协议面行为——第 4 篇的 ToolError 三条归宿表,每条都值得一个集成用例;端到端最贵也最真,留给发布前与重大改动的冒烟。Inspector 的位置可以理解为"人肉集成层":探索时用它,探索出的结论固化成 Client 用例。三层齐备,uv run pytest 十秒跑完的回归网加上宿主里的一次人工确认,就是 server 的交付底气。
7、实战:知识库测试套件
最后给第 3 篇的知识库 server 补完整测试。它有两个部件:search 工具与 kb://catalog 资源,外加 tokenize 与 cosine 两个纯函数。先说测试语料:server 在 import 时全量读取 docs/ 目录,测试必须用固定语料——把三篇测试文档(部署指南、入门、常见问题)随测试代码提交,别指向生产目录。先写单元层,代码如下。
from collections import Counter
import pytest
from kb import cosine, mcp, tokenize
def test_tokenize_splits_words_and_cjk():
assert tokenize("MCP 部署指南") == ["mcp", "部", "署", "指", "南"]
def test_cosine_identical_vector_is_one():
v = Counter({"a": 1, "b": 2})
assert cosine(v, v) == pytest.approx(1.0)
解读:tokenize 对英文按单词、中文按单字切分,两个断言把这个合同钉死——它决定检索行为,改切分规则必须先改测试;cosine 同向量相似度为 1,用 pytest.approx 容忍浮点误差。这两个用例完全不走协议,改一次跑一次的成本约等于零。接着写集成层,fixture 沿用第 4 节的写法。
@pytest.mark.anyio
async def test_list_tools_exposes_search(client: Client):
result = await client.list_tools()
assert {t.name for t in result.tools} == {"search"}
@pytest.mark.anyio
async def test_search_ranks_relevant_doc_first(client: Client):
result = await client.call_tool("search", {"query": "部署步骤", "top_k": 1})
assert not result.is_error
assert "部署指南" in result.content[0].text
解读:第一个用例守住工具目录——工具名拼错、注册丢失都会在这里现形;第二个用例验证检索质量的最小合同:问"部署步骤",排第一的必须是部署指南。注意集成层断言的是协议返回的形状:.tools 列表、.content[0].text、.is_error,与真实客户端读到的一字不差。资源侧补一个用例。
@pytest.mark.anyio
async def test_catalog_lists_all_docs(client: Client):
result = await client.read_resource("kb://catalog")
text = result.contents[0].text
for name in ("部署指南.md", "入门.md", "常见问题.md"):
assert name in text
解读:read_resource 收 URI 字符串、返回内容块列表,固定语料有三篇,清单就该三篇俱全——资源注册、模板解析、内容拼装一条链全被这一条用例压住。uv run pytest 一跑,单元与集成两层全绿,这套件放进 CI 就是每次提交的协议回归网。语料涨大之后,更工程化的做法是把 DOCS 的构建从模块级挪进第 4 篇的 lifespan,届时测试语料的注入点也更干净。
8、总结
Server 开发层三篇到此收官:协议标准化给了 MCP server 天然的可测性——客户端现成、schema 可推导、无状态内核免会话铺垫;测试三件套各就其位,mcp dev 钉版本拉 Inspector 做交互调试,进程内 Client(mcp) 内存直连写成 pytest,宿主接入一条 JSON 配置加一条 claude mcp add;测试策略按单元、集成、端到端分层,成本递增、保真递增。留三道练习:
- 给第 4 篇的
import_docs写集成测试:Client 配上 elicitation 回调模拟用户选"跳过重复",断言库存与进度 - 把知识库的语料加载挪进 lifespan,为测试加一个注入临时语料目录的 fixture,全绿后对比两种结构
- 用
claude mcp add --scope project把知识库挂进团队仓库,会话里/mcp连通后问一个知识库问题,对照 Inspector 报文看真实宿主的调用差异
对于准备交付第一个 server 的读者,建议把这套分层直接抄走:pytest 套件进 CI,宿主接入留作发布检查单。本系列 Server 开发层结束,下一篇进入传输与部署——stdio 之外的 Streamable HTTP 上线、无状态内核如何铺进生产环境。

