Testing MCP clients against a Model Context Protocol server
A Model Context Protocol client has two kinds of failure to handle, and confusing them is the common bug: a tool that ran and failed, which the model should see and reason about, and a JSON-RPC error, which the client itself must handle. The MCP Test Server produces both on request, together with the session, schema, resource and authentication behaviour an MCP client meets in practice, so a client or agent can be tested against a known server rather than a moving one.
Real endpoints from the catalog — every request above is served, and every status code shown is one that endpoint actually returns.
How to practise it
Run initialize and assert the negotiated protocol version, the server capabilities and that the response carries an Mcp-Session-Id header.
List the tools, call add, and assert that both the text content and the structuredContent match the tool's declared output schema.
Call fail with mode "tool" and with mode "protocol" and check your client passes the first to the model and handles the second itself.
Call a tool with an argument of the wrong type and assert the JSON-RPC -32602 error reaches the user as a clear message.
Connect to the secure endpoint without a token, read the 401 and its WWW-Authenticate header, then retry with the documented test token.
Pagination testing — Practise page-number and cursor pagination, and the edge cases that break clients: the last partial page, an out-of-range page, and a total count that disagrees with what you collected.
Rate limit testing — Trigger a real 429 with Retry-After and X-RateLimit headers, and verify your client backs off instead of retrying straight into the limit.
Idempotency key testing — Send the same write twice with an Idempotency-Key and confirm the operation happens once — the mechanism that stops a network retry becoming a duplicate charge.
ETag and If-Match testing — Provoke a 412 Precondition Failed by writing with a stale ETag — the check that stops two clients silently overwriting each other.
Webhook signature testing — Register a callback, trigger a delivery, verify its HMAC signature, and confirm a tampered payload is rejected.
OAuth and JWT testing — Run real client-credentials, authorization-code and device-code flows, then test what your client does when the token expires mid-session.
Negative testing — Provoke 400, 401, 403, 404, 409, 418, 422, 429, 500 and 503 deliberately, and check your client handles each one differently.
Async job testing — Start a long-running job, follow the 202 and its Location header, and poll to completion — including the failure and timeout paths.
LLM API testing — Test code that calls a language model — reassemble streamed answers, detect a dropped stream, honour Retry-After and complete a tool-call round trip — without a real key.