Every integration team has lived the same incident: a dependency changed its contract, nothing failed in CI, and production broke on a Tuesday anyway.
When Optic shut down, that pain got louder. Teams still need to know when an API they depend on — but do not own — starts returning different JSON. What changed in the last six months is volume and surface area: MCP servers, agent tool catalogs, and partner webhooks now fail the same way REST APIs always have, except failures show up as confused agents instead of clean 4xx errors.
We built DriftGuard because the tooling landscape left a hole:
| What teams use today | What it covers well | What it misses |
|---|---|---|
| oasdiff | OpenAPI diffs in CI for specs you control | Live payloads, MCP tools, vendors without specs |
| FlareCanary / uptime tools | Status codes, latency | Schema shape, required fields, tool definitions |
| Contract tests in-repo | Your own services | Stripe, GitHub, internal MCP servers owned by other teams |
The gap: continuous monitoring for schema drift on systems you consume but do not publish specs for — especially MCP tools/list output.
This article walks through the problems we see in production integrations, how we classify drift, and how to wire monitoring into a stack you already run.
The problems integration teams actually hit
1. MCP tools change without a changelog
Your agent stack depends on tools like create_pull_request, search_code, or an internal ops MCP server. When a maintainer:
- removes a tool,
- adds a required field to
inputSchema, or - renames a parameter,
the agent does not always surface a structured error. You get retries, empty results, or silent tool skips. By the time someone notices, several workflows have already degraded.
What teams need: a baseline snapshot of tools/list and a diff when the catalog or schemas move.
2. Vendor APIs drift outside your OpenAPI file
Stripe webhooks, GitHub REST responses, billing portals, identity providers — most teams integrate against observed JSON, not a spec they version in-repo. A field disappears, a type widens, an array becomes an object. Unit tests with fixtures go stale; production does not.
What teams need: infer schema from live responses over time and alert on breaking vs informational changes.
3. CI green, production red
Contract tests validate what you ship. They rarely validate what you consume. Post-Optic, teams rebuilt CI diff pipelines but still lack always-on watches on URLs that matter for revenue or operations.
What teams need: scheduled checks, webhook alerts, and history — without running another JVM cluster.
How we approach schema drift at DriftGuard
Our platform monitors two watch types:
- REST / JSON endpoints — fetch, infer schema, diff against the last snapshot
-
MCP servers —
initialize→tools/list, diff tool names andinputSchemaover time
Every change lands in one of three buckets:
| Severity | Meaning | Example |
|---|---|---|
| Breaking | Callers or agents will fail | Required field added, tool removed, type narrowed |
| Warning | Likely breakage or silent behavior change | Optional field removed, tool description changed materially |
| Info | Safe evolution | New optional field, new tool added |
That classification is what makes alerts actionable. On-call does not need a raw JSON diff at 2am — they need to know if they can wait until Monday.
Local diff (no account required)
Teams can validate the engine locally before pointing watches at production URLs:
git clone https://github.com/kioie/driftguard
cd driftguard && npm install && npm run build
npm run check -- diff \
'{"user":{"id":1,"email":"a@b.com"}}' \
'{"user":{"id":1}}'
Example output shape:
{
"hasChanges": true,
"breakingCount": 1,
"warningCount": 0,
"infoCount": 0,
"changes": [ /* field-level detail */ ]
}
Use this in incident post-mortems, vendor escalation threads, or pre-deploy sanity checks.
Practical deployment patterns we recommend
Pattern A — CI for what you own, watches for what you don't
Your OpenAPI specs → oasdiff in GitHub Actions
Partner / MCP URLs → DriftGuard watches + webhooks
This split keeps CI fast and puts long-running polling on infrastructure built for it.
Pattern B — MCP-native operations
DriftGuard ships an MCP server so agent workflows can register and inspect watches without context-switching to a dashboard:
| Tool | Use when |
|---|---|
compare_json |
Ad-hoc diff of two payloads (runs locally) |
register_watch |
Add a URL to continuous monitoring |
check_watch |
Force an immediate drift check |
list_drift_events |
Pull recent breaking changes into an agent session |
We designed this so platform teams can expose drift data inside the same surface engineers already use — not as another portal login.
Pattern C — Alert routing you already have
Point watch webhooks at Slack, PagerDuty, or an internal event bus. Payloads include breaking / warning / info counts plus structured change lists so routers can page only on breakingCount > 0.
Hosted platform vs open-source client
We run an open-core model: the diff engine and MCP client are public; continuous monitoring, retention, and multi-tenant isolation run on our hosted edge stack.
| Tier | Price | Built for |
|---|---|---|
| Free | $0 | Self-host, 3 watches, daily checks, OSS MCP + CLI |
| Pro | $19/mo | 25 watches, hourly checks, 30-day history, API keys |
| Team | $49/mo | 100 watches, 15-minute checks, shared keys, priority support |
Hosted checkout and billing are handled through our secure payment flow — no separate ops burden for tax or invoicing on your side.
Get started on hosted:
- Pricing & checkout
- Activate API key after purchase
- Add
DRIFTGUARD_API_KEYto your MCP or CI environment (see README)
Where DriftGuard fits in the market
We are not replacing oasdiff — we are complementing it.
- oasdiff → gate merges on spec changes you control
- DriftGuard → watch runtime behavior of APIs and MCP tools you depend on
If your roadmap includes more agents, more MCP integrations, or more vendor APIs post-Optic, schema drift becomes infrastructure work — not a one-off debugging session.
Try it this week
Open source (5 minutes):
git clone https://github.com/kioie/driftguard
cd driftguard && npm install && npm run build
npm run check -- diff '<before-json>' '<after-json>'
Hosted monitoring: register your first watch from Cursor via MCP or POST to /api/watches with a Pro API key.
Questions we want from the community:
- Which MCP servers are you running in production today?
- Do you page on schema drift, or only on HTTP errors?
- What would make hosted monitoring a no-brainer vs self-host?
We are actively expanding MCP coverage and retention policies based on production feedback from early teams.
DriftGuard is maintained by the team at Kioi. Open-source client: github.com/kioie/driftguard · Hosted: driftguard.eddy-d55.workers.dev
Top comments (0)