MCP server

One endpoint gives an agent the same 13 tools the REST API exposes, and every answer comes back inside a Trust Envelope — sources, verification labels with their evidence, coverage, review state and an audit record. Agents are exactly where unverified citations do the most damage, so the honesty contract is not optional here.

Connect

https://mcp.verdict.io/mcp

Streamable HTTP transport, JSON-RPC. Point any MCP client at that URL with a Bearer token; the server advertises its tools through the usual initialize / tools/list handshake.

The REST API at https://api.verdict.io/v1 exposes the same surface for software that is not an agent. Same auth, same envelope, same prices — see the 13 tools.

Authentication

Lane	Token	Use it for
OAuth	Bearer JWT	Interactive users. Signup credits and a monthly free-tier floor attach to this lane.
API key	vd_key_…	Server-to-server. Minted from an OAuth session, shown once, stored hashed. Calls bill the creating account.

A leaked key cannot mint or revoke keys

Key management is OAuth-lane only. An API key can spend against the account that created it, and that is the whole of its authority — it cannot create more keys, revoke the keys you have, or lock you out of your own account. Twenty active keys per account; rotate by creating the new one, moving traffic, then revoking the old.

Rate limits, stated plainly

A token bucket per account, shared across every replica and refilled continuously — 30 requests/minute once the account holds 501 credits or more, 5/minute on the free floor.

Honour Retry-After and you will never see a second 429

Every 429 carries it, as a header and as error.retry_after in the envelope. Weighted refusals make waits of 20–60 seconds normal, so a fixed one-second backoff loop will burn its retry budget and get nowhere. Two anti-patterns worth naming: a serial tight loop of GETs trips the limiter even at concurrency 1, and list workloads that could have been one batch call.

Batch is weighted rather than free: POST /v1/cases/batch costs about one token per 50 ids requested, so a full 500-id batch costs ten. A batch larger than your per-minute capacity is granted when your bucket is full, so it never becomes a permanent 429.

Retries never double-charge

Idempotency is server-enforced. A byte-identical request inside the replay window returns the stored answer and is not billed again, marked meter.replayed: true. Verification tools replay for 24 hours; read calls replay for 1 minute.

The same window is why you must not probe “did the fix land?” with a byte-identical request — you will get the replay, not a fresh answer.

Pin the contract, fail loudly

Two documents are public, versioned and static per deploy. Read them at build time and pin what you read:

Document	Carries
consumer guidance	`guidance_version`, label classes, measured per-label reliability, rate and replay semantics
tool manifest	every tool with its `output_schema_sha256`

When a schema or the guidance version moves, a pinned consumer breaks visibly instead of quietly mis-reading a response. That is the intended behavior, not a nuisance: re-pin after reading what changed. Our own reference gate does exactly this, and the label semantics page explains why an unrecognised label must never pass silently.

What a call costs

Identical to REST — the transport does not change the price. A citation check is 3¢, and 1¢ when we return an honest coverage gap. Reading an audit record back is free, as is a coverage report. Full table on pricing.