# Getting started

> Capture your contract, compare a change, then protect the next pull request. Start in the hosted console, or use an approved preview CLI build.

## Start in the hosted console

MCP Inspect is a privately operated hosted product. Open
[app.mcprobe.dev/signup](https://app.mcprobe.dev/signup) and create an account
with an email address and a password of at least 12 characters. An organization
and a first project are created for you. GitHub sign-in is not offered until
its OAuth integration is configured.

After creating an account, paste the server's final public endpoint URL into
**Capture your first contract** and choose **Capture contract**. No CLI, API key
or GitHub connection is needed for hosted HTTP capture. Expand authorization only
if your server requires a header. If authorization fails, add a current header
and retry in the same screen.

Capture progress stays visible until a recorded snapshot opens your server. The
first snapshot is a baseline, not a compatibility verdict. Browse the captured
entities and input paths, then choose **Capture again** to compare the next
version. New watches check hourly and alert on breaking changes; adjust the
interval and threshold in **Settings → Watched servers**. Discovery does not
invoke tools and never sits in the server's request path.

Use the server's **Changes** view to review snapshots, compatibility findings
and migration hints. A baseline establishes history; the next distinct contract
provides a comparison. A failed capture is shown as a failure, not an unchanged
contract. Watched servers cannot target private or loopback addresses.

## Local and CI preview access

The CLI, instrumentation and standalone Action are not publicly released yet.
Use only builds supplied through approved preview access. The source repository
is private; cloning it is not a public installation path. The npm package named
`mcp-inspect` belongs to another project and must not be used for this product.

Once the preview CLI is installed, the local workflow below works without an
account. Hosted usage queries, nightly rollups, account email delivery and paid
checkout remain pending. Self-host deployments are not supported.

## 1. Capture your baseline

From your server repository, with its normal build and environment ready:

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

This imports an existing MCP configuration, connects to the server and saves
`.mcp-inspect/surface.json`. It discovers the advertised surface without calling
any tools. A successful capture is your **baseline**, not a compatibility verdict.

If several servers are configured, select the one you maintain with
`--server <name>`. If none is found, fill in the generated config's `server`
command or URL, then run `mcp-inspect snapshot`. Use
`mcp-inspect doctor` if the connection fails; it is a troubleshooting step,
not a required extra capture.

Already have a configuration? Run `mcp-inspect snapshot` before editing the
server. Already have two snapshots? Go straight to:

```bash
mcp-inspect diff before.json after.json
```

## 2. Compare your change locally

Make your intended server change and rebuild it if needed. Keep the initial
snapshot unchanged, then run:

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

The check captures the current server and compares it with your saved baseline.
It does not overwrite that baseline. Read the changed entity, compatibility
severity and migration hint together.

### Example report

This is an illustrative report; your own result depends on your server changes.

```text
BREAKING (1)
  ! search
    `limit` changed from optional to required.
    → Accept calls that omit it for at least one release, applying the
      previous default, then require it.

POTENTIALLY_BREAKING (1)
  ~ create_issue
    Description changed. Agents may alter tool-selection behavior.
    → Review the wording and re-run your tool-selection evaluations.
```

A breaking finding exits 1 by default. A potentially breaking finding remains
visible but only blocks when you choose `fail_on: POTENTIALLY_BREAKING`.
Prose classification is a deterministic heuristic, not a measurement of model
behavior. [Understand severities](/docs/severities).

An unchanged contract produces no changes. That is a completed comparison.
**“Comparison skipped — baseline needed” means no comparison happened**, even
though the command exits 0 so a setup PR can merge.

## 3. Protect the next pull request

The standalone GitHub Action release is pending. The generated workflow currently
references an unreleased Action location. Do not enable it as a working check yet.
See [GitHub Action details](/docs/github-action) for preview access requirements.

After a verified Action release, generate its workflow:

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

Review the generated `.github/workflows/mcp-compatibility.yml`, including your
build command and any environment secrets the server needs. Commit it together
with `.mcp-inspect.yml` and the baseline snapshot. Merge the baseline into your
PR base branch before expecting CI to compare against it.

The first setup PR may report a skipped comparison. The next PR should show an
actual comparison; the Action exposes `compared=true` when one ran.

After reviewing an intentional contract change, run `mcp-inspect snapshot`
and commit the updated snapshot with the change. CI reads its baseline from the
base branch, so it can still check that PR while the updated snapshot becomes
the baseline after merge. [GitHub Action details](/docs/github-action).

Do not hand-edit snapshots: their content and fingerprints are verified on read.

## 4. Add shared history when you need it

The local check is fully usable without signup. To keep deployment history,
open the hosted console and follow **Add your first server**: select a project,
create an API key and run the supplied upload command. Setup is complete when
the console receives the snapshot. A successful CLI exit alone does not confirm
upload, because hosted failures are warnings.

In `.mcp-inspect.yml`, set `endpoint: https://api.mcprobe.dev` explicitly when
using a source revision with the previous hosted default. The console is at
[app.mcprobe.dev](https://app.mcprobe.dev). Usage queries and nightly rollups
are pending the deployment's analytics read credential; account email delivery,
GitHub sign-in and paid checkout are not configured yet.

[Telemetry](/docs/telemetry) is a separate, optional step. You can capture,
compare, gate pull requests and keep shared history without installing the SDK.