🥐 croissant-validation

A stateless MCP server for validating MLCommons Croissant dataset metadata — built as a working demonstration of the MCP 2026-07-28 specification, the revision that made the Model Context Protocol stateless.

Live endpoint: https://croissant-validation.jetty.bot/mcp

Why this exists

The 2026-07-28 spec removed the initialize/notifications/initialized handshake and the Mcp-Session-Id header. Every request is now self-contained: protocol version and client capabilities travel in _meta, and servers advertise themselves via server/discover. That means an MCP server can run on plain serverless functions behind any load balancer — no sticky sessions, no shared session store.

This repo is exactly that: the MCP Python SDK v2 (mcp==2.0.0, released alongside the spec) serving Croissant validation from Vercel serverless functions. Validation is performed by the official mlcroissant library — the same checks as the MLCommons croissant-validator, previously hosted in the mlcbakery MCP server.

Tools

Tool	Description
`validate_croissant`	Validate a Croissant JSON-LD document (object or JSON string) against the Croissant schema. Returns per-check results, blocking `errors`, and non-blocking `warnings`.
`validate_croissant_url`	Fetch metadata from a URL (e.g. a Hugging Face dataset's `/croissant` endpoint) and validate it.
`pdf_to_croissant`	Generate Croissant metadata from an academic paper: give it a PDF URL (or an `upload_id` from `POST /upload`, below) and a Jetty agent in an isolated sandbox reads the paper, extracts dataset metadata, writes `croissant.json`, and validates it — the MCP version of mlcroissant.jetty.bot. Runs take 2–5 minutes.
`croissant_run_status`	Poll a running `pdf_to_croissant` job. Done when status is `completed` and `croissant.json` is in `files`.
`croissant_run_result`	Fetch an output file from a completed run — `croissant.json` comes back parsed and re-validated by this server's own validator.

The generation tools mirror the API flow of jettyio/pdf2croissant (upload → runbook launch → trajectory poll → file download) and vendor its runbook verbatim. They need a JETTY_API_TOKEN_PDF2CROISSANT environment variable; without it, the validation tools still work — validation is pure and stateless.

Local PDFs (`POST /upload`)

MCP has no client→server file-transfer primitive — tool arguments are JSON generated by the model, so base64-ing a paper into a tool call is a non-starter. Local files instead come in over plain HTTP:

curl -sS -F "file=@paper.pdf" https://croissant-validation.jetty.bot/upload
# → {"upload_id": "…", "filename": "paper.pdf", "size_bytes": 123, "next": "…"}

Then call pdf_to_croissant with that upload_id instead of pdf_url. A raw-body POST works too (--data-binary @paper.pdf, optional ?filename=).

The upload_id is the Jetty storage path, HMAC-signed with a key derived from the server's Jetty token — self-contained and tamper-evident, so the stateless server needs no session store, and callers can't mint references to arbitrary storage paths. Note the hosted instance sits behind Vercel's ~4.5 MB request-body cap; larger papers (up to 15 MB) should go through pdf_url.

Connect

Claude Code:

claude mcp add --transport http croissant-validator https://croissant-validation.jetty.bot/mcp

Or any MCP client that speaks Streamable HTTP — clients on the 2025-era protocol still work; the SDK answers the legacy handshake alongside server/discover.

One raw stateless request

No handshake — a single POST does everything:

curl -sS https://croissant-validation.jetty.bot/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -d '{
    "jsonrpc": "2.0", "id": 1, "method": "tools/call",
    "params": {
      "name": "validate_croissant_url",
      "arguments": {"url": "https://huggingface.co/api/datasets/mnist/croissant"},
      "_meta": {
        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
        "io.modelcontextprotocol/clientCapabilities": {}
      }
    }
  }'

The params._meta envelope replaces the old initialize handshake — the protocol version and client capabilities ride along on every request instead of being negotiated up front. (The server rejects 2026-07-28 requests without it.)

Development

uv sync
uv run pytest -q                                  # validation + stateless HTTP round-trip tests
uv run uvicorn croissant_mcp.server:app --reload  # local server on :8000

Layout:

croissant_mcp/validation.py — mlcroissant-backed validation (JSON well-formedness → Croissant schema; warnings surfaced from mlcroissant's issue tracker)
croissant_mcp/server.py — MCPServer definition, tools, landing page, and the stateless Streamable HTTP ASGI app (stateless_http=True, json_response=True)
main.py — Vercel entrypoint (the Python backend builder serves the ASGI app on all routes)
examples/ — a valid Croissant file (Titanic, from the MLCommons repo) and an invalid variant (invalid-not-a-dataset.json, missing its @type)

Record-set generation checks (actually materializing data) are intentionally out of scope here — they can download arbitrarily large files, which doesn't belong in a serverless request. Schema validation is the static contract check.

Deploy

Deployed on Vercel (Python runtime, Fluid Compute). The one serverless-specific consideration: streamable_http_app() starts its session manager via ASGI lifespan, which Vercel now runs. In stateless mode there is no cross-request state, so cold starts and horizontal scaling are free.

Roadmap

Wire into Jetty workflows as the validation step for an MCP-native version of PDF → Croissant.

License

MIT