UseQR MCP server — tool reference

Connect first

Setup lives on the MCP server page; the short version:

claude mcp add --transport http useqr https://useqr.app/api/mcp

The server is stateless Streamable HTTP — plain JSON-RPC 2.0 over POST, no auth, no sessions, nothing stored. It negotiates protocol versions 2024-11-05, 2025-03-26 and 2025-06-18. This page is the reference for what tools/list returns: six tools.

Shared styling arguments

Every generating tool accepts the same optional style block:

Arg	Values	Default
size	64–4096 (PNG px)	512
color / bg	hex; bg also transparent	black / white
style	square rounded dot diamond star vertical-bars horizontal-bars organic	square
eye	square rounded circle leaf diamond	matches style
ec	L M Q H	M
format	png (image block) or svg (markup as text)	png

qr_generate

Any string in, image out. Returns the PNG plus a stable hosted URL (/api/v1/qr?…) the agent can embed — the URL is deterministic and cached forever.

{ "name": "qr_generate", "arguments": { "data": "https://example.com", "size": 1024, "ec": "Q" } }

qr_generate_typed

Structured payloads with escaping and format rules handled — the tool agents should prefer whenever the user says "WiFi code" rather than "encode this string". type is one of 29 payload types (wifi, vcard, mecard, email, phone, sms, whatsapp, telegram, event, geo, upi, pix, epc, paypal, bitcoin, ethereum, litecoin, bitcoin-cash, dogecoin, crypto, social, menu, feedback, pdf, coupon, json, ssh, url, text); fields carries the type's parameters, validated against the real specs — a malformed IBAN or VPA fails with an explanation instead of encoding garbage.

{ "name": "qr_generate_typed", "arguments": {
  "type": "wifi", "fields": { "ssid": "CafeGuest", "password": "espresso", "security": "WPA" }
} }

Key field names: wifi(ssid,password,security,hidden) · vcard(fn,ln,org,title,phone,email,url) · upi(pa,pn,am,tn) · event(title,start,end,location) · geo(lat,lng) · pix(key,name,city,amount) · epc(name,iban,amount) · sms/whatsapp(number,message) · email(to,subject,body).

qr_decode

Reads every code in an image — pass url (public http/https) or base64 bytes. Same zxing engine as the decode API, up to 8 codes per image.

{ "name": "qr_decode", "arguments": { "url": "https://example.com/menu-qr.png" } }

qr_verify

The tool that separates this server from image generators: renders the styled code, rasterises it, decodes it back with a real decoder and returns the full report — scannable, decoded, matchesInput, version, ecLevel, contrast, issues[]. The server's own instructions tell models to run it before declaring any styled code print-ready, because whether a heavily styled code still scans is not something a model can reason out from the pattern.

{ "name": "qr_verify", "arguments": { "data": "https://example.com", "color": "888888", "style": "dot" } }

qr_batch

Up to 1,000 items per call. Items mix {data} and {type, fields}; a shared style applies to all with per-item overrides; optional id is echoed back for matching results to source rows; verify: true decodes each code (≤ 50 items). Returns hosted URLs plus the exact encoded payload per item, and a failed item returns its own error and fix without failing the batch.

{ "name": "qr_batch", "arguments": {
  "style": { "size": 1024 },
  "items": [ { "id": "t1", "data": "https://example.com/1" },
             { "id": "w", "type": "wifi", "fields": { "ssid": "Guest" } } ]
} }

qr_size_recommend

Physical-world guardrail: given distance_cm (and optionally the data, since denser codes need more area), returns the minimum print size in mm, cm and inches, assuming a 4-module quiet zone and 300 DPI — with the advice to add 25–50% for low light, glare or curves. The maths behind it: the 10:1 rule.

{ "name": "qr_size_recommend", "arguments": { "distance_cm": 200, "data": "https://example.com/menu" } }

A workflow that composes them

A realistic agent run: qr_generate_typed builds a branded WiFi code → qr_verify reports contrast: 2.1 with an issue → the agent darkens the colour and re-verifies → qr_size_recommend sizes it for a table tent → done, provably scannable. Every failure along the way carries a fix the agent can apply — see using QR codes from an AI agent.

FAQ

What tools does the UseQR MCP server expose?

Six: qr_generate, qr_generate_typed, qr_decode, qr_verify, qr_batch and qr_size_recommend — generation, structured payloads, image decoding, scan verification, bulk generation up to 1,000 items, and print-size recommendations.

Which tool should an agent use for WiFi or payment codes?

qr_generate_typed. It takes typed fields — ssid and password, or pa and pn for UPI — and applies the real escaping and format rules, validating input so a malformed value fails with an explanation instead of producing a broken code.

How does an agent know a styled QR code still scans?

By calling qr_verify, which rasterises the styled output and decodes it with zxing, returning scannable, contrast and concrete issues. Reasoning about the pixel pattern cannot substitute for actually decoding it.

Does qr_batch fail if one item is invalid?

No. Each item succeeds or fails independently; failed items return their own error with a fix field while the rest complete. The response reports count, ok and failed so the agent can retry only what broke.