You run CI on your backend. You lint your frontend. Your Docker containers have healthchecks. Everything in your stack has a testing story — except the MCP connections your agent depends on every single call.
On April 19, the MCP team published their 2026 roadmap. Four priorities: authorization, registry, rich UX primitives, and agentic capabilities. Testing, health checks, contract validation — not on the list. Not mentioned. Not planned. 😾
So you're on your own. Here's how to test MCP servers today with the tools that actually exist.
What you're working with
The MCP ecosystem has roughly 17,000 registered servers. Community audits find about half respond reliably at any given moment. Your agent connects to three servers? Statistically, one of them is flaky right now.
Testomat.io published the most comprehensive survey of MCP testing tools on April 8. Their conclusion is blunt: nothing speaks MCP natively for testing. Everything is duct tape layered on generic HTTP frameworks. No test runner understands MCP transport. No assertion library knows what a valid tool response looks like. You're building the entire testing stack from scratch for every server you depend on.
Here's the full inventory of what exists — and how to make it work.
MCP Inspector: the manual starting point
MCP Inspector is the official debugging tool — think Postman for MCP. You connect to a server, call tools manually, inspect responses.
What it gives you:
- Interactive tool discovery and invocation
- Raw JSON response inspection
- Connection diagnostics for both stdio and HTTP+SSE transports
What it doesn't:
- CI integration
- Regression detection
- Automated test suites
- Response validation against any schema
It's a screwdriver. Useful for poking around during development, worthless for preventing regressions in production. You need a test harness. 😹
Building wrapper tests (the duct-tape approach)
Most teams testing MCP today write wrapper tests — plain pytest or Jest suites that call tools directly through the MCP client SDK and assert on what comes back.
# pytest example — testing an MCP server tool
import json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
async def test_search_tool_returns_results():
server = StdioServerParameters(
command="npx",
args=["-y", "@example/mcp-search-server"]
)
async with stdio_client(server) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool(
"search",
arguments={"query": "test query", "limit": 5}
)
assert result.content is not None
assert len(result.content) > 0
assert result.content[0].type == "text"
data = json.loads(result.content[0].text)
assert "results" in data
assert len(data["results"]) <= 5
This works until the upstream server changes its response format. Which happens silently, without versioning, without changelogs — the MCP spec has no semver convention, no lockfile equivalent, no mechanism to announce breaking changes. Your assertion checks data["results"] — the server renames it to data["items"] on a Tuesday at 2 AM. Best case: your test turns red. Worst case: the field still exists but the structure inside changes, your test stays green, your agent hallucinates on malformed data, and you pay per hallucinated token.
Contract testing without contracts
The fundamental gap: MCP servers don't publish response schemas. The spec describes what a tool should do in natural language. It offers no machine-readable contract to validate against.
The workaround: generate your own.
# Step 1: Record real responses over time
from genson import SchemaBuilder
builder = SchemaBuilder()
for response in recorded_responses: # collect these from staging/dev
builder.add_object(json.loads(response))
inferred_schema = builder.to_schema()
# Save this to your repo as the "contract"
# Step 2: Validate in CI
from jsonschema import validate, ValidationError
def test_tool_response_matches_contract():
response = call_mcp_tool("search", {"query": "test"})
try:
validate(instance=response, schema=inferred_schema)
except ValidationError as e:
pytest.fail(f"Contract violation: {e.message}")
The process: record real responses from the server over a week. Infer a JSON Schema from those responses using a schema generator. Commit that schema to your repo. Validate future responses against it in CI.
It's reverse-engineered contract testing. Not elegant. But it catches silent upstream changes that would otherwise reach production undetected. When the schema breaks, your pipeline breaks — loudly, in CI, not quietly in your agent's output. 😸
Health monitoring: build it or pray
Your orchestrator pings Docker containers. Your load balancer checks /health. MCP servers offer no health endpoint — the spec defines none. A server is either responding or it isn't, and you find out when your agent's tool call hangs.
Build your own health check:
import asyncio
from datetime import datetime
async def check_mcp_health(server_params, timeout=10):
try:
async with asyncio.timeout(timeout):
async with stdio_client(server_params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
tools = await session.list_tools()
return {
"status": "healthy",
"tools_available": len(tools.tools),
"checked_at": datetime.utcnow().isoformat()
}
except (asyncio.TimeoutError, Exception) as e:
return {
"status": "unhealthy",
"error": str(e),
"checked_at": datetime.utcnow().isoformat()
}
Run this on a cron. Alert on consecutive failures. Check not just connectivity but tool list — servers add and remove tools without notice, and your agent expecting search_v2 after the server silently drops it produces the kind of failure that looks like an agent bug but isn't.
Failure injection: the part everyone skips
Your agent calls a tool. The tool times out. What happens next?
If you haven't tested this, the answer is: the model improvises. It might retry endlessly. It might hallucinate the expected response. It might apologize to the user and do nothing. You won't know until production shows you, and production charges per token for the lesson. 🙀
Wrap your MCP client to simulate failures:
import random
class ChaosProxy:
"""Wraps a real MCP session to inject failures during testing."""
def __init__(self, real_session, failure_rate=0.1, corruption_rate=0.05):
self.session = real_session
self.failure_rate = failure_rate
self.corruption_rate = corruption_rate
async def call_tool(self, name, arguments):
# Simulate timeout
if random.random() < self.failure_rate:
raise TimeoutError(f"Simulated MCP timeout on {name}")
result = await self.session.call_tool(name, arguments)
# Simulate corrupted response
if random.random() < self.corruption_rate:
return self._corrupt_response(result)
return result
def _corrupt_response(self, result):
# Return valid MCP envelope with garbage content
# Tests whether your agent handles malformed data gracefully
...
Run your agent through this proxy with a 10% failure rate. Watch how it handles timeouts, garbage data, and missing tools. Fix the breakage. Increase the rate. Repeat until your agent degrades gracefully instead of hallucinating confidently.
The complete testing stack
Here's what a tested MCP deployment looks like today — all of it hand-rolled, none of it standardized:
| Layer | Tool | What it catches |
|---|---|---|
| Manual exploration | MCP Inspector | "Does this tool exist and respond?" |
| Unit tests | pytest/Jest wrappers | Response shape, basic behavior |
| Contract tests | Inferred JSON Schema | Silent upstream format changes |
| Health monitoring | Custom cron + alerting | Server outages, tool list drift |
| Failure injection | Chaos proxy wrapper | Agent behavior under degraded conditions |
| Integration tests | End-to-end agent runs | Full pipeline regressions |
Total standardized tooling the MCP spec provides for any of this: zero. Every layer you build, you also maintain, debug, and rebuild when transport changes break your test infrastructure. 😾
The gotchas that will bite you
State pollution. MCP tools can have side effects — write data, delete records, charge money. The spec defines no mock mode. You either build a fake server for testing, run against production (dangerous), or maintain a staging environment per MCP dependency (expensive). Most teams test against production and hope. Hope is not a testing strategy.
Transport mismatch. Your tests run over stdio. Production runs over HTTP+SSE. They behave differently under load, timeout differently, fail differently. Test both transports or accept that your test environment doesn't match production.
Auth expiration. OAuth tokens expire. Your CI runs at 3 AM. The token expired at 2 AM. Your test fails, not because the server broke, but because auth did. Handle token refresh in test setup or you'll chase phantom failures for hours.
Tool list drift. Server adds a tool, removes a tool, renames a parameter — no notification, no version bump. Test tool discovery as part of your health checks. Diff the tool list against a known-good snapshot. Alert on changes.
You're dangerous now
You can test MCP servers. Not because the protocol helps you — the April 19 roadmap confirms it won't prioritize this anytime soon — but because JSON Schema validation, chaos engineering, and health monitoring are all solved problems. You can bolt them onto MCP's untested surface with regular Python and a cron job.
The setup is ugly. The maintenance is manual. The entire stack will need rebuilding when the spec eventually adds testing primitives — if it ever does.
But your agent has tested dependencies now instead of prayers. That's the difference between "it worked in the demo" and "it works in production." One of those pays your salary. The other gets you a Slack message at 2 AM from someone who trusted your agent with something important. 😼
→ MCP 2026 Roadmap (April 19, 2026) → Testomat.io — MCP Server Testing Tools
