How to Test an MCP Server Before Release
Go beyond a successful handshake to test discovery, schemas, authorization, isolation, failures, and real clients.
Short answer
Test protocol negotiation and discovery first, then every tool's schema, authorization, tenant boundary, success behavior, failure semantics, and side effects. Finish with a compatibility matrix using real client implementations and an independently verified result.
Key takeaways
- A successful initialize or discovery call proves very little.
- Authorization and tenant isolation need negative tests.
- Tool schemas and errors must work in real clients, not only curl.
Signs this is the problem
Start by confirming the symptom before changing prompts, models, or infrastructure.
- Testing stops after tools/list returns names.
- Scopes are checked on discovery but not again on tool execution.
- The server passes a custom client but fails common hosts.
Step-by-step approach
- 1
Test transport and discovery
Verify supported protocol versions, content types, request independence or session rules, and deterministic tool discovery.
- 2
Validate every tool
Exercise schemas, required fields, bounds, structured results, errors, cancellation, and idempotency where relevant.
- 3
Attack the boundary
Try missing, expired, wrong-audience, and wrong-scope credentials plus cross-tenant identifiers.
- 4
Run real clients
Record client versions and prove discovery, invocation, errors, and final outcomes across the supported matrix.
What to measure
| Metric | What it measures | How to use it |
|---|---|---|
| Contract pass rate | Protocol and tool-schema cases passing for each advertised capability. | Block release on any advertised contract failure. |
| Authorization isolation | Negative tests that correctly return no unauthorized data or action. | Treat one cross-tenant escape as critical. |
| Client compatibility | Supported client and version pairs completing representative tasks. | Publish the tested boundary rather than claiming universal support. |
Common mistakes
- Treating proprietary tool endpoints as standard MCP.
- Testing with administrator credentials only.
- Forwarding inbound access tokens to downstream services.
Practical checklist
- Test transport and discovery: Verify supported protocol versions, content types, request independence or session rules, and deterministic tool discovery.
- Validate every tool: Exercise schemas, required fields, bounds, structured results, errors, cancellation, and idempotency where relevant.
- Attack the boundary: Try missing, expired, wrong-audience, and wrong-scope credentials plus cross-tenant identifiers.
- Run real clients: Record client versions and prove discovery, invocation, errors, and final outcomes across the supported matrix.
Frequently asked questions
What should I do first?
Verify supported protocol versions, content types, request independence or session rules, and deterministic tool discovery
How should the result be measured?
Protocol and tool-schema cases passing for each advertised capability. Block release on any advertised contract failure.
When is the change ready to ship?
Ship only after the protected cases pass, the primary metric clears its agreed boundary, and the team reviews the remaining failure modes instead of relying on one aggregate score.