Model Context Protocol · v3.2.0

MCP Integration

Any AI agent can generate shaped QR codes on demand. One JSON-RPC call. Clean black-and-white output with camo noise fill. 3 ink per QR.

START HERE — use generate_geometric_qr This is the primary tool. Fast, deterministic, clean B&W output shaped to any silhouette, with camo noise filling the rest of the shape. 3 ink for a preset shape, 5 ink for your own uploaded silhouette. Reusing a shape you already saved is back to 3.

Endpoint

POST https://shapedqr.com/api/qr-studio-mcp
Content-Type: application/json
X-MCP-Source: your-agent-name

generate_geometric_qr PRIMARY · 3 ink preset · 5 ink custom shape

Clean black-and-white QR clipped to a shape. Deterministic. Fast. This is what most agents want.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_geometric_qr",
    "arguments": {
      "url": "https://yoursite.com",
      "email": "agent@yourdomain.com",
      "shape_preset": "bb"
    }
  }
}

Field	Required	Notes
url	required	The URL to encode. https://, tel:, wifi:, sms: all supported.
email	required	Billing identifier — the same email as your inkwell.wiki ink wallet.
shape_preset	one of	Preset key from `list_shapes`. e.g. bb, skull, heart, star5, dt, crown, hexagon…
shape_svg_path	one of	Custom SVG `d` attribute for your own silhouette (viewBox 0 0 480 480). 5 ink instead of 3, and it auto-saves so reuse is 3.
saved_shape_id	optional	Reuse a shape from `list_my_shapes` or `list_gallery_shapes` at the 3 ink base rate.

list_shapes FREE · 0 ink

Returns all available shape preset keys. Call once to discover what's available before generating.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": { "name": "list_shapes", "arguments": {} }
}

generate_multi_qr 3 ink per real QR · decoys free

Multiple QRs inside one shape. Mix real scannable QRs with decoys — broken-finder fakes that look like QRs but don't scan, defeating bot scrapers while humans find the real one.

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": {
    "name": "generate_multi_qr",
    "arguments": {
      "url": "https://yoursite.com",
      "email": "agent@yourdomain.com",
      "shape_preset": "bb",
      "extra_qrs": [
        { "decoy": true },
        { "decoy": true }
      ]
    }
  }
}

Response

{
  "ok": true,
  "svg": "<svg ...>",
  "svg_url": "https://…/shaped-qr.svg",
  "scannable": true,
  "layout": {
    "primary_size_pct_used": 32,
    "primary_shape_damage_pct": 5,
    "finder_corners_inside_pct": 100,
    "recommended_min_output_px": 280,
    "warnings": []
  },
  "ink_charged": 3,
  "charged_via": "ink",
  "remaining_balance": 47
}

Check scannable before you ship the art A shape can be too thin or too busy to hold a readable QR. When that happens scannable is false and layout.warnings says why — usually a shorter URL or a fuller shape fixes it. layout.recommended_min_output_px is the smallest output width that still decodes, so size your export at or above it.

Auto-refund on failure Ink is only charged on success. Failed generations auto-refund.

Pricing

1 ink = $0.05. generate_geometric_qr costs 3 ink ($0.15) on a preset shape and 5 ink ($0.25) on a custom uploaded silhouette — and because custom shapes auto-save to your account, every reuse drops back to 3. generate_multi_qr is 3 ink per real QR; decoys are free.

list_shapes, list_my_shapes, list_gallery_shapes, save_shape, delete_shape, get_ink_balance, trace_image and validate_geometric_layout are all free. Top up at inkwell.wiki/buy-ink, or call get_pricing — it always returns the live rates.

Rather not buy ink? cash_checkout returns a Stripe link for a flat $1 per step. A $5 Studio Pass covers 5 shapes a month.