Add a CI Gate for MCP Contract Coverage in 10 Minutes

#mcp #githubactions #devops #tutorial

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 and walked a hands-on lab in ToolSchema Kit. This post is the CI half: wire a progressive gate so every mcp.json endpoint is either watched or explicitly ignored before merge.

What you are adding

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.

Full reference: docs/CI.md in the open-source repo.

Step 1 — Copy the starter workflow

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:

schema-hook — proves the diff action works (swap in your own before/after fixtures later).
coverage-preview — reads scan-paths, discovers MCP and API URLs, writes a GitHub Step Summary with unmonitored endpoints and one-click console links.

No files-json boilerplate — scan-paths walks the repo for you.

Step 2 — Read the Step Summary

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.

Step 3 — Trial gate (one endpoint)

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.

Step 4 — Pro gate (multi-dependency repos)

After 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.

What this does not replace

Tool	Role
oasdiff	Diff your OpenAPI specs at merge time
MockDrift / ToolChange	Gate packages for fixtures and MCP manifest lint — see gate ladder
APM / synthetics	Latency and 5xx on your HTTP surface

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.

Suggested progression

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.

Open core boundary

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 → npm ci && npm run build.

Try it

Copy driftguard-starter.yml into your repo.
Open a PR and read the Step Summary.
Start a trial if preview lists URLs you care about.

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.

Series links

Post	Topic
Market gap / launch	Why silent MCP drift happens
ToolSchema lab	10-minute hands-on demo
MCP tool removed postmortem	Real incident timeline
Agent embedding postmortem	MCP tools in the agent loop