machinegrade/validate

Validate AI-generated artifacts against a contract before you act on them:
- **json_schema** — validate artifact against a JSON Schema (all errors collected).
- **openapi_response** — validate a response body against the response schema for a given path + method + status in an OpenAPI spec.
- **sql** — check a SQL string for syntax errors in a given dialect.
Every check returns a **verdict**, not an error: {valid, errors, latency_ms},
HTTP 200 whether the artifact is valid or not. Only genuinely wrong requests
(bad key, unsupported type, malformed body, over your limit) get typed HTTP
errors.
Live at **https://api.machinegrade.dev** — free tier, self-service key,
try it in 30 seconds (first example below). Built on Hono; the same
codebase runs on Cloudflare Workers (production) and plain Node (local
dev), and is MIT-licensed if you'd rather self-host.
Why
Agents that generate JSON, API responses, or SQL need a fast, cheap,
machine-checkable pass/fail before they ship the result — cheaper than a
full LLM-as-judge call, and deterministic.
Run it locally
3 runnable examples
1. curl
2. Python (requests)
3. MCP config snippet
mcp/server.ts exposes a single tool, validate, that forwards to
POST /v1/validate. Point an MCP-compatible client at it:
Connect remotely
The production service also exposes an MCP endpoint directly — no local
process, no npm install — via streamable HTTP at:
It's the same single validate tool as the stdio adapter above.
initialize and tools/list work without a key (discovery is
anonymous); tools/call requires X-Api-Key (issue one via POST
/keys, same as the REST API — the free tier and limits are shared).
With Claude Code:
The stdio adapter via npm (@machinegrade/validate, see above) remains
available for local/offline use or clients without HTTP transport
support.
Claude Desktop: one-click install
Download the latest .mcpb bundle from
Releases and
double-click it. Claude Desktop asks for an API key during install and stores it
in the OS keychain (macOS Keychain, Windows Credential Manager) rather than in a
config file — nothing lands in claude_desktop_config.json.
Issue a free key (500 calls/month) first:
The bundle is a thin stdio client over the hosted API: ~34 KB, zero bundled
dependencies. If you self-host, point the extension's **API base URL** setting at
your own deployment and the tool talks to that instead.
API
See public/openapi.yaml for the full contract, or
/v1/manifest for a machine-readable
summary (types, limits, pricing, error codes) once the service is running.
/llms.txt is a short pointer for LLM agents.
| Endpoint | In | Out |
|---|---|---|
| POST /keys | {email} | {key} |
| POST /v1/validate | header X-Api-Key, body {type, artifact, contract?} | verdict, header X-Calls-Remaining |
| GET /v1/manifest | — | capability manifest |
| GET /stats | header X-Admin-Token | funnel: keys_issued, active_callers, repeat_callers_7d, limit_hits, paid_requests |
| POST /v1/paid-request | header X-Api-Key | records interest in paid access |
| GET /openapi.yaml, GET /llms.txt | — | static docs |
| POST /mcp | MCP streamable HTTP, header X-Api-Key for tools/call | see "Connect remotely" above |
Pricing
- **Free tier:** 500 calls/month per key, 60 calls/minute rate limit.
- **Paid tier:** EUR 0.002/call beyond the free tier — **opens soon**.
Request paid access via POST /v1/paid-request (requires X-Api-Key);
you'll be notified when it's live.
Errors
Every error is typed JSON — {code, message, hint, docs_url} — never a