Validate MCP server

machinegrade validate

Validate AI-generated artifacts against a contract before you act on them:

• jsonschema** — validate artifact against a JSON Schema (all errors collected).
• openapiresponse** — 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

npm install
npm run dev
# machinegrade validate listening on http://localhost:8787

3 runnable examples

1. curl

# Get an API key (live service — works as-is)
curl -s -X POST https://api.machinegrade.dev/keys \
  -H 'content-type: application/json' \
  -d '{"email": "you@example.com"}'
# => {"key":"sk_..."}

# Validate a JSON artifact against a JSON Schema
curl -s -X POST https://api.machinegrade.dev/v1/validate \
  -H 'content-type: application/json' \
  -H 'X-Api-Key: sk_...' \
  -d '{
    "type": "json_schema",
    "artifact": {"name": "Ada", "age": 30},
    "contract": {
      "schema": {
        "type": "object",
        "required": ["name", "age"],
        "properties": {"name": {"type": "string"}, "age": {"type": "number"}}
      }
    }
  }'
# => {"valid":true,"errors":[],"latency_ms":1}

2. Python (requests)

import requests

base = "http://localhost:8787"

key = requests.post(f"{base}/keys", json={"email": "you@example.com"}).json()["key"]

resp = requests.post(
    f"{base}/v1/validate",
    headers={"X-Api-Key": key},
    json={
        "type": "sql",
        "artifact": "SELECT id, name FROM users WHERE id = 1",
        "contract": {"dialect": "mysql"},
    },
)
print(resp.status_code, resp.headers.get("X-Calls-Remaining"), resp.json())

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:

{
  "mcpServers": {
    "machinegrade-validate": {
      "command": "npx",
      "args": ["tsx", "mcp/server.ts"],
      "cwd": "/path/to/validate",
      "env": {
        "SANDBOX_URL": "http://localhost:8787",
        "SANDBOX_API_KEY": "sk_..."
      }
    }
  }
}

Connect remotely

The production service also exposes an MCP endpoint directly — no local process, no npm install — via streamable HTTP at:

POST https://api.machinegrade.dev/mcp

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:

claude mcp add --transport http validate https://api.machinegrade.dev/mcp --header "X-Api-Key: sk_..."

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 claudedesktopconfig.json.

Shortened. The full README is on GitHub.