Testing a server without an agent
Testing a server without an agent is the practice of exercising an MCP server through its protocol interface using controlled requests, before any language model or agent is involved. It verifies that tools, resources, prompts, schemas, responses, errors, and side effects behave correctly as server code, not as model behaviour.
The problem is that an agent is a poor diagnostic instrument. It may select the wrong tool, supply strange arguments, retry a call, ignore part of a response, or explain away an error. If the first test of an MCP server is through a model-driven client, a failing run does not clearly tell you whether the server is broken, the schema is misleading, or the model simply made a bad choice.
Direct testing treats the MCP server like any other protocol-speaking service. Start it locally, connect with a simple client, inspector, or test harness, ask it to list its capabilities, then invoke tools and read resources with known inputs. The test asserts on the structured result, returned text, error shape, and any side effect such as file access. Because the request is exact, the observed response can be attributed to the server.
This does not prove the full agent experience will work. It deliberately removes planning, prompt interpretation, tool selection, and conversational context, so it cannot catch failures caused by a model misunderstanding your tool descriptions. The trade-off is narrower coverage in exchange for cleaner evidence. It also costs some setup: you need fixtures, repeatable inputs, and assertions for both success and failure paths.
Engineers meet this in practice while building or changing MCP servers. Before attaching Claude, an IDE agent, or another LLM client, they run direct checks for invalid schemas, missing required arguments, unsafe paths, malformed errors, and incorrect JSON or text responses. Once those pass, remaining failures are easier to classify as client integration, prompt design, or model behaviour rather than ordinary server defects.
Common questions
- Why not just test through the agent users will actually use?
- Because the agent adds nondeterminism and ambiguity. A bad result might come from your server, the tool description, the model's planning, or the client integration. Direct tests remove the model from the loop, so you can first establish that the server contract itself behaves correctly under known requests.
- What should a direct MCP server test check?
- Check that the server starts, advertises the expected tools, resources, and prompts, accepts valid arguments, rejects invalid ones predictably, returns the expected structured data or text, and produces safe side effects. Failure cases matter as much as happy paths, especially malformed inputs, missing required fields, and unsafe filesystem or network targets.
- Does passing direct tests mean the MCP server is ready for agents?
- It means the server is much less likely to be the source of basic failures. It does not guarantee that an agent will choose the right tool, provide good arguments, or interpret the result correctly. After direct tests pass, agent testing is still needed, but it is testing model and integration behaviour on a sounder base.
- Is this different from ordinary API testing?
- The principle is the same: test the service contract before testing a higher-level client. The MCP-specific parts are the capabilities being exposed, such as tools, resources, and prompts, and the structured protocol responses an agent will consume. Commonly, the misunderstanding is thinking the model is required to make the server test realistic.