I launched a SaaS product called QRflows — a dynamic QR code platform. Two months in, I decided to build an MCP (Model Context Protocol) server for it. Now Claude can create, update, and track QR codes directly from a chat conversation, without touching a dashboard.
This post is about why I built it, how it works technically, and what I learned along the way.
MCP is Anthropic's open protocol that lets AI assistants like Claude connect to external services. Think of it like a USB standard — any MCP-compatible server can plug into Claude and give it new tools.
For QRflows, this meant Claude could become a QR code manager. A user types "create a QR code for my restaurant menu that routes to the breakfast version before 11am and the dinner version after" — and it just happens.
That's a real use case for my product's Smart Rules feature. Before MCP, the user had to go to the dashboard, create a QR, set up routing rules manually. With MCP, the whole thing is one sentence in chat.
Here's what it looks like in practice — Claude fetching stats across all QR codes for a full month:
QRflows itself runs on Laravel + React. But the MCP server is completely separate:
wrangler deploy
)@modelcontextprotocol/sdk
The server lives at mcp.qrflows.app
and communicates via HTTP (Streamable HTTP transport).
The MCP server exposes 10 tools to Claude:
create_qr — create a new QR code (16 types supported)
update_qr_url — change the destination URL without reprinting
update_qr — update any QR fields
update_wifi_qr — update WiFi credentials
list_qr_codes — list all QR codes in the account
get_qr — get details for a specific QR
get_qr_stats — get scan analytics
delete_qr — delete a QR code
apply_smart_rules — set geo/device/time routing rules
get_account_usage — check plan limits and usage
Each tool has proper MCP annotations:
server.tool(
"create_qr",
"Create a new dynamic QR code in QRflows (16 QR types).",
{
name: z.string().describe("Human-readable name for the QR code"),
qr_type: z.enum(qrTypes).default("url"),
content: z.record(z.unknown()).describe(
"Payload by type, e.g. url: { url }; smart_rules: { default_url, rules: [...] }"
),
},
{
title: "Create QR Code",
readOnlyHint: false,
destructiveHint: false,
idempotentHint: false,
openWorldHint: true,
},
async (input) => {
const api = new QrflowsApi(env, token);
return toolSuccessWithUserMarkdownLeadingJson(
await api.createQr(input)
);
}
);
The readOnlyHint
, destructiveHint
, and idempotentHint
annotations are important — they tell Claude how to handle each tool safely. Read-only tools like list_qr_codes
get readOnlyHint: true
. The delete_qr
tool gets destructiveHint: true
so Claude knows to be careful.
Anthropic requires remote MCP servers to implement OAuth 2.0. This makes sense — you don't want Claude connecting to a QR service without the user explicitly authorizing it.
The flow looks like this:
mcp.qrflows.app/auth/authorize
The trickiest part was the token refresh logic. Cloudflare Workers have no persistent state between requests, so I use KV with TTL to store tokens and refresh them automatically.
// Store in KV with expiry
await env.OAUTH_STORE.put(
`token:${userId}`,
JSON.stringify({ access_token, refresh_token, expires_at }),
{ expirationTtl: 3600 }
);
The most interesting use case is Smart Rules — QRflows' geo/device/time routing feature.
A user can tell Claude:
"Create a QR code that sends people in Spain to qrflows.app/es and everyone else to qrflows.app"
Claude translates this into a create_qr
call with qr_type: "smart_rules"
and the right routing config:
{
"qr_type": "smart_rules",
"content": {
"default_url": "https://qrflows.app",
"rules": [
{
"condition_type": "country",
"condition_value": "ES",
"destination_url": "https://qrflows.app/es",
"label": "Spain"
}
]
}
}
This is where natural language + structured API really clicks. Describing routing rules in JSON is annoying. Describing them in English is natural. Claude handles the translation.
And when you ask for stats on a specific QR, Claude returns a full analytics breakdown inline:
One thing I got wrong initially: my tools returned raw JSON. Claude would display it as a code block and the conversation felt clunky.
The fix was to make tools return a markdown block first, then the JSON for Claude's internal use, separated by a delimiter:
Here's your QR code for the restaurant menu:
**Download:** [PNG](https://...) | [SVG](https://...)
**Destination:** https://your-menu.com
**Type:** Menu QR
---
qrflows_tool_json
{ ... raw json ... }
Claude surfaces the markdown naturally in conversation. The JSON after the delimiter is parsed by Claude if it needs to chain tool calls.
When listing all QR codes, Claude also renders a full breakdown table automatically:
The MCP server is live at https://mcp.qrflows.app/mcp
.
To connect in Claude (claude.ai):
https://mcp.qrflows.app/mcp
Then try:
Create a WiFi QR code for my office. SSID: OfficeWifi, password: correct-horse-battery
Show me scan stats for all my QR codes from last week
Update the URL on my "Menu QR" to point to https://myrestaurant.com/menu-v2
I've submitted QRflows to Anthropic's official MCP connector directory. The review is ongoing — once approved, QRflows will appear in the built-in connector list inside Claude without users needing to add a custom URL.
If you're building an MCP server and wondering about the submission process: there's a Google Form linked from the Anthropic docs. The technical requirements include Streamable HTTP transport, OAuth 2.0, and proper tool annotations. The review takes a few weeks.
Start with OAuth earlier. I built all 10 tools first, then retrofitted OAuth. That was backwards. OAuth shapes your entire architecture — do it first.
Test with real Claude conversations, not just the MCP inspector. The inspector tells you if tools work. Only real conversations tell you if Claude uses them correctly. Claude sometimes misinterprets tool descriptions in ways the inspector won't catch.
Keep tool descriptions conversational. I initially wrote terse, developer-style descriptions. Claude is better at using tools described the way you'd explain them to a colleague.
https://mcp.qrflows.app/mcp
Built this in about 2 weeks alongside the main product. Happy to answer questions about the implementation — drop them in the comments.