MCP tool catalog drift monitoring

Agents bind to live tools/list catalogs — not OpenAPI files in your repo. DriftGuard snapshots MCP tool schemas on a schedule and classifies what changed before your agents hit runtime errors.

What breaks in production (and why CI often misses it)

Most agent incidents we see are not mysterious model failures. They are contract mismatches: the MCP server your agent called yesterday is not the same catalog today.

Typical failure modes:

  • Tool removed or renamed — your harness still calls search_documents but the server now exposes search_docs.
  • inputSchema tightened — a field that was optional becomes required; the LLM still emits the old shape and validation fails at execution time.
  • Description-only edits — schema unchanged but tool metadata shifts enough to confuse routing (classified as suspicious on Pro+ for review).

CI diff tools catch your deploy against a schema you pinned at build time. They do not catch a vendor or internal MCP service that drifts after you shipped. Scheduled MCP watches close that gap.

MCP watch vs CI lockfile — complementary, not either/or

QuestionCI lockfile / compare_jsonHosted MCP watch
When does it run? On every PR / deploy On your plan interval (e.g. every 15 minutes on Pro)
What does it compare? Git-pinned baseline vs current probe Last good snapshot vs latest tools/list
Best for MCP servers you build and version MCP servers you depend on (Stripe, internal platform, SaaS MCP)
Alerts CI check failure Slack, PagerDuty, webhook with classified diff

If you own the server repo, start with a lockfile in CI. If agents call a URL you do not control on every release, add a watch.

What an MCP watch snapshots

An MCP watch polls your server endpoint and normalizes the response into a canonical tool catalog — tool names, inputSchema shapes, and metadata DriftGuard uses for structural diff.

  • First successful check becomes the baseline.
  • Each later check diffs against that baseline (or your promoted baseline after review).
  • Results surface in the console, GET /api/watches/:id/status, and MCP tools like get_watch_status.

See also: Watches · Change records.

How changes are classified

DriftGuard uses the same severity model as API schema diff — tuned for agent safety.

ChangeSeverityAgent impact
Tool removed from catalog breaking Calls fail — update harness, prompts, or lockfile
New required field in inputSchema breaking Old argument objects may be rejected
Type change (string → object, etc.) breaking Validators and repair passes may break
New optional field info Backward compatible — note in changelog
Description / enum label shift, shape unchanged suspicious (Pro+) May change tool selection — human review

Breaking changes can trigger webhooks with agentAction hints (for example ack_required or lockfile remediation on Team). Details: MCP tools reference.

Set up an MCP watch (about five minutes)

  1. Open /start or call POST /api/watches/suggest with your MCP HTTP/SSE URL.
  2. Confirm watch type is mcp (not REST JSON).
  3. Run the first check — wait for baseline driftStatus: ok.
  4. Set alert policy to breaking-only before wiring production agents.
  5. Optional: import servers from mcp.json during onboarding to batch-create watches.

Step-by-step with screenshots: First watch how-to · Connect MCP in Cursor.

Pair with preflight before agent runs

Monitoring tells you that the catalog drifted. Preflight lets orchestrators ask may I start this agent run? against current watch status.

curl -s https://driftguard.org/api/preflight \
  -H "Authorization: Bearer $DRIFTGUARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"watchIds":["<your-mcp-watch-id>"]}'

Returns allowed: false with reasons when any bound watch is drifted or in an open incident — before the agent burns tokens on doomed tool calls.

Common questions

Does this work with SSE and streamable HTTP MCP?

Yes — paste the same URL your MCP client uses. DriftGuard probes the endpoint your agents reach in production, not a static export checked into git.

Does DriftGuard judge whether the LLM answer is correct?

No. Classification is structural — schema shape, required fields, tool presence. Semantic review of descriptions is a separate Pro+ signal, not a substitute for human eval.

Can I diff offline without a watch?

Yes. Use the open-source compare_json MCP tool or CLI against two saved tools/list payloads. Hosted watches automate the probe and alert loop.

Next steps

  • Solution overview — MCP agents
  • Coverage assert — fail CI when MCP deps are unwatched
  • API: create a watch
  • OSS: MCP lockfile bridge (for servers you ship)