Add a CI Gate for MCP Contract Coverage in 10 Minutes

DriftGuard offers a CI gate that catches silent MCP contract drift before merge. The tool scans mcp.json files, compares tool schemas, and blocks pull requests when endpoints are missing or changed. A progressive funnel lets teams start with a free preview and upgrade to a paid gate that enforces coverage.

Your PR is green. tools/call still breaks on Tuesday. That gap is familiar: CI validates what you ship , not what your agent consumes . Cursor and Claude read mcp.json or .cursor/mcp.json and trust whatever tools/list returns today. When a vendor removes a tool or tightens inputSchema , your pipeline does not notice — because nothing in Git ever referenced that contract. We already covered the failure mode in why MCP integrations break silently https://dev.to/kioiek/why-your-mcp-integrations-break-silently-and-how-we-built-driftguard-to-close-the-gap-4g0g and walked a hands-on lab in ToolSchema Kit https://dev.to/kioiek/catch-mcp-tool-schema-drift-in-10-minutes-live-demo-optional-watch-4ao2 . This post is the CI half : wire a progressive gate so every mcp.json endpoint is either watched or explicitly ignored before merge. DriftGuard CI is a hook → preview → trial → paid gate funnel. You can stop at any layer: | Layer | Action | API key | Blocks CI? | |---|---|---|---| 1 — Hook | drift-diff / compare json | No | On breaking fixture diff only | 2 — Preview | drift-coverage-preview | No | No writes Step Summary + trial link | 3 — Trial gate | drift-coverage + trial session | Trial secret | Yes — 1 endpoint max | 4 — Pro gate | drift-coverage + API key | dg … | Yes — plan limit 50 on Pro | Layer 2 is the fastest win: zero secrets, scans your repo, prints which MCP URLs are not monitored. Layer 4 is what teams adopt after one postmortem like MCP tool removed over the weekend https://dev.to/kioiek/postmortem-mcp-tool-removed-over-the-weekend-detected-on-scheduled-poll-not-prod-traffic-1pdi . Full reference: docs/CI.md https://github.com/kioie/driftguard/blob/main/docs/CI.md in the open-source repo. Create .github/workflows/driftguard.yml : name: DriftGuard on: pull request: push: branches: main jobs: schema-hook: runs-on: ubuntu-latest steps: - uses: kioie/driftguard/.github/actions/drift-diff@v0.3.3 with: before: '{"status":"ok","data":{"id":1,"name":"test"}}' after: '{"status":"ok","data":{"id":1}}' coverage-preview: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: kioie/driftguard/.github/actions/drift-coverage-preview@v0.3.3 with: scan-paths: mcp.json,.cursor/mcp.json,package.json Pin @v0.3.3 or current release — never @main in production pipelines.Open a PR. The DriftGuard check runs two jobs: scan-paths , discovers MCP and API URLs, writes a No files-json boilerplate — scan-paths walks the repo for you. After the preview job finishes, expand Summary on the workflow run. You should see something like: Discovered endpoints: 3 Watched: 0 Missing: 3 → https://driftguard.org/ci/setup?from=ci&import=… That link opens CI setup : mint a trial session, copy DRIFTGUARD TRIAL SESSION into GitHub secrets, and import the first missing watch without leaving the browser.Preview is non-blocking by default — it nudges without breaking existing repos. When you are ready to enforce, keep reading. Add a secret DRIFTGUARD TRIAL SESSION from Step Summary or POST /api/trial/session . Uncomment a third job: coverage-gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: kioie/driftguard/.github/actions/drift-coverage@v0.3.3 with: trial-session: ${{ secrets.DRIFTGUARD TRIAL SESSION }} scan-paths: mcp.json,.cursor/mcp.json,package.json Trial intentionally limits you to one watched endpoint. If preview finds three MCP servers and only one is covered, the gate fails with an upgrade message . That is the funnel working — not a bug. For a single-server team one Stripe MCP, one internal ops server , trial gate is enough to block merges until that URL is on a schedule. After pricing https://driftguard.org/pricing → activate, replace the trial header with your API key: coverage-gate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: kioie/driftguard/.github/actions/drift-coverage@v0.3.3 with: api-key: ${{ secrets.DRIFTGUARD API KEY }} scan-paths: mcp.json,.cursor/mcp.json,package.json One dg … key unlocks assert coverage in MCP, the hosted API, and CI. Failures include upgrade.console URLs to bulk-import missing watches. Local equivalent useful in pre-commit or agent loops : export DRIFTGUARD API KEY=dg … driftguard coverage assert --mcp-json .cursor/mcp.json Exit code 1 when a discovered dependency is not watched. | Tool | Role | |---|---| oasdiff | Diff your OpenAPI specs at merge time | MockDrift / ToolChange | Gate packages for fixtures and MCP manifest lint — see | The CI gate answers: "Every URL in mcp.json that our agents depend on — is it on a watch?" Scheduled polling and breaking-classified alerts are hosted; the diff engine stays open source. Week 1 drift-diff on PRs fixture or snapshot you control Week 2 drift-coverage-preview see the gap, no secrets Week 3 Trial gate on one critical MCP server Week 4 Pro gate when preview lists 2+ production dependencies Optional: turn preview blocking early with fail-on-missing: true once the team agrees every discovered URL should be watched or removed from config. | Free in GitHub Actions | Hosted trial / Pro | |---|---| drift-diff , compare json | register watch , scheduled polls | drift-coverage-preview | Alerts, drift history, console | Step Summary + /ci/setup deep links | assert coverage enforcement | Clone path until npm publish is fully wired: github.com/kioie/driftguard https://github.com/kioie/driftguard → npm ci && npm run build . Question for you: Do you gate third-party dependencies in CI today — OpenAPI only, MCP included, or not at all? I read every reply and will link follow-up posts agent embedding, contract drift monitoring based on what teams are actually running. | Post | Topic | |---|---| | GitHub: kioie/driftguard https://github.com/kioie/driftguard · Hosted: driftguard.org https://driftguard.org