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.

MCP client testing — request and response sequence Sequence diagram for MCP client testing: GET /auth/v1/oauth/protected-resource answers 200 OK. POST /mcp/v1/mcp answers 202 Accepted. POST /identity/v1/resource answers 400 Bad Request. POST /mcp/v1/secure/mcp answers 401 Unauthorized. Your client Fun API Playground GET /auth/v1/oauth/protected-resource 200 OK A resource protected by a token from this flow (not the s… POST /mcp/v1/mcp 202 Accepted Streamable HTTP endpoint (JSON responses): initialize, to… POST /identity/v1/resource 400 Bad Request Verify an unexpired access token POST /mcp/v1/secure/mcp 401 Unauthorized Same server behind a Bearer token (mcp-test-token) — test…
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

  1. Run initialize and assert the negotiated protocol version, the server capabilities and that the response carries an Mcp-Session-Id header.
  2. List the tools, call add, and assert that both the text content and the structuredContent match the tool's declared output schema.
  3. Call fail with mode "tool" and with mode "protocol" and check your client passes the first to the model and handles the second itself.
  4. Call a tool with an argument of the wrong type and assert the JSON-RPC -32602 error reaches the user as a clear message.
  5. Connect to the secure endpoint without a token, read the 401 and its WWW-Authenticate header, then retry with the documented test token.

APIs to try it on

Status codes involved

Other techniques

Getting started guide · All 55 mock REST APIs

Last updated