How to Test an MCP Server Before You Ship It

A successful handshake proves very little

An MCP client reaching your endpoint is only the first test. A production-ready server also needs accurate discovery, bounded permissions, typed tool contracts, predictable failures, tenant isolation, and evidence that real clients can complete the intended workflow.

1. Verify discovery from a cold client

Start without a hardcoded endpoint or prior session. Check the published server card, protected-resource metadata when authentication is required, protocol version, transport, and documentation link. A stale card is worse than no card because it sends agents toward a dead contract.

2. Treat tool schemas as public APIs

Every tool should have a specific name, a description that says when to use it, typed inputs, bounded outputs, and explicit read/write behavior. Reject unknown fields and malformed values. Do not rely on the model to infer a hidden enum or permission rule.

3. Prove authentication and least privilege

Test anonymous discovery separately from authenticated tool calls. Verify that a token exposes only its declared organization and scopes, expired or revoked credentials fail predictably, and a read-only server has no accidental mutation path.

4. Exercise failures on purpose

• missing, expired, and wrong-scope credentials;
• unknown tools and invalid arguments;
• provider timeouts and unavailable dependencies;
• oversized results and rate limits;
• hostile Origin, Host, redirect, and routing headers.

Return stable error codes and actionable messages. Do not convert an upstream failure into a successful empty result.

5. Prove tenant isolation with real storage

Mock tests are useful for schema behavior, but organization boundaries need a database-backed test. Create records for two organizations, call the same tool with each identity, and prove that neither can enumerate or infer the other tenant’s data.

6. Test the workflow, not just tools/list

Use at least one real client to discover the server, authenticate, list tools, call the intended tool, and interpret its result. Record the client version, protocol version, server revision, scopes, and exact result.

7. Turn every escaped failure into regression coverage

When a client reveals a schema mismatch, auth ambiguity, invalid success, or result-parsing problem, preserve the interaction and add it to the release suite. Over time, the compatibility matrix becomes executable evidence rather than a marketing table.

A practical release checklist

• cold discovery succeeds;
• tool schemas are complete and reject malformed input;
• auth and scopes fail closed;
• read/write annotations match runtime behavior;
• cross-tenant reads return no data;
• rate-limit and dependency failures remain machine-readable;
• at least one supported client completes the real workflow.

See EvalGate’s MCP integration guide and machine-readable MCP contract for a concrete example.