Qrblox MCP

What it is

The Qrblox MCP server (qrblox-mcp) connects AI agents to merchant-owned Qrblox data over the Model Context Protocol. A merchant mints an API key in Qrblox Create, pastes it into Claude Desktop, Cursor, or a custom agent, and the assistant can draft QR codes, audio codes, menus, and loyalty challenges — and summarize scan activity — all scoped to that one merchant workspace.

Quick start (no signup)

The fastest path: agents can generate a real, scannable QR code with no key and no OAuth. Sandbox codes work immediately, are IP rate-limited, and expire in 7 days unless claimed into a real account.

curl -X POST https://app.qrblox.com/api/generate-qr-code \
  -H "content-type: application/json" \
  -d '{"url":"https://example.com"}'

{
  "ok": true,
  "code": {
    "id":             "…",
    "destinationUrl": "https://example.com",
    "qrImage":        "data:image/png;base64,…",
    "claimToken":     "…",
    "expiresAt":      "2026-06-02T…Z"
  },
  "upgrade": { "signup": "https://app.qrblox.com", /* … */ }
}

Agents can discover the endpoint without writing code first — GET https://app.qrblox.com/api/generate-qr-code returns a JSON manifest describing every field, the bulk endpoint, the limits, and the path to a real key. The MCP itself is reachable at the same host: GET https://app.qrblox.com/api/mcp returns the full tool list, and the JSON-RPC tools/list method works with no auth.

Get an API key

MCP keys are merchant-scoped and created in Qrblox Create:

Keys carry merchant-scoped permissions:

Authentication

Send the key as a Bearer token. Keys begin with sk-qrblox- and are validated against Firestore on every request; the matching record carries the merchant id and scopes that the tool layer enforces.

Authorization: Bearer sk-qrblox-4c2fa8e1b7d9…

The server also accepts a Firebase ID token or a session cookie for in-app callers on Qrblox Create. External agents use the sk-qrblox- API key — that is what this page covers.

Endpoint and transport

One endpoint: POST https://app.qrblox.com/api/mcp. Standard MCP JSON-RPC 2.0 envelopes in the body, a single JSON-RPC response in the reply. A GET on the same URL returns server metadata (name, endpoint, docs link). Each POST is stateless — no session handshake between requests.

POST /api/mcp HTTP/1.1
Host: app.qrblox.com
Authorization: Bearer sk-qrblox-…
Content-Type: application/json

{"jsonrpc":"2.0","id":1,"method":"tools/call",
 "params":{"name":"qrblox.qr.list",
  "arguments":{"limit":10}}}

Supported JSON-RPC methods:

• initialize — handshake. Returns protocolVersion 2025-03-26 and server info (qrblox-mcp). No auth required.
• notifications/initialized — accepted as a notification; replies 204 No Content.
• ping — protocol-level liveness probe; returns an empty result. No auth (distinct from the qrblox.ping tool).
• tools/list — discover the tool registry. Requires auth.
• tools/call — invoke a tool by name with { name, arguments }. Requires auth.

Tools

Every tool re-derives the merchant from the verified caller, so an agent can only ever read and write within its own merchant workspace.

Example call

{
  "jsonrpc": "2.0",
  "id": "create-menu-qr",
  "method": "tools/call",
  "params": {
    "name": "qrblox.qr.create",
    "arguments": {
      "title": "Table 12 lunch menu",
      "destinationUrl": "https://qrblox.com/m/table-12",
      "campaign": "Lunch menu rollout",
      "tags": ["menu", "table-12"]
    }
  }
}

Bulk generation (requires an API key)

Bulk generation is for real marketing — it writes permanent codes into your merchant workspace with evergreen Firebase Storage PNG URLs, no sandbox, no expiry. So it requires a sk-qrblox- key. Mint one for free at create.qrblox.com/settings/api-keys.

One bulk call

curl -X POST https://app.qrblox.com/api/bulk-qr-codes \
  -H "authorization: Bearer sk-qrblox-…" \
  -H "content-type: application/json" \
  -d '{"urls":[
       "https://qrblox.com/menu/spring",
       "https://qrblox.com/menu/summer",
       "https://qrblox.com/menu/fall"
     ]}'

Up to 50 URLs per call. Response shape: { ok, count, codes: [{ codeId, title, destinationUrl, qrImageUrl }] }. Each qrImageUrl is a Firebase Storage download URL — stable, sharable, no expiry.

Or one tool call per row, through the MCP

Same shape as bulk, item by item — useful when you want per-row error handling, per-row delay, or richer per-row arguments (campaign labels, tags).

const rows = [
  { "title": "Email — June", "destinationUrl": "https://qrblox.com/june", "campaign": "june" },
  { "title": "Print — June", "destinationUrl": "https://qrblox.com/june", "campaign": "june" },
];

for (const args of rows) {
  await fetch("https://app.qrblox.com/api/mcp", {
    method: "POST",
    headers: { "authorization": "Bearer sk-qrblox-…", "content-type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0", id: args.title, method: "tools/call",
      params: { name: "qrblox.qr.create", arguments: args },
    }),
  });
}

Want all codes labelled by campaign for reporting? Pass a consistent campaign argument — the scan summary rolls up by campaign.

Tracking & analytics

Qrblox supports two flavors of code, and your tracking story depends on which one you create:

For account-owned codes, agents can read scan counts via:

{ "jsonrpc":"2.0", "id":1, "method":"tools/call",
  "params":{ "name":"qrblox.analytics.scan_summary",
              "arguments":{ "days": 30 } } }

Returns totalScans and a byDay series. The deeper raw export is the daily DataPro report (see Reports on the docs home) — per-code, with city, lat/lng, and day-of-week.

Marketing playbook

Concrete patterns agents can run on a merchant's behalf, end-to-end through the MCP:

Errors

Tool results come back as JSON-RPC result objects; failures come back as JSON-RPC error objects. Auth failures carry a data.code of NO_AUTH, INVALID_API_KEY, INVALID_TOKEN, or REVOKED.

Security model

Connect snippets

Claude Desktop

{
  "mcpServers": {
    "qrblox": {
      "url": "https://app.qrblox.com/api/mcp",
      "headers": { "Authorization": "Bearer sk-qrblox-…" }
    }
  }
}

Cursor

In Cursor settings, add a new MCP server with the same URL and Authorization header.

curl (smoke test)

# Expect: { ok: true, merchantId: "…", authMethod: "api-key" }
curl -s https://app.qrblox.com/api/mcp \
  -H "Authorization: Bearer sk-qrblox-…" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"qrblox.ping","arguments":{}}}'

Looking for the rest of the stack? Web Portal · Canva app · All docs