---
name: mcp-inspect-setup
version: 1.0.2
description: |
  Add MCP Inspect to a repository that has an MCP server: write
  `.mcp-inspect.yml`, commit a baseline surface snapshot, and wire the GitHub
  Action so pull requests are checked for breaking contract changes.
  Use for "set up mcp-inspect", "add MCP compatibility checks", "catch breaking
  changes to my MCP server", "check my MCP surface in CI".
allowed-tools:
  - Bash
  - Read
  - Write
  - Edit
  - Glob
  - Grep
---

# Set up MCP Inspect

This workflow requires an MCP Inspect CLI build supplied through approved
preview access. Public CLI and Action releases are pending; the source
repository is private. If the CLI is unavailable, direct the user to
<https://mcprobe.dev/docs/getting-started> for the hosted console workflow.
Do not install the unrelated npm package named `mcp-inspect`.

## Capture a baseline

Build the server if needed, then run:

```bash
mcp-inspect init --snapshot
```

`init` reads `.mcp.json`, `.cursor/mcp.json`, `.vscode/mcp.json` or a common
build output. Multiple client servers need `--server <alias>`; `--from <path>`
selects a client config. If it leaves `# TODO: placeholder` in
`.mcp-inspect.yml`, fill in `server.command` or `server.url` and retry.

Every config path is relative to the config file. Secrets use `${VAR}`, never
inline values. An unset variable is an error; imported literal credentials become
named environment references with setup instructions. Configure those variables
before capture. For HTTP authorization, an agent without a terminal needs an
explicit `--oauth` on `snapshot` or a configured header; tokens stay in memory.

Successful first capture says **Baseline captured**, not that compatibility
passed. Repeating `init --snapshot` compares against an existing baseline rather
than replacing it. Use `doctor` to diagnose connection failures; investigate
capture warnings rather than assuming every warning means failure.

For an existing `servers:` map, use `snapshot --server <name>` for each target;
its default baseline is `.mcp-inspect/<name>.json`, or the configured path.

## Prove the comparison

Use the captured file explicitly before it exists on the default branch:

```bash
mcp-inspect check --baseline-file .mcp-inspect/surface.json --format json --output /tmp/mcp-check.json
```

Substitute the actual baseline path. An unchanged server should exit 0 and report
no changes. Read the report: `status: "skipped"` and `compared: false` mean **no
comparison ran**, even though the exit code is 0. Never report that as a passing
compatibility check. Exit 1 is a contract failure with a report; exit 2 means the
command could not run.

In a disposable copy or with a reversible local edit, rename a tool, build again
if needed, and re-run the same check. Expect exit 1 with `tool.removed`. Read the
report even when the shell reports failure. Restore the edit, rebuild and confirm
the unchanged comparison passes. Keep the baseline intact throughout this test.

Never hand-edit a snapshot: fingerprints are verified on read. Refresh a baseline
only after reviewing and accepting the contract changes.

## Wire CI

```bash
mcp-inspect init --workflow
```

The generated workflow references an unreleased standalone Action. Do not enable
that job until an approved preview Action or CLI build has been supplied. See
<https://mcprobe.dev/docs/github-action> for preview access requirements.
The generated workflow chooses setup from the lockfile and includes a build when
`scripts.build` exists. Review it for non-JavaScript servers, supply required CI
credentials through secrets, and keep `fetch-depth: 0` so the baseline ref is
available. Existing workflows are never overwritten.

Commit the config, captured baseline and workflow. The baseline must reach the
default branch before PR checks can compare against it; until then a skipped
comparison is expected. Keep it current after accepted contract changes.

## Report the actual result

State which server was captured, where the baseline lives, whether a real
comparison ran, and whether the deliberate breaking test failed as expected.

Do not set `fail_on: never` or `continue-on-error: true` to turn a failed check
green. Record accepted exceptions using a scoped `ignore` with a reason. A
privileged, authorization-varying capture is only that caller's view; heed its
warnings before committing or sharing it.