搞了几年测试第一次听到“MCP测试”这个说法时我第一反应是又来个新名词换汤不换药但等我把Claude、Cursor这类工具接上MCPModel Context Protocol模型上下文协议后我发现事情没那么简单。现在Blender MCP、Unity MCP、Playwright MCP、蓝湖MCP、Mastergo MCP铺天盖地大家都忙着接入却很少有人认真回答一个问题AI在调用工具谁来保证这些调用是可靠的这篇文章就围绕“MCP测试”这件事聊聊它到底测什么、怎么搭环境、怎么写用例以及那些文档里不会写的坑。给正在做AI应用测试、准备接MCP服务、或者想转型AI测试工程师的朋友一份能直接上手的参考。1. MCP测试到底在测什么1.1 先摸清MCP的链路结构我在实际工作中发现很多人把MCP测试和普通接口测试混为一谈结果大量时间浪费在错误的断言和无效的用例上。要搞清楚MCP测试得先把MCP这条链路拆开看。MCP本质上是一个“AI模型——MCP客户端——MCP服务端——具体工具/数据源”的四层结构。模型侧现在常见的是Claude Desktop、Cursor、Trae、Cocos Creator、Unity这类宿主应用它们充当MCP HostMCP Client负责和Server建立连接、协商能力把模型侧的工具调用意图翻译成协议消息MCP Server暴露三类核心能力——工具Tool、资源Resource、提示词模板Prompt最底层才是真正干活的系统比如数据库、文件系统、浏览器、Blender、设计稿平台。所以MCP测试绝对不是单点测试而是对这条链路从内到外的逐层验证。我自己做测试规划时习惯把MCP测试拆成四个层次协议层、服务层、工具层、集成层。每个层次的关注点完全不同用的手段也完全不同。1.2 四个测试层次怎么分工我列一个我自己一直在用的分层表这样规划用例时脑子很清楚层次测什么核心关注点常用手段协议层是否符合MCP规范initialize握手、能力协商、JSON-RPC消息格式、协议版本兼容性MCP Inspector、协议抓包、SDK客户端服务层Server自身的运行状态启动/退出生命周期、超时、并发、内存泄漏、鉴权进程监控、压测脚本、日志采集工具层每个Tool的行为参数Schema、入参校验、返回格式、错误处理、边界值pytest SDK、Mock数据、Schema校验集成层真实客户端里的端到端效果自然语言触发工具、交互流程、跨应用状态一致真实Host联调、E2E脚本、人工验收协议层是地基协议不对后面全白搭。我见过太多人跳过这一层直接写工具用例结果连初始化握手都不通过工具调用自然全是无效返回。服务层则是在长跑中才能暴露问题一个MCP Server被多个客户端同时连接或者工具调用时间超过30秒很容易出现超时、端口占用、进程假死。工具层是工作量最大的地方因为一个Server里可能有几十个Tool每个Tool都相当于一个独立的小接口。集成层最贴近用户体验比如用户用自然语言让AI在Unity里创建节点、在CoCos里导出资源、在浏览器中做自动化回归这种完整流程必须放到真实产品里验证一轮。1.3 为什么不能直接照搬API测试的思路MCP测试和传统API测试最核心的区别在于“动态协商”。传统接口是request-response一对一的固定契约参数和返回值都写死在文档里测试用例可以直接照着接口文档造数据。但MCP不一样Client要先通过initialize完成握手再通过tools/list之类的通知动态发现工具列表和参数Schema。换句话说工具是“被发现”的不是“被约定”的。这要求测试用例不能把对端能力写死必须先读取能力列表再动态生成断言。另一个区别是运行方式。MCP Server可能是stdio子进程也可能是HTTP远程服务。stdio模式下测试脚本必须自己拉起子进程、管理标准输入输出流还要处理进程退出时僵死的问题远程模式下又涉及网络延迟、鉴权、跨进程状态。我常用的一个比喻是你测的不只是一个API而是一个“会说话的进程”。你得先和它建立会话它才愿意告诉你它能干什么这跟普通接口一比一调用是完全不同的心智模型。2. 工具选型测MCP需要准备哪些环境2.1 官方与社区测试工具盘点选对工具能让效率翻倍但很多人一开始就卡在工具选择上。我把自己用过的几类工具整理一下按场景来说官方MCP Inspector是目前最推荐的快速冒烟工具基于Node实现图形化界面可以直接加载本地或远程MCP Server在一块面板里看到三类能力的列表和原始JSON-RPC消息非常适合第一轮联通性验证。Python生态则用官方mcp-python-sdk里面带了client、shared等模块可以封装自己的测试客户端。TypeScript项目也可以用modelcontextprotocol/sdk。社区里还有一堆针对特定应用的服务端比如Playwright MCP用于浏览器自动化Blender MCP用于3D建模操作Unity MCP、Mastergo MCP、蓝湖MCP等这些本质上都是MCP Server测试它们还是得回到协议和服务框架上而不是被具体业务带跑。下面是工具选择的速查参考工具类型适用场景MCP Inspector可视化调试器快速冒烟、查看协议消息、手动调用工具mcp-python-sdk客户端SDK编写自动化用例、协议级断言pytest pytest-asyncio测试框架组织用例、参数化、报告输出Docker Compose环境编排管理多个Server实例、隔离依赖压测工具locust/自定义脚本压测验证并发连接、长稳表现顺带说一句MCP Inspector适合“看”但别指望靠它完成自动化回归。真正进CI的用例还是得靠SDK加pytest写出来不然每次版本更新你都要手动点一遍工具列表项目一多效率就崩了。2.2 用MCP Inspector做第一轮冒烟拿到一个MCP Server后我的第一件事是打开Inspector跑一次冒烟。操作路径很简单# 用npx直接启动Inspector npx modelcontextprotocol/inspector启动后浏览器会打开一个本地界面在连接配置里选择传输类型。本地脚本就选stdio填上启动命令比如python my_server.py远程服务就选SSE或HTTP填上endpoint地址。连接成功后你会看到三块区域Tools、Resources、Prompts这就是Server声明能力的全部入口。我习惯按三步走先在Tools里随便选一个最简单的工具填参调用看返回然后去Resources里打开一个静态资源验证URI和内容是否能正常读取最后切到消息面板看一遍完整的JSON-RPC消息流确认initialize、notifications/initialized、tools/list这些关键消息都按顺序出现了。这里有个很容易被忽略的点消息面板里能直接看到client和server之间交换的原始协议帧很多连接问题一眼就能定位是排查问题的一等功臣。冒烟通过后才进入正式用例编写阶段。如果冒烟阶段就报了协议版本不匹配或者工具Schema解析失败别浪费时间查业务逻辑先回头检查Server实现版本和SDK版本是否兼容。2.3 自动化框架怎么搭自动化测试至少需要三样东西一个基于MCP SDK的客户端封装、一个能造数据和收集报告的pytest脚手架、以及一个能管理多个Server实例的调度方式。我的建议是先用Docker Compose把Server运行环境和测试环境隔离开尤其当Server依赖本地数据库或浏览器时隔离能避免测试数据污染真实环境。框架搭好后用例结构大概是这样conftest.py里放fixture负责起Server、建临时数据库、清理环境test_client.py里封装MCP客户端连接test_tools.py里按Tool维度组织用例。下一节我用一个具体项目把这块完整跑一遍。3. 实操从零搭建一个可复现的MCP Server测试项目3.1 一个最小可测的MCP Server纸上谈兵没意思直接上一个能跑的最小例子。下面是我用来练手和带新人用的MCP Server基于FastMCP实现包含一个简单的加法工具、一个模拟查询、一个故意会出错的工具# server.py from mcp.server.fastmcp import FastMCP mcp FastMCP(demo-server) mcp.settings.host 127.0.0.1 mcp.settings.port 8000 mcp.tool() def add(a: int, b: int) - int: 计算两个整数的和 return a b mcp.tool() def get_user(user_id: str) - dict: 按ID查询用户信息 return {id: user_id, name: fuser-{user_id}, level: 1} mcp.tool() def fail_demo(message: str) - str: 一个故意制造异常的示例工具 raise RuntimeError(fboom: {message})代码里我刻意保留了一个会抛异常的fail_demo目的是验证工具调用异常时Server返回的isError标记和错误消息结构。MCP协议规定工具调用失败时返回的content块里要能表示错误状态客户端侧依赖这个状态做分支处理这个用例在真实项目中非常常见。这个Server支持两种部署方式直接运行时走stdio也可以指定SSE传输跑成远程服务。测试两种传输方式时启动命令略有区别但测试逻辑可以共用。3.2 用SDK写Client做协议级测试有了Server下一步是用官方Python SDK写一个测试客户端。这里的关键是把“连接、列工具、调用工具、断言返回”封装成可复用的函数而不是每个用例都重复一遍握手逻辑# client.py import asyncio from mcp import ClientSession, StdioServerParameters from mcp.client.stdio import stdio_client async def create_session(command: list[str], env: dict | None None): server_params StdioServerParameters( commandcommand[0], argscommand[1:], envenv ) read, write await stdio_client(server_params) async with ClientSession(read, write) as session: await session.initialize() yield session封装好后测试用例就能聚焦在业务断言上。比如验证add工具的正常路径和边界值# test_add.py import pytest from client import create_session pytest.mark.asyncio async def test_add_normal(): async for session in create_session([python, server.py]): result await session.call_tool(add, {a: 1, b: 2}) assert not result.isError # 返回的content是消息块列表需要按类型解析 text result.content[0].text assert int(text) 3这段代码看似简单其实踩过一个坑MCP的call_tool返回对象不是Int而是一个ContentBlock列表你得按text类型取出来再转成目标类型。如果直接断言result 3永远过不了。这也是为什么我前面强调MCP测试不能照搬API测试——返回结构多包了一层断言前必须做解包处理。3.3 测试用例设计的几个关键点工具层用例写了一段时间后我把设计要点归纳成下面几条基本覆盖了90%的MCP Server场景参数校验是重头。工具定义上的Schema要符合JSON Schema规范必填参数要标required数值类型要设置minimum、maximum这类约束。测试时要覆盖缺失参数、错误类型、边界值。比如add工具传{a: 1}、传{a: x, b: 2}、传超大数据这几类用例都得有。超时测试容易被忽略。真实Server里工具可能调用第三方接口耗时不稳定。我会故意在工具里加一个sleep模拟慢响应验证客户端超时设置是否生效以及超时后Server状态是否还能继续处理下一个请求。这里有个结论asyncio的超时控制和子进程的通信协程是两条线只设置外层超时不一定能中断底层stdin/stdout的读写得结合进程级清理才能避免测试卡死。错误场景必须覆盖。MCP协议里工具执行失败的规范做法是返回isErrorTrue同时content里给出错误信息。我见过不少Server抛异常后直接把堆栈塞进content而不设置isError导致客户端拿到的消息结构不符合规范模型侧容易出现奇怪行为。测试时要显式断言isError标记而不只是看有没有异常文本。并发和状态隔离同样重要。多个Client同时连接同一个Server工具之间不能互相串数据。我会用asyncio.gather跑多个并发用例验证Server在高并发下不崩、数据不串。对于有状态工具比如连接了数据库的还要验证每个会话的上下文是否隔离。4. 核心链路测试工具、资源与提示词模板4.1 工具Tool测试要点Tool是MCP里最常用、出错率最高的部分。每个Tool本质上是一次远程过程调用但它和普通RPC的区别在于工具名和描述会直接影响模型是否选择调用它。如果工具描述写得太泛或太绕AI很可能在多个工具之间选错。所以在工具测试里我还会关注描述是否清晰、参数名是否直观、是否需要把工具拆细或合并。返回格式也是高频出问题的地方。MCP协议规定的content块类型有text、image、resource等文本内容要放到text字段里结构化数据可以放到structuredContent字段但不能把自定义字段直接放在返回对象顶层否则严格客户端解析时会直接失败。我通常会给每个工具写一个“返回结构协议测试”用JSON Schema校验返回的content块是否符合预期。参数Schema校验我这里再强调一次工具定义的输入参数schema必须能被标准JSON Schema引擎解析。最容易踩的坑是type写成了integer但实际校验引擎期望的是number或者required数组里写了schema中不存在的字段名这些错误Inspector界面上往往不会报只有用严格校验器才会暴露。4.2 资源Resource与提示词Prompt测试要点Resources在MCP里用于暴露静态数据比如文档、图片、配置文件。测试Resource时重点看三件事URI是否可解析、mimeType是否与实际内容匹配、模板化URI比如users://{id}/profile是否能正确展开。模板参数丢失、内容类型声明错乱是常见毛病会导致客户端拿到资源后无法正确展示或解析。Prompts用于给模型提供现成的提示词模板测试时重点看参数注入后的消息内容是否正确、模板里的占位符是否会被意外转义。还有一点Prompt的返回结果有时候会被模型当成指令执行所以在写提示词测试用例时我会特别检查内容里有没有异常指令注入的可能。这块在AI安全里叫提示注入MCP Server只要暴露给外部模型就必须做防注入测试。4.3 跨应用场景怎么测Playwright MCP、Blender MCP这类服务MCP最常见的玩法是接进现有工具链比如用Playwright MCP做浏览器自动化测试用Blender MCP操作三维场景用Unity MCP在游戏编辑器里创建资源。测这类Server时测试脚本必须同时验证“协议的返回”和“目标应用的真实状态”两件事。拿Playwright MCP举例它的工具列表里通常有打开网页、定位元素、点击、输入、断言等能力。端到端测试的完整链路是这样用MCP客户端调browser_navigate打开一个测试页面再调browser_fill往输入框填值接着调browser_click触发提交最后调一个自动化断言工具校验页面出现了预期文案。如果只验证协议返回200级别的内容根本发现不了浏览器里页面渲染失败的问题。Blender MCP和Unity MCP这类设计工具Server有个特点主要逻辑在客户端应用内部MCP Server相当于一个翻译层。测试这类服务时要尽量隔离环境用独立工程或临时场景避免自动化脚本把正在制作的正式模型或场景改坏了。我自己的经验是先在命令行里用最小客户端验证工具能被调用再进真实编辑器做人工抽查两层都过了才算稳。5. 常见问题与排查技巧实录5.1 连接初始化失败怎么排查初始化失败是我遇到最多的问题现象通常是Failed to initialize session或者Connection closed。排查思路按顺序走第一确认Server地址和启动命令没问题本地stdio模式注意要传完整命令和参数不能只传一个脚本名第二看协议版本MCP SDK和Server用的库版本差太远时握手阶段就会失败升级到匹配版本通常能解决第三看日志stdlib模式把stderr接进测试日志能直接看到Python报错第四远程模式检查端口、鉴权、防火墙注意HTTP服务路径是否带前缀。还有一类隐蔽问题Server启动缓慢而客户端初始化有超时限制。测试用例里如果只给了2秒初始化超时而Server要加载模型权重或连数据库要5秒就会出现偶发失败。解决方案是在测试fixture里先等待Server就绪比如循环检测端口或进程日志关键字再开始正式用例。5.2 JSON Schema校验失败的排查工具Schema校验失败时最直接的现象是Inspector里工具列表加载不完整或者客户端build工具时直接抛SchemaValidationError。常见原因有三个缺少type字段、required数组引用了不存在的属性、enum值类型和属性类型不一致。还有一个python程序员容易踩的坑FastMCP根据函数签名自动生成Schema如果可选的参数没有给默认值会被误判成必填参数导致客户端拿到一个难以满足的工具定义。排查技巧是先把Server声明的原始Schema导出来单独用JSON Schema校验器验证一遍再检查生成Schema的源码逻辑。这一步能快速区分是库的生成问题还是业务代码的定义问题。5.3 工具调用返回结构不兼容这个问题在接入真实客户端如Claude、Cursor时暴露得最明显。Server侧返回了自定义结构但客户端解析不出来导致模型只能看到“工具调用失败”而没有原因。MCP协议对返回的content块类型有明确约束结构化数据要放在structuredContent里普通文本放text。我建议每个工具的返回都写一个序列化函数统一把内部数据类型转成协议允许的格式避免在工具函数里散落一堆return dict时间一长就失控。5.4 安全与权限测试注意点MCP Server一旦接上浏览器、数据库、文件系统测试就必须把安全测试拉进用例范围。我常做的几项检查工具是否实现了鉴权是否校验调用方的会话身份工具是否有幂等控制重复调用会不会产生脏数据是否存在越权路径比如某个工具只应该查自己的数据但能通过构造参数查到别人的数据有没有提示注入点外部内容被拼进Prompt后能否改变模型的执行意图。权限测试我一般做成矩阵用例不同的调用方角色、不同的参数组合逐项断言允许和拒绝的结果。以前觉得这只是安全测试工程师的事后来发现MCP的权限边界比传统API更模糊因为模型可能用各种自然语言绕来绕去触发工具如果工具自身不过硬代价是非常大的。说起来我在第一次给一个带数据库的MCP Server做回归测试时就是用pytest把几十个工具用例跑了一遍顺手把超时和幂等用例也补上了。那次最大的收获不是发现多少个bug而是总结出了一套可复用的测试模式协议握手一条用例、工具Schema一条用例、每个工具的正常路径和异常路径各一条、并发与超时各一条。这套模式后来带到新项目里新人上手也快。最后再分享一个小技巧给MCP Server做测试一定要养成把协议层消息全部留存下来的习惯。就算用例全绿留一份原始JSON-RPC消息记录出了问题翻出来对照定位速度能快好几倍。毕竟排MCP的错很多时候就是看客户端和服务端到底互相说了什么。