# MCP server testing: contract checks and evals

> Test MCP tool behavior, detect breaking contract changes before merge, and evaluate agent tool selection with the right evidence for each question.

Testing an MCP server needs three kinds of evidence: whether a tool works,
whether its advertised contract remains compatible, and whether an agent chooses
and uses it correctly. MCP Inspect compares contracts across versions; the
official MCP Inspector, integration tests and agent evaluations cover different
questions. A successful tool call alone cannot establish backward compatibility.

## Which MCP server test do I need?

| Question                                               | Evidence to collect                                                 | Workflow                                                                                                      |
| ------------------------------------------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Can a client connect, discover a tool and call it?     | The request, response and protocol exchange                         | Use the [official MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) and integration tests. |
| Can an existing caller still use the changed contract? | Before/after schemas, descriptions and capabilities                 | Compare snapshots with mcprobe or try the [free schema diff checker](/mcp-schema-diff).                       |
| Does the handler return the right business result?     | Assertions against controlled fixtures and dependencies             | Run your server's functional tests; discovery does not execute handlers.                                      |
| Does an agent pick the intended tool?                  | Task outcomes and tool-selection traces under controlled conditions | Run agent evaluations, especially after [description changes](/docs/mcp-tool-description-changes).            |
| Did a third-party server change after my last review?  | Two observed contracts and their capture times                      | [Schedule hosted captures](/docs/monitor-mcp-server-changes) and review the diff.                             |

The official Inspector documentation describes an interactive debugging client
with tool calls and protocol inspection. MCP Inspect is a separate product,
with the npm CLI named **mcprobe**. These workflows can be used together.

## Reproduce a breaking change without a server or account

An existing `search` call can omit `limit`. If the next version requires that
argument, the handler might still work for a new test that supplies it, while
the old caller stops validating. MCP Inspect reports
`tool.input.required.added` as BREAKING.

Open the [free checker](/mcp-schema-diff) and select the required-input example,
or download the same illustrative snapshots and run the published CLI:

```bash
curl --fail --output before.json https://mcprobe.dev/examples/required-input/before.json
curl --fail --output after.json https://mcprobe.dev/examples/required-input/after.json
npx --yes mcprobe@0.1.1 diff before.json after.json
```

Expect one BREAKING finding for `.limit` and exit code 1 under the default
policy. That exit reports the intentional compatibility failure in this example.

Node 22 or newer is required. The snapshots and findings come from the
[example lab](/examples#required-input), where you can inspect both contracts
and download the engine's result. They are illustrative contracts, not customer
data. The browser checker only analyzes pasted tools; a full snapshot includes
the other advertised server entities.

## Check your own MCP server before merging

Install the published CLI in your server repository:

```bash
npm install --save-dev --save-exact mcprobe@0.1.1
npx mcprobe init --snapshot
```

Review the generated `.mcp-inspect.yml` and baseline before editing the server.
After the change, rebuild the server and check the current contract against the
recorded baseline:

```bash
npx mcprobe check --baseline-file .mcp-inspect/surface.json
```

The CLI captures the advertised surface without invoking tools. Breaking changes
fail the default policy; a connection or capture failure is an error, not a clean
comparison. Commit the configuration and baseline, then use the
[pinned CLI workflow in GitHub Actions](/docs/github-action) for pull requests.
The standalone Action and `init --workflow` shortcut remain previews.

The published 0.1.1 bundle predates the hosted engine's latest conservative prose
correction. Use the same engine version when comparing verdicts and retain
tool-selection evaluations alongside description heuristics. See the
[checker guide](/docs/mcp-schema-diff-checker) for scope and version limits.

## Monitor a public MCP endpoint

For hosted history, [create a free account](https://app.mcprobe.dev/signup) with
email and password, then add one public MCP URL. The first successful capture
is a baseline. Capture again to compare the next observed contract, or configure
scheduled checks. A monitor observes changes after they reach that endpoint;
the local CI check is the pre-merge gate.

Discovery covers what the server advertises to that caller. Authorization can
change the visible catalog. A snapshot does not prove every possible client saw
the same tools, validate handler output or establish agent success. Unknown
schema changes receive conservative findings. Read the
[compatibility rules](/docs/rules) and [privacy boundaries](/docs/privacy) before
interpreting a verdict.

Reviewed October 14, 2026. [About MCP Inspect and its maintainer](/docs/about).