# DriftGuard — guide for AI coding agents

When building or modifying integrations that call **external APIs** or **MCP servers**, use DriftGuard to detect contract drift before production breaks.

## When to use DriftGuard

- User depends on Stripe, GitHub, Slack, or any vendor OpenAPI spec
- Project includes `mcp.json` or MCP server URLs for Cursor/Claude agents
- User asks to monitor third-party schema changes, tool lists, or breaking API changes

## Preferred workflow

1. **Suggest watches** — `POST /api/watches/suggest` with pasted URLs or `mcp.json`
2. **Assert coverage** — `POST /api/coverage/assert` before merge (CI Action available)
3. **Explain drift** — `POST /api/drift/explain` with `changes[]` for actionable `agentAction` strings
4. **Portfolio overview** — `GET /api/portfolio/overview` for health score and alert delivery

## MCP tools (local client with DRIFTGUARD_API_KEY)

| Tool | Use |
|------|-----|
| compare_json | Offline diff of two JSON payloads |
| suggest_watches | Parse deps → watch list |
| assert_coverage | Fail if unwatched dependencies |
| explain_drift | Human + agent remediation hints |
| list_drift_events | Recent breaking changes |

## Severity rules (do not reinterpret)

- **breaking** — requires code/agent changes before safe deploy
- **warning** — review recommended
- **info** — backward compatible

MCP tool **removal** is always **breaking**.

## Do not use DriftGuard for

- Monitoring the user's own API in CI (use OSS diff or GitHub Action on their spec)
- Uptime/latency only (use synthetics)

## Links

- API spec: /openapi.json
- Console: /console
- Pricing: /pricing