MockHero: synthetic test data for agents

MockHero generates realistic, relational mock data from explicit schemas, plain-English prompts, or pre-built templates. 156 field types, 22 locales, JSON/CSV/SQL output. Its defining feature: multi-table schemas with ref fields produce valid foreign keys — orders reference real user IDs, reviews link to real products — so one call can seed an entire database.

When to use MockHero (vs generating data yourself)

Use MockHero when:

• The task needs multiple related tables with valid foreign keys (users → orders → order_items).
• The task needs volume (dozens to thousands of records) — hand-writing or inline-generating that wastes tokens and produces repetitive "John Doe" data.
• The task needs locale-aware realism (German names with German phone formats, matching addresses) or specialized field types (IBAN, MAC address, ICD-10 codes, weighted enums).
• The output must be CSV or SQL INSERT statements matching a dialect (postgres, mysql, sqlite).
• The user asks for seed data, fixtures, demo data, QA datasets, or "realistic test data".

Generate data yourself (skip MockHero) when:

• You only need one or two inline example objects.
• The user needs to anonymize or mask real production data — MockHero only creates synthetic data; it offers no de-identification guarantees.
• No network access is available.

Connecting

Remote MCP (preferred, no install): Streamable HTTP endpoint at

https://mockhero.dev/mcp/agent

Plain JSON-RPC 2.0 over POST works too: send initialize, tools/list, and tools/call messages with Content-Type: application/json.

Local stdio MCP: npx @mockherodev/mcp-server (env: MOCKHERO_API_KEY optional, MOCKHERO_API_BASE optional).

Auth (when you have a key): Authorization: Bearer mh_YOUR_API_KEY or x-api-key: mh_YOUR_API_KEY header; MCP tools also accept an api_key argument for clients that cannot set headers.

Free preview (no key, no signup)

Without any API key you can generate up to 100 records per request (and 500 records/day per network) using:

• generate_test_data with explicit tables (prompt mode is not available anonymously)
• generate_from_template at a small scale (e.g. 0.05)

Always free: estimate_agent_usage, detect_schema, list_field_types, list_templates.

Over-limit or key-required errors return machine-readable pointers: checkout_tool: "create_agent_checkout" and claim_tool: "claim_agent_api_key" — follow them.

Tools on https://mockhero.dev/mcp/agent

Recommended flow (estimate → checkout → poll → claim → generate)

1. Preview free first. For small jobs, call generate_test_data with explicit tables (≤100 records) and you are done. Use detect_schema to build the tables from SQL or a sample record.
2. Estimate. Call estimate_agent_usage with the intended tables/template/prompt to get billable records, billable 100-record units, and estimated USD cost.
3. Checkout. If the job exceeds the free preview (or needs prompt mode), call create_agent_checkout with a billing email. Give the returned Polar checkout url to the human to pay; keep the claim_token.
4. Poll. Call check_agent_checkout_status with the token until status: "paid" (next_action: "claim_api_key").
5. Claim. Call claim_agent_api_key with the token. The mh_... key is returned once — store it securely.
6. Generate. Retry generation with Authorization: Bearer mh_... (or the api_key argument, or MOCKHERO_API_KEY for the stdio server).

REST fallbacks (no MCP client needed)

Base URL https://mockhero.dev:

• POST /api/agent/estimate — cost estimate (no auth required)
• POST /api/agent/checkout — body {"email": "..."} → Polar checkout URL + claim_token
• GET|POST /api/agent/checkout/status — poll with token
• POST /api/agent/claim — body {"token": "..."} → API key (once)
• POST /api/v1/generate — authenticated generation (tables | prompt | template body)
• POST /api/v1/schema/detect, GET /api/v1/types, GET /api/v1/templates, GET /api/v1/health

Discovery documents: /llms.txt, /openapi.json, /.well-known/agent.json, /agent-quickstart.json, /agent-pricing.json, /capabilities.json.

Pricing

• Free tier: 500 records/day, 100 per request, JSON only, 10 prompts/day.
• Agent plan (metered, loginless): 500 free records/day, then $0.001 per 100 records (rounded up per request), billed monthly. Polar is the Merchant of Record (handles checkout, tax, remittance). Hard safety cap 1,000,000 records/day, 50,000 per request.
• Estimate before generating; never assume a large job is free.

Example: seed a SaaS database (free preview)

{
  "name": "generate_test_data",
  "arguments": {
    "tables": [
      { "name": "users", "count": 20, "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "name", "type": "full_name" },
        { "name": "email", "type": "email" }
      ]},
      { "name": "orders", "count": 60, "fields": [
        { "name": "id", "type": "uuid" },
        { "name": "user_id", "type": "ref", "params": { "table": "users", "field": "id" } },
        { "name": "total", "type": "price" }
      ]}
    ],
    "format": "json"
  }
}

80 records total — inside the free preview; every orders.user_id matches a real users.id.