@mcp-contracts/cli

The mcpdiff CLI tool — capture, diff, and inspect MCP server tool schemas.

Detects breaking changes, description drift, and potential tool poisoning vectors in MCP servers.

Install

npm install -g @mcp-contracts/cli

Or run directly with npx:

npx @mcp-contracts/cli snapshot --command "node server.js" -o snapshot.mcpc.json

Global Options

--format <format>    Output format: terminal | json | markdown
--no-color           Disable colored output
-o, --output <path>  Output file path
--quiet              Suppress non-essential output
--verbose            Show detailed information

Transport Options

Most commands accept transport options to connect to a live MCP server:

--command <cmd>       Server command to run via stdio transport
--args <args...>      Arguments for the server command
--url <url>           Server URL for streamable-http or SSE transport
--sse                 Use SSE transport instead of streamable-http (requires --url)
--header <header...>  Custom HTTP headers as "Key: Value" (repeatable)
--config <path>       Path to mcp.json config file
--server <name>       Server name from config file
--env <pairs...>      Environment variables as KEY=VALUE pairs

Exactly one of --command, --url, or --config must be specified.

Commands

mcpdiff snapshot

Connects to an MCP server and captures its tool/resource/prompt interface as a .mcpc.json file.

# Via stdio transport
mcpdiff snapshot --command "node server.js" -o snapshot.mcpc.json

# Via HTTP transport
mcpdiff snapshot --url http://localhost:3000/mcp -o snapshot.mcpc.json

# Via SSE transport with custom headers
mcpdiff snapshot --url http://localhost:3000/sse --sse --header "Authorization: Bearer token" -o snapshot.mcpc.json

# From an mcp.json config file
mcpdiff snapshot --config ./mcp.json --server my-server -o snapshot.mcpc.json

mcpdiff diff

Compares two snapshots and classifies every change as breaking, warning, or safe.

mcpdiff diff before.mcpc.json after.mcpc.json

# Diff a baseline against a live server
mcpdiff diff baseline.mcpc.json --live --command "node server.js"

# Fail CI on warnings too
mcpdiff diff before.mcpc.json after.mcpc.json --fail-on warning

# Output as JSON
mcpdiff diff before.mcpc.json after.mcpc.json --format json

# Send results to a webhook
mcpdiff diff before.mcpc.json after.mcpc.json --webhook https://example.com/hook

Options:

--live               Diff baseline against a live server instead of a file
--severity <level>   Minimum severity to display: safe | warning | breaking (default: "safe")
--fail-on <level>    Exit code 1 threshold: safe | warning | breaking (default: "breaking")
--webhook <url>      POST diff results to a webhook URL

Exit codes: 0 = no breaking changes, 1 = breaking changes detected, 2 = error.

mcpdiff baseline

Manage contract baselines — capture and verify snapshots against a committed baseline.

# Capture a baseline (default: contracts/baseline.mcpc.json)
mcpdiff baseline update --command "node server.js"

# Write to a custom path
mcpdiff -o custom/path.mcpc.json baseline update --command "node server.js"

# Verify the server still matches the baseline
mcpdiff baseline verify --command "node server.js"
mcpdiff baseline verify --baseline custom/path.mcpc.json --url http://localhost:3000/mcp

mcpdiff ci

All-in-one CI command: captures a snapshot, diffs against a baseline, outputs the report, and sets the exit code. Auto-detects CI environments (GitHub Actions, GitLab CI, CircleCI).

mcpdiff ci --baseline contracts/baseline.mcpc.json --command "node server.js"

# Fail on warnings too
mcpdiff ci --baseline contracts/baseline.mcpc.json --command "node server.js" --fail-on warning

# Only show breaking changes
mcpdiff ci --baseline contracts/baseline.mcpc.json --command "node server.js" --severity breaking

# Send results to a webhook
mcpdiff ci --baseline contracts/baseline.mcpc.json --command "node server.js" --webhook https://example.com/hook

Options:

--baseline <path>    Path to baseline snapshot (required)
--fail-on <level>    Severity threshold for exit code 1 (default: "breaking")
--severity <level>   Minimum severity to display (default: "safe")
--webhook <url>      POST diff results to a webhook URL

mcpdiff watch

Watch for file changes and re-diff against a baseline on every change. Useful during development.

mcpdiff watch --baseline contracts/baseline.mcpc.json --command "node server.js"

# Watch specific paths with custom debounce
mcpdiff watch --baseline contracts/baseline.mcpc.json --command "node server.js" \
  --watch-paths src lib --debounce 1000

# Send diffs to a webhook on each cycle
mcpdiff watch --baseline contracts/baseline.mcpc.json --command "node server.js" \
  --webhook https://example.com/hook

Options:

--baseline <path>         Path to baseline snapshot (required)
--watch-paths <paths...>  Paths to watch for changes (default: ["."])
--debounce <ms>           Debounce interval in milliseconds (default: 500)
--severity <level>        Minimum severity to display (default: "safe")
--fail-on <level>         Severity threshold (default: "breaking")
--webhook <url>           POST diffs on each cycle
--clear                   Clear screen between diffs (auto-enabled if stdout is TTY)

mcpdiff inspect

Summarizes a snapshot file.

mcpdiff inspect snapshot.mcpc.json
mcpdiff inspect snapshot.mcpc.json --tools
mcpdiff inspect snapshot.mcpc.json --schema create_contact

CI Integration

name: MCP Contract Check
on: [pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @mcp-contracts/cli
      - run: mcpdiff ci --baseline contracts/baseline.mcpc.json --command "node dist/index.js"

mcp-contracts is an open-source project (MIT license). It's community tooling for the MCP ecosystem, not affiliated with Anthropic or the MCP project. Contributions and feedback are welcome.

License

MIT