API Design Prover MCP Connector for Claude

LLMs design APIs the way junior developers do — they pick verbs randomly, skip versioning, return different shapes on every endpoint, and dump error stack traces to the client. The result: 200 consumer services break when you refactor a single route. Clients write custom parsers for each endpoint. Nobody can paginate. Nobody can cache.

The Problem

AI-generated API designs commit five protocol violations that compound into integration nightmares:

• Verb Abuse — GET /users/create. POST for reads. PUT for partial updates. The agent treats HTTP methods as cosmetic labels. Every misused verb breaks caching, idempotency guarantees, and proxy behavior for every consumer downstream.
• Version Blindness — No /v1/ prefix. No header strategy. No deprecation policy. The first schema change becomes a breaking change for every integrated service. Rollback is impossible.
• Shape Chaos — Raw arrays on /users, wrapped objects on /users/:id, nested envelopes on /users/:id/orders. Three endpoints, three different response contracts. Client SDKs become unmaintainable.
• Unbounded Lists — GET /orders returns 47,000 rows. No cursor. No limit. No offset. The mobile client crashes. The CDN times out. The database locks.
• Error Void — Status 500 with { message: 'Something went wrong' }. No error code. No RFC 7807. No machine-readable structure. The frontend shows a generic toast. Support tickets multiply.

How It Works

API Design Prover validates every contract through 5 Decision Pivots:

1. verbsSemantic — GET is read-only and idempotent. POST creates. PUT replaces entirely. PATCH updates partially. DELETE removes. No exceptions. No 'it depends.'
2. versioningDefined — URL path (/v1/), header, or query param — with an explicit deprecation timeline. 'We'll version later' fails this pivot.
3. responseConsistent — Every endpoint returns { data: T, meta?: {}, errors?: [] }. No raw arrays. No naked objects. One shape, every route.
4. paginationHandled — Collection endpoints use cursor or limit/offset with a hard maximum (e.g., max 100). GET /users without bounds fails immediately.
5. errorContracted — Errors follow RFC 7807 Problem Details: { type, title, status, detail, instance }. String messages are rejected.

The Verdict Matrix

First Failing Pivot	Verdict	Meaning
verbsSemantic = false	VERB_ABUSE	HTTP semantics violated. Caching and idempotency broken.
versioningDefined = false	VERSION_MISSING	No versioning strategy. First change breaks all consumers.
responseConsistent = false	SHAPE_INCONSISTENT	Different response shapes per endpoint. Client SDKs unmaintainable.
paginationHandled = false	UNBOUNDED_RESPONSE	Lists return unlimited rows. Memory leaks and timeouts guaranteed.
errorContracted = false	ERROR_UNDEFINED	No standard error structure. Consumers cannot handle failures programmatically.
All pivots pass	API_PROVEN	Semantic verbs, versioned, consistent shape, paginated, RFC 7807 errors.

Why It Works

• Tool calls are obligations. The agent cannot claim 'versioning is handled' without naming the strategy. Filling the fields IS the design work.
• Consistency engine catches contradictions. Claiming responseConsistent=true while returning raw arrays on one route triggers rejection with a specific coaching message.
• Semantic traps detect vague answers. 'We follow REST best practices,' 'errors are handled by the framework,' or 'pagination will be added later' all trigger automatic rejection.