Testing MCP servers: the basics

Testing an MCP server is checking that the server follows the Model Context Protocol specification, that its tools, resources and prompts work correctly, that it is safe to connect to, and that language models use it as intended. This article covers the basics: what makes such testing different, which levels it consists of, what the specification requires and which official tools exist.

The requirements in this article follow the specification version 2026-07-28. Basic concepts of the protocol (host, client, server, primitives, transports) are described in the article What is MCP.

Overview

Property	Value
Object of testing	MCP server: its protocol behavior, tools, resources and prompts
Levels	Tool logic, protocol conformance, integration, security, evaluation with models
Official tools	MCP Inspector (web, CLI, TUI), conformance test suite
Source of requirements	MCP specification, Security Best Practices
Specification version	2026-07-28

How it differs from API testing

An MCP server often wraps an ordinary API, and the usual API testing methods still apply to it. Three things are specific to MCP.

The consumer is a model. A person or a program calls an API according to its documentation. An MCP tool is chosen by a model, based on the tool's name, description and input schema. A tool can return correct results and still fail in use: the model does not call it when it should, calls a different tool or fills in the arguments incorrectly. The descriptions are part of the interface and are tested like code.

There is a protocol layer. Besides the business logic, the server must follow the rules of MCP: version selection, required fields of each request, capability declarations, error types, transport behavior. A client from another vendor relies on these rules, not on the server's code.

Behavior with a model is not deterministic. The same user request can lead to different sequences of tool calls in different runs and with different models. A single run of a scenario shows that it can work, not that it works reliably. This level is tested statistically, on sets of tasks and repeated runs.

Levels of testing

Level	What is checked	How
Tool logic	The code behind each tool returns correct results and correct errors	Ordinary unit tests of the handlers, without the protocol
Protocol conformance	Messages, discovery, versions, schemas and errors follow the specification	MCP Inspector, the conformance test suite
Integration	The server starts and works over its transport in a real host, with configuration and authorization	MCP Inspector, the target host, logs
Security	Tokens, access to data and state, input validation, behavior of a local server	Checks from Security Best Practices, standard security testing
Evaluation with models	Models choose the right tools, fill in arguments and complete tasks	Sets of tasks run through a model with the server connected

The lower levels are faster and cheaper, so they run on every change. Evaluation with models takes longer and costs model usage, so it runs on changes to tools and their descriptions and on a schedule.

Protocol conformance

The checks below follow directly from the requirements of the specification.

Discovery and versions

Every server must implement server/discover. The response contains the supported protocol versions (supportedVersions) and the capabilities of the server (capabilities).
A request with a version the server does not support is rejected with UnsupportedProtocolVersionError (code -32022); the supported versions are listed in the data field of the error.
Every request carries io.modelcontextprotocol/protocolVersion and io.modelcontextprotocol/clientCapabilities in _meta. A request without either field is rejected with -32602 (Invalid params).
If the server needs a client capability that the request did not declare, for example elicitation, it returns MissingRequiredClientCapabilityError (code -32021) with the names of the missing capabilities.
The server declares only the capabilities it implements: a server that declares tools must answer tools/list.

Tools

The list returned by tools/list must not depend on the connection or on other requests. It may depend on the authorization of the request, for example on the scopes of the token.
Tools should be returned in a deterministic order: clients cache the list, and the order affects the prompt cache of the model.
inputSchema must be a valid JSON Schema object, not null. The default dialect is JSON Schema 2020-12. For a tool without parameters the specification recommends { "type": "object", "additionalProperties": false }.
If a tool declares outputSchema, its structured results (structuredContent) must conform to that schema.
Tool names should be 1 to 128 characters long and use only Latin letters, digits, _, - and .; names are unique within a server.

Errors

The specification separates two kinds of errors, and a test checks that each case falls into the right one:

Situation	How it is returned
Unknown tool, malformed request, server failure	JSON-RPC error (protocol error)
Invalid arguments, including values that pass the schema but fail validation in code	Tool result with `isError: true` and a text explanation
Failure of an external API, business logic error	Tool result with `isError: true`

The difference matters to the model. The host passes a tool execution error to the model, and the model can correct the call. A protocol error is usually handled by the application and does not reach the model. Before SEP-1303, implementations returned invalid arguments in different ways; the current specification returns all input validation errors as tool execution errors.

Multi Round-Trip Requests

For a server that asks the client for additional input (resultType: "input_required"):

inputRequests contains only request types that the client declared in its capabilities;
every InputRequiredResult contains inputRequests, requestState or both;
a modified or foreign requestState is rejected when it affects authorization, access to resources or business logic;
a repeated request with the answers is processed correctly by any instance of the server.

Transports

stdio: standard output contains only MCP messages. Any other output, such as logs or debug prints, breaks the protocol. Logs go to standard error.
Streamable HTTP: the server works behind a load balancer without sticky sessions, because there is no protocol session since 2026-07-28. State needed between calls is passed in explicit handles, which are checked separately for security.

Official tools

MCP Inspector

MCP Inspector is the reference developer tool for testing and debugging MCP servers. It is distributed as the npm package @modelcontextprotocol/inspector, requires Node.js 22.19.0 or newer and contains three clients:

Client	Command	Purpose
Web	`npx @modelcontextprotocol/inspector`	Graphical interface: primitives, tool calls, the JSON-RPC exchange
CLI	`npx @modelcontextprotocol/inspector --cli`	One request per run with machine-readable output, for scripts and CI
TUI	`npx @modelcontextprotocol/inspector --tui`	Interactive interface in the terminal

The server is passed as the command that starts it (stdio) or as a URL (Streamable HTTP):

# Local server over stdio
npx @modelcontextprotocol/inspector node build/index.js

# Remote server over Streamable HTTP
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

The CLI runs one request (--method) and exits with a code that tells the type of failure, so a script or a CI job can branch on it:

Code	Meaning
`0`	Success
`3`	The server requires authentication (HTTP 401 or 403)
`4`	The server is unreachable
`5`	The tool returned `isError: true` or was not found
`6`	`--strict` found an error-level problem in tool schemas

A minimal smoke test in CI: the server starts, exposes the expected tool, its schemas pass the strict check and the tool call succeeds.

set -euo pipefail

# The server starts and exposes the get_weather tool
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

# Tool schemas have no error-level problems (exit code 6 otherwise)
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/list --strict > /dev/null

# The call succeeds (exit code 5 if the result has isError: true)
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call --tool-name get_weather --tool-arg city=Boston > /dev/null

For servers that require authorization, the CLI has the --stored-auth-only flag: it uses a stored token and fails immediately with auth_required instead of opening a browser that a CI job cannot use.

Conformance test suite

The conformance test suite (repository modelcontextprotocol/conformance) checks client and server implementations against the specification. For a server it acts as a client: it sends test requests, records the responses and runs checks on them, including validation of every JSON-RPC message against the JSON schema of the specification.

# List the server scenarios
npx @modelcontextprotocol/conformance list --server

# Run all server scenarios against a server over HTTP
npx @modelcontextprotocol/conformance server --url http://localhost:3000/mcp

The results of each scenario are saved to results/server-<scenario>-<timestamp>/checks.json with the status of each check. Known failures can be recorded in a YAML file and passed with --expected-failures, so that CI fails only on new ones.

The suite is the reference point for the official SDKs: an SDK of Tier 1 must pass all conformance tests, an SDK of Tier 2 at least 80 percent. Since SEP-2484, a change to the protocol with observable behavior reaches the final status only together with a conformance scenario that covers its requirements. Comparison of contracts between versions of a server is described in the article Regression testing of an MCP server.

Security

The specification and the Security Best Practices document describe the attacks that concern MCP servers. For each of them there is a verifiable requirement:

What to check	Requirement
Tokens	The server accepts only tokens issued for it and rejects tokens with another audience. Invalid or expired tokens get HTTP 401
Token passthrough	The server does not forward the client's token to other APIs; for them it obtains its own tokens
State handles	A handle (for example, a cart or workflow identifier) is not treated as authentication. Handles are random, not sequential, bound to the user and checked on every call
Scopes	`scopes_supported` lists a minimal set; additional scopes are requested when a privileged operation is first attempted
Local server	It uses stdio, or restricts access to its HTTP endpoint with a token or IPC. A local HTTP server without protection can be reached by other processes and through DNS rebinding
Tool inputs and outputs	The server validates all inputs, enforces access control, limits the call rate and sanitizes results
Tool descriptions	Descriptions contain only the description of the tool. Text addressed to the model, hidden in a description or in data the tool returns, is a form of prompt injection

The attacks behind these requirements are described in the article MCP security, the authorization flow in the article Authorization in MCP, and prompt injection and ways to test for it in the article Prompt injection.

Evaluation with models

Protocol conformance shows that a client can work with the server. Whether a model can complete tasks with it is shown only by running the model. Anthropic describes this approach in its guide to writing tools for agents.

Tasks. A set of realistic tasks based on real data, each with a verifiable outcome: an exact answer or a check by another model. Good tasks require several tool calls.
Runs. Each task is run in a loop: the model receives the task and the tools, calls them and gets the results until it gives an answer.
Metrics. Accuracy of the answers, the time of tasks and tool calls, the number of tool calls, token consumption and tool errors.
Analysis. The transcripts show the causes. Many repeated calls point to missing pagination or filters. Frequent invalid arguments point to unclear descriptions or parameter names.
Iterations. After changes to tools or descriptions the same set is run again. Part of the tasks is kept aside to confirm that the improvement is not limited to the tasks it was tuned on.

The behavior of a model varies from run to run, so each task is run several times and the results are compared as shares of successful runs. Models and hosts also differ in how they choose tools, so the evaluation is run on the models that the users of the server work with. The method in detail is described in the article Evaluating an MCP server with models, general methods of evaluating applications built on language models in the article Testing LLM applications.

Debugging

The first step is to connect to the server with MCP Inspector and call its tools directly, without a model and a host.
A server over stdio writes logs only to standard error; the host captures this stream. For HTTP servers the logs are collected on the server side, for example with OpenTelemetry.
A host may start a stdio server with an undefined working directory and a limited set of environment variables. Paths in the configuration are absolute; the variables the server needs are set explicitly in the host configuration.
If the connection fails, the protocol version and the _meta fields are checked: server/discover shows the versions the server supports.

Terms

Term	Meaning
Protocol conformance	Correspondence of an implementation to the requirements of the specification
Conformance test suite	Official set of scenarios that checks clients and servers against the specification
MCP Inspector	Official developer tool for connecting to a server, calling its primitives and viewing messages
Protocol error	JSON-RPC error: unknown tool, malformed request, server failure. Usually does not reach the model
Tool execution error	Tool result with `isError: true`: invalid arguments, API failure, business logic error. Passed to the model
Evaluation (eval)	Run of a set of tasks through a model with the server connected, with measurable results
State handle	Identifier that a tool returns and the model passes back in later calls, instead of a protocol session
Token passthrough	Forwarding the client's token to other services; forbidden by the specification