@jsonfabrica/mcp-server

A local Model Context Protocol (MCP) server that lets an AI coding agent — Claude Desktop, Cursor, or anything else that speaks MCP — generate realistic, schema-conformant JSON test data mid-session by calling JsonFabrica's REST API as MCP tools.

It runs over stdio transport only: your AI client launches it as a subprocess, so there's no network service to host and no port to open. It never talks to anything except the JsonFabrica gateway you configure.

New to JsonFabrica? It's an API-first service for generating synthetic JSON test data from reusable templates — deterministic, seed-reproducible, with referential integrity across related records. See jsonfabrica.com and the API docs.

Install / run

Add it to your MCP client's config so the client launches it via npx:

config.json

{
  "mcpServers": {
    "jsonfabrica": {
      "command": "npx",
      "args": ["-y", "@jsonfabrica/mcp-server"],
      "env": {
        "JSONFABRICA_API_KEY": "sk_live_...",
        "JSONFABRICA_API_URL": "https://api.jsonfabrica.com"
      }
    }
  }
}

Claude Desktop — add the block above to claude_desktop_config.json (Settings → Developer → Edit Config), then restart.
Cursor — Settings → MCP → Add new MCP server, or add the block to ~/.cursor/mcp.json.

Get an API key by signing up at jsonfabrica.com — Settings → API Keys.

Or run it directly for local testing:

Terminal

npm install
npm run build
JSONFABRICA_API_KEY=sk_live_... node dist/index.js

What it looks like in a session

Once connected, an agent can do things like:

You: Generate 20 realistic customer records and 60 orders linked to them, and drop them into fixtures/seed.json.

Agent: calls jsonfabrica_create_template for the customer and order shapes, then jsonfabrica_create_batch with a relations map so each order references a generated customer id, then writes the result to the file.

No tab-switching to a dashboard, no hand-written fixtures.

Configuration

Env var	Required	Default	Notes
`JSONFABRICA_API_KEY`	Yes	—	If missing, the server still starts and answers tool discovery, but every tool call fails with "check JSONFABRICA_API_KEY". Never logged or echoed back in tool output.
`JSONFABRICA_API_URL`	No	`https://api.jsonfabrica.com`	Base URL of the JsonFabrica gateway. Override this if you're self-hosting the gateway (e.g. `http://localhost:4000`).

Tools

Every tool's description states, verbatim, which REST endpoint it calls. Tool names are prefixed jsonfabrica_ to avoid collisions with other MCP servers your client may have loaded.

Health / Auth

Tool	Endpoint	Notes
`jsonfabrica_health`	`GET /health`	No auth. Connectivity check.
`jsonfabrica_whoami`	`GET /v1/whoami`	Returns `{ tenantId, role }` for the configured key.

Templates

Tool	Endpoint
`jsonfabrica_create_template`	`POST /v1/templates`
`jsonfabrica_list_templates`	`GET /v1/templates`
`jsonfabrica_get_template`	`GET /v1/templates/{templateId}`
`jsonfabrica_update_template`	`PUT /v1/templates/{templateId}`
`jsonfabrica_delete_template`	`DELETE /v1/templates/{templateId}`
`jsonfabrica_generate_from_template`	`POST /v1/templates/{templateId}/generate`
`jsonfabrica_generate_adhoc`	`POST /v1/templates/generate` (no persistence; same billing as persisted generation)

Template body strings use JsonFabrica's function-call placeholder syntax with angle brackets, e.g. <getRandomFullName()>, <getRandomEmail()>, <createSeq('orderNo')>. The full catalogue of built-in functions is documented at jsonfabrica.com/docs/functions — it's authoring reference, not something this server exposes as tools.

Sequences

Tool	Endpoint
`jsonfabrica_create_sequence`	`POST /v1/sequences`
`jsonfabrica_list_sequences`	`GET /v1/sequences`
`jsonfabrica_get_sequence`	`GET /v1/sequences/{name}`
`jsonfabrica_update_sequence`	`PATCH /v1/sequences/{name}`
`jsonfabrica_delete_sequence`	`DELETE /v1/sequences/{name}`
`jsonfabrica_bump_sequence`	`POST /v1/sequences/{name}/bump`

Batches

Tool	Endpoint
`jsonfabrica_create_batch`	`POST /v1/batches` (small batches run synchronously — 200 with `results`; larger batches are queued — 202, poll with `jsonfabrica_get_batch`)
`jsonfabrica_get_batch`	`GET /v1/batches/{batchId}`

Usage

Tool	Endpoint
`jsonfabrica_get_usage`	`GET /v1/usage` — returns `{ tenantId, usageTotal, asOf }`

Explicitly out of scope

POST /v1/signup and PATCH /v1/billing/tier — unauthenticated account-creation / billing-tier-change endpoints. Wrapping these would let a model create real paid subscriptions or change billing tiers on the user's behalf; excluded by design (generation API surface only).
POST /v1/webhooks/stripe — Stripe-only webhook ingestion, not a developer-facing capability.

Error handling

Every tool catches errors internally and returns an MCP isError: true result with a readable message — it never throws out of the handler or crashes the host process. Common cases:

401 → "Invalid or missing API key — check JSONFABRICA_API_KEY."
403 → the API key's tenant is not allowed to perform the call.
402 (blocked account) → the upstream blockReason is passed through.
Network failure (gateway unreachable) → a message naming the configured JSONFABRICA_API_URL.
Anything else → JsonFabrica API error [CODE] (HTTP status): message.

Troubleshooting

401 / "Invalid or missing API key" → check JSONFABRICA_API_KEY is set and valid.
Connection refused / UPSTREAM_UNREACHABLE → check JSONFABRICA_API_URL and that the gateway is actually running and reachable from wherever this process runs.
403 / FORBIDDEN → your API key's tenant is not permitted to perform that call.

Development

Terminal

npm install
npm run build   # tsc -p tsconfig.json
npm test        # build + node --test dist/
npm start       # node dist/index.js (requires JSONFABRICA_API_KEY)

Source layout mirrors the OpenAPI spec's tags: one file per tag under src/tools/. src/client.ts is the only place that knows about fetch, the base URL, and the Authorization header.

License

MIT — see LICENSE.