# Compare MCP tool schemas with a free diff checker

> Check MCP input schemas, output schemas and descriptions in the browser, then keep the complete server contract checked with mcprobe in CI.

The [free MCP schema diff checker](/mcp-schema-diff) compares two pasted MCP
tool definitions with MCP Inspect's production deterministic engine. No account
or installation is required. The comparison runs locally in a browser worker;
definitions are not uploaded, persisted, included in URLs or sent to an LLM.

## What to paste

Paste one tool object on each side, including `name` and `inputSchema`.
Optional `outputSchema`, title, description, annotations, icons and `_meta` are
compared when present. Do not paste an entire `tools/list` response, a schema
without its tool envelope, a normalized snapshot or tool invocation arguments.
Unsupported top-level fields produce an error rather than being silently dropped.

For example, start with this tool:

```json
{
  "name": "search",
  "description": "Search the issue tracker.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" },
      "limit": { "type": "integer" }
    },
    "required": ["query"]
  }
}
```

In the After tool, change `required` to `["query", "limit"]`. The checker emits
`tool.input.required.added`, BREAKING: an existing call that omits `limit` can
stop validating. Retain the previous default during a staged migration. Inspect
the [exact example definitions and findings](/examples#required-input).

## Inputs and outputs have different compatibility directions

Accepting another input enum value preserves the values existing callers send:
NON_BREAKING. Returning another output enum value can break a caller that only
handles the old values: BREAKING. Both cases are reproducible in the
[example lab](/examples). A description rewrite may be POTENTIALLY_BREAKING even
without a schema edit; this is a deterministic heuristic, not measured model behavior.

These verdicts belong to MCP Inspect's engine. The official
[MCP tools specification](https://modelcontextprotocol.io/specification/2026-07-28/server/tools)
defines the tool fields and JSON Schema contract. It does not define our severity
taxonomy. See [schema compatibility](/docs/mcp-schema-compatibility) and the
[generated rule reference](/docs/rules) for detailed policy and migration hints.

## Scope and limits

The checker compares only the two pasted tools, not an entire server. A renamed
tool can be detected, but this editor cannot establish discovery completeness,
tool removals elsewhere, server capabilities, resources, prompts, Skills or
authorization-varying catalogs. It does not validate handler behavior or prove
an agent completed its task. Editing either field clears the previous verdict.

Each definition is limited to 64 KiB, 32 nesting levels and 5,000 JSON values;
processing stops after two seconds. A limit or parsing failure produces an
error, never a passing verdict. Schema references and icon URLs are not fetched.
Unknown schema changes remain conservative. This is a compatibility checker,
not a JSON Schema validator. JavaScript and web workers are required. Use the
CLI for larger contracts, unsupported fields or browsers without workers.

## Compare from a coding agent or CI

An agent can retrieve this guide as [Markdown](/docs/mcp-schema-diff-checker.md)
and reproduce the illustrated findings through the
[example JSON index](/examples/index.json). Cite the canonical HTML page. Machine
companions provide retrieval convenience; they do not guarantee agent citations.

For your own server, install the dependency-free published CLI:

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

Select the server's actual connection when prompted. After changing and
rebuilding it, compare with the recorded baseline:

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

A breaking change exits 1; capture or execution failure exits 2. An initial
baseline is not a compatibility verdict. For two existing normalized snapshots:

```bash
npx mcprobe@0.1.1 diff before.json after.json --format json
```

This command expects snapshots, not the single tool objects in the browser
editor. Use the [CLI CI recipe](/docs/github-action) for pre-merge checks. The
standalone Action and instrumentation distribution remain previews.

The web checker includes the current hosted description-change heuristic.
Published `mcprobe@0.1.1` predates the latest conservative word-edit correction;
description verdicts can differ for small wording changes such as `open issues`
to `closed issues`. The schema examples above reproduce with the published CLI.
See [description-check limits](/docs/mcp-tool-description-changes). No new CLI
release is promised by this browser tool.

## Add history and scheduled checks

For a public HTTP MCP endpoint, [capture your server](https://app.mcprobe.dev/signup)
with email and password, then one public MCP URL. No CLI, API key, GitHub
connection or telemetry setup is needed before this first capture. The first
snapshot is a baseline; capture again to compare the next observed contract.
The hosted service adds history and scheduled monitoring. Usage queries remain
pending; a quiet tool is not proof that nobody depends on it.