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.
Your agent stack depends on tools like create_pull_request
, search_code
, or an internal ops MCP server. When a maintainer:
inputSchema
, orthe 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.
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.
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.
Our platform monitors two watch types:
initialize
→ tools/list
, diff tool names and inputSchema
over 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.
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.
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.
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.
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
.
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:
DRIFTGUARD_API_KEY
to your MCP or CI environment (see We are not replacing oasdiff — we are complementing it.
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.
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:
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