claimseed

@claimseed/mcp

An MCP server that lets an agent list, generate and render claimseed's synthetic medical-billing specimen documents. Rendered documents come back as page images that chat clients show in the conversation, and, if you give it a folder, as PDF and ground-truth files in that folder. It runs over stdio, writes nowhere but that one folder, never reads a file a client names, and needs no network access and no API key.

Run it

Node.js 22.13 or later. Rendering needs Chrome or Chromium (CLAIMSEED_CHROME=/path/to/chrome, or an install in a usual place); listing and generate_data do not.

To see documents in the chat and save no files:

{ "mcpServers": { "claimseed": { "command": "npx", "args": ["-y", "@claimseed/mcp"] } } }

To also keep each PDF and its ground truth as files, give it a folder:

{

"mcpServers": { "claimseed": { "command": "npx", "args": ["-y", "@claimseed/mcp", "--workspace", "/absolute/path/to/claimseed-out"] } } }

Or from a checkout: node packages/mcp/src/cli.js (add --workspace ./out for files). With Docker, using the published image ghcr.io/claimseed/claimseed-mcp (Chromium is inside it; :latest, or a version tag such as :0.1.0), or one you build from the Dockerfile at the repository root (docker build -t claimseed-mcp ., then use claimseed-mcp as the image name below):

docker run -i --rm --network none --read-only --tmpfs /tmp --cap-drop ALL --security-opt no-new-privileges \

--user "$(id -u):$(id -g)" -v "$PWD/claimseed-out:/work" ghcr.io/claimseed/claimseed-mcp

(The image writes to /work; to save no files, leave out the -v mount and add -e CLAIMSEED_WORKSPACE=.)

{ "mcpServers": { "claimseed": { "command": "docker",

"args": ["run", "-i", "--rm", "--network", "none", "--read-only", "--tmpfs", "/tmp", "--cap-drop", "ALL", "--security-opt", "no-new-privileges", "--user", "1000:1000", "-v", "/absolute/path/to/claimseed-out:/work", "ghcr.io/claimseed/claimseed-mcp"] } } }

The server is listed in the MCP registry as io.github.claimseed/claimseed.

Replace 1000:1000 with your user and group ids (id -u, id -g) so the files in the folder are yours. Chromium's own sandbox needs privileges a container does not have, so inside the image it runs without it; the container is the boundary, which is why the flags above take away its network, its capabilities and its writable filesystem.

Tools

Arguments are a type, a scenario slug and a seed (letters, digits, ., _, -; up to 64 characters). The same type, scenario and seed always give the same data, and on Linux with the same Chrome build the same PDF bytes. generate_data, render_document, degrade_document and verify_document also take layout_variant for itemized-bill, ppo-eob and hmo-eob: an id from the type's list in describe_document_type (b01-b12, p01-p12, h01-h12), or seeded to pick one from the seed. A variant prints the same data with another column order, header wording, style and way of marking a continued table; the ground truth names it (documents[0].layoutVariant, schema 1.4) and, with a workspace, the file names carry its id after the seed. Left out, the document keeps the standard layout, unchanged. msn takes no variant; a value for it, an unknown id, an id of another type and all are refused with an error that repeats nothing sent.

render_document also takes:

• preview: none, first or all — which pages come back as images (default all without a workspace, first with one). Pages are 1200 pixels on the long side, PNG (JPEG when only a JPEG still fits), and one result carries at most CLAIMSEED_MCP_PREVIEW_KB of image data (default 800 KB, under the 1 MB some clients allow a tool result); the result says which pages it holds and where to continue. The first requested page is always included, drawn smaller or as a JPEG to fit, and at its smallest even when that is over a very low limit.
• from_page: the first page to return as an image (default 1), to see the pages one result had no room for.
• include_pdf: also return the PDF itself, embedded in the result. It counts toward the same limit: when it fits, page images take the room left (none is forced in); when the PDF alone is over the limit it is left out, and the result says so (pdfEmbedded: false).
• also: 835 (the only value) — also write the X12 835 remittance of the same claims, for msn, ppo-eob and hmo-eob; any other type is refused. With a workspace it is saved beside the PDF under a name the server chooses (.835) and linked in the result; without one its text is embedded in the result (application/edi-x12). The structured result's remittance gives the file (or null), its SHA-256 and whether it is embedded; the ground truth holds the 835 as documents[1] and, on each error it carries, x12Ref. What the file contains: the core README, "X12 835 remittances".

degrade_document takes the same arguments as render_document and preset: scan, fax, photo or low-res. The settings (rotation, blur, noise, resolution and the rest) come from the type, scenario, seed and preset, so the same request gives the same settings. The pixels can differ very slightly from one run to the next (antialiasing in the browser), and so can the copy's bytes; its ground truth records the SHA-256 of the copy it came with. verify_document scores a report on a degraded copy against the same answer key as the clean document.

verify_document takes the type, scenario and seed of the document and output, the report in the shape of schema://extractor-output: fields maps answer-key field paths (the keys of documents[0].fields) to the values read, and errors lists { kind, fieldRef or lineRef }. It rebuilds the answer key from the seed with this version of claimseed. Matching follows @claimseed/core's verify command: money to the cent, dates in ISO, M/D/YYYY or "April 11, 2026", text without regard to case; an error is found when its kind and line match, and for a duplicate charge either line counts; a flag on a decoy (a line that looks wrong but follows the rules) is a false alarm. To score a whole rendered set, use claimseed-core batch and claimseed-core verify --manifest.

Resources: schema://ground-truth (the ground-truth JSON Schema), schema://extractor-output (the report verify_document scores), catalog://scenarios, catalog://mutations (error and decoy operations), docs://error-taxonomy, policy://synthetic-data, and ui://claimseed/preview (the MCP Apps view below). Prompt: build_test_case (a goal, optionally a type) plans and renders a small test set with expected results.

Seeing documents in the chat

A render_document result holds the page images as standard MCP image content, the ground truth as structured content, and names an MCP Apps view (_meta.ui.resourceUri = "ui://claimseed/preview") that shows the pages with a table of the injected errors and, when there are any, a table of the decoys. As in describe_document_type, only a document with neither errors nor decoys is labelled a clean control. What you see depends on the client:

Every client gets the text summary and the structured ground truth. The view is one self-contained page: it loads nothing (its Content-Security-Policy allows only data: images), sends nothing but the MCP Apps messages to its host, shows every value as text, and takes only colour and font values from the host's style variables.

ChatGPT reaches MCP servers over HTTPS, so a stdio server needs a bridge and a public address. One way, with third-party tools (pin versions you have checked): run npx -y supergateway@4.1.0 --stdio "npx -y @claimseed/mcp" --outputTransport streamableHttp --stateful --port 8000, expose port 8000 with a tunnel (for example cloudflared tunnel --url http://localhost:8000), and add https:// /mcp as a connector in ChatGPT's developer mode. Anyone who has the tunnel address can call the server while it runs; without a workspace it writes nothing, but stop the tunnel when you are done.

Limits and safety

• One folder, or none. Without a workspace the server saves no file. Its browser, like any Chrome, keeps a temporary profile in the system temp folder while it runs (in the container, the in-memory /tmp); the profile is removed when the browser closes, after a minute without renders or when the server stops, and is left behind only if the process is killed. With a workspace, the server writes only into the workspace folder (--workspace or CLAIMSEED_WORKSPACE), which must exist and may not be / or your home folder. It picks every file name itself ( _ _ _ .pdf and .ground-truth.json), creates files exclusively and never through a symbolic link, and stops if the folder is moved or replaced by a link while it runs.
• Quota. CLAIMSEED_MCP_QUOTA_MB (default 500) caps the total size of its outputs, counted across runs in a ledger (.claimseed-mcp.json) with each file's size and SHA-256. Over the quota it deletes its own oldest outputs from the current run, and only files still exactly as it wrote them; the right to delete is kept in memory, not in the ledger, so an edited ledger cannot make it delete anything. It never deletes any other file, including its outputs from earlier runs: when those alone fill the quota, a render is refused until you remove some. Run one server per folder.
• Time and load. One shared browser per