# UseQR MCP server: tool reference

> The UseQR MCP server at https://useqr.app/api/mcp exposes six tools: qr_generate (any string), qr_generate_typed (WiFi, vCard, UPI and other structured payloads), qr_decode (read codes from an image), qr_verify (prove a styled code scans), qr_batch (up to 1,000 codes per call) and qr_size_recommend (minimum print size for a scan distance). Keyless.

Source: https://useqr.app/docs/developers/qr-code-mcp-server-tools · Last reviewed 2026-08-21 · UseQR is free forever, no signup.

---

## Connect first

Setup lives on the [MCP server page](/docs/developers/qr-code-mcp-server); the short
version:

```bash
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](/docs/developers/caching-and-cdn-strategy-for-qr-images).

```json
{ "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.

```json
{ "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](/docs/developers/decode-a-qr-code-programmatically),
up to 8 codes per image.

```json
{ "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](/docs/developers/building-a-decode-verify-loop)
from the pattern.

```json
{ "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.

```json
{ "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](/glossary/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](/docs/print/the-10-to-1-distance-rule).

```json
{ "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](/docs/developers/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.

## Try it

- https://useqr.app/wifi
- https://useqr.app/vcard
- https://useqr.app/upi
- https://useqr.app/validate