A guide for developers integrating Whisqr through marketplaces (such as mcpize), AI agent gateways, or direct Streamable HTTP connections. Covers server capabilities, multi-layer fallbacks, interactive UI rendering, and optimal agent workflows.
Whisqr is accessible over standard Streamable HTTP. It requires no local compilation or binary dependencies on the client runtime.
| Parameter | Value | Notes |
|---|---|---|
| Endpoint URL | https://whisqr.com/mcp |
Primary Streamable HTTP endpoint |
| HTTP Method | POST |
JSON-RPC 2.0 payload over HTTP |
| Required Header | Accept: application/json, text/event-stream |
Mandatory header for MCP Streamable HTTP |
| Tracking Base | https://whq.at |
Short redirect domain for dynamic tracked links |
| Protocol Version | 2026-07-28 (MCP 2.0) |
Stateless execution + legacy SSE backward compatibility |
| OAuth 2.1 Metadata | /.well-known/oauth-authorization-server |
RFC 8414 / RFC 9728 discovery |
Add this snippet to your AI client settings (Claude Desktop, Cursor, Goose, Antigravity):
{
"mcpServers": {
"whisqr": {
"url": "https://whisqr.com/mcp",
"headers": {
"Accept": "application/json, text/event-stream"
}
}
}
}Whisqr exposes 9 active tools categorized by feature area. Every tool returns rich multi-payload results (text summaries, inline base64 images, and structured JSON).
Generates static PNG or SVG QR codes from raw text, URLs, or structured data payloads (WiFi, vCard, Calendar, Geo, etc.). Offers interactive resolution export and one-click copying.
data, structured_type, structured_data, error_correction (L/M/Q/H), size (64–4096), format (png/svg), print_url_meta.ui
Creates a dynamic tracked QR code with a short redirect URL (whq.at), Google Safe Browsing verification, and real-time visitor analytics. The destination URL can be changed later without reprinting the QR code.
destination_url (required), label, expires_at (ISO 8601), format, size, print_urlhttps://whq.at/:code (redirect) • https://whisqr.com/qr/:code.png (image)Updates an existing tracked link's destination URL, label, expiry timestamp, or visual format without changing the short URL or physical print code.
code (e.g. "2xK9"), destination_url, label, expires_atFetches scan counts, unique visitor IP telemetry, time-series distributions, and cohort breakdowns for any tracked QR code.
none, daily, weekly, monthly, day_of_week, hour_of_day, user, cohortjson, csv, text, markdown (executive table)Opens an interactive camera scanner session for live webcam/mobile scanning, phone handoff QR pairing, or image drag-and-drop. Responds in <50ms with instant session tokens.
ttl_minutes (1–60, default 10), label, webhook_url, auto_wait (default false)_meta.resultType: 'input_required' + MRTR task lifecycleRetrieves the decoded payload from a camera scan session once the user confirms they completed the capture.
token (session token; auto-resolves most recent if omitted)pending, completed (with decoded data), expiredDecodes QR codes from pre-existing images without human interaction. Used when an image file, base64 payload, or HTTPS URL is already provided.
image_path, image_base64, or image_urlGenerates up to 50 QR codes in a single operation. Supports structured payloads for each item, uniform error correction, and parallel rendering.
items (array of max 50 objects), format, size, error_correctionInspects a QR image non-destructively to decode data and extract technical metadata. When a URL payload is detected (including naked domain names without protocol prefixes), it automatically normalizes the URL and validates it against Google Safe Browsing and local domain rules.
image_path or image_base64safety: { safe: boolean, error?: string } report
Instead of manually assembling complex RFC-compliant syntax strings, pass structured_type and structured_data directly to generate_qr_code or batch_generate_qr_codes:
| Type | Required Fields | Optional Fields | Encoded Output Syntax |
|---|---|---|---|
wifi |
ssid, security (WPA/WEP/nopass) |
password, hidden |
WIFI:S:OfficeNet;T:WPA;P:secret123;H:false;; |
vcard |
name |
email, phone, org, title, url |
BEGIN:VCARD\nVERSION:3.0\nFN:Jane Doe\n...END:VCARD |
calendar |
summary, start (ISO), end (ISO) |
location, description |
BEGIN:VCALENDAR\n...BEGIN:VEVENT\n...END:VCALENDAR |
geo |
lat, lon |
altitude |
geo:37.7749,-122.4194 |
sms |
phone |
body |
smsto:+15551234567:Hello from Whisqr |
email |
to |
subject, body |
mailto:contact@whisqr.com?subject=Inquiry |
url |
url |
— | https://whisqr.com |
Whisqr is engineered for zero-failure execution across any client generation, terminal window, or sandbox environment.
structuredContent JSON simultaneously. If an AI host interface cannot render binary images, the Markdown text provides direct URLs (e.g. https://whisqr.com/qr/:code.png) so users can view the graphic in any browser.
_meta.ui to render rich interactive iframes with resolution sliders and clipboard tools. Non-UI clients (CLI agents, terminal runtimes) ignore _meta.ui seamlessly and receive standard text and image outputs.
Mcp-Method/Mcp-Name), and Tasks Extension (MRTR), while maintaining full fallback for legacy stateful SSE connections (/sse + /messages).
BarcodeDetector API → falls back to pure JS jsQR → falls back to in-UI file picker and drag-and-drop → falls back to mobile phone pairing QR codes for desktop users without a webcam.
Constructing reliable agent workflows requires distinguishing between spontaneous conversational flows and repeatable automated pipelines:
scan_qr_code_with_camera on Turn 1 immediately. Do not ask clarifying questions first—the scanner interface automatically handles webcam, phone pairing, and file drop. When the user confirms capture, call get_scan_session_result.
create_tracked_qr_code. Reserve generate_qr_code strictly for unmonitored offline payloads (WiFi, vCard, plain text).
create_tracked_qr_code. Print the permanent image URL (https://whisqr.com/qr/:code.png). Programmatically update the target via manage_tracked_qr_code whenever the campaign destination changes.
get_qr_scan_stats(code, group_by: "daily", format: "json") on a schedule to pipe scan timeseries and demographic breakdowns directly into your analytics data warehouse.
Drop this prompt block into your agent's system instructions to guarantee optimal tool selection and decision routing:
### Whisqr QR Code Engine Instructions
You have access to the Whisqr MCP Server for professional QR code generation, scanning, tracking, and telemetry.
Routing Rules:
1. LIVE SCANNING: If the user asks to scan, read, or decode a QR code and has not attached an image or image URL, call `scan_qr_code_with_camera` immediately on Turn 1. Present the scanner link to the user. When they confirm completion, call `get_scan_session_result` with the session token.
2. IMAGE DECODING: If an image file path, base64 payload, or image URL is already provided in the prompt, call `scan_qr_code`.
3. DYNAMIC & MARKETING QR: If the user asks for a trackable, dynamic, campaign, or analytics QR code, call `create_tracked_qr_code`. Use `get_qr_scan_stats` to inspect scan telemetry and `manage_tracked_qr_code` to update destinations.
4. STATIC PAYLOADS: Use `generate_qr_code` for unmonitored static payloads (WiFi, vCard, Calendar, SMS, Email, Geo, raw text). Pass `structured_type` and `structured_data` rather than formatting raw strings manually.
5. BATCH OPERATIONS: For multiple codes in one turn, use `batch_generate_qr_codes` (up to 50 items).
6. DIRECT ASSET URLS: You can link directly to rendered QR images using `https://whisqr.com/qr/{code}.png` or `https://whisqr.com/qr/{code}.svg`.Whisqr implements multiple defense-in-depth layers to safeguard users and infrastructure: