How I Built an MCP Server So Claude Can Create QR Codes F...

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.

What is MCP and why did I care

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:

The stack

QRflows itself runs on Laravel + React. But the MCP server is completely separate:

Runtime: Cloudflare Workers (deployed with wrangler deploy)
Language: TypeScript
MCP SDK: @modelcontextprotocol/sdk
Auth: OAuth 2.0 (required by Anthropic for remote MCP servers)
Storage: Cloudflare KV for OAuth token store

The server lives at mcp.qrflows.app and communicates via HTTP (Streamable HTTP transport).

The tools I implemented

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.

OAuth was the hard part

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:

User adds QRflows as a connector in Claude
Claude redirects to mcp.qrflows.app/auth/authorize
User logs in with their QRflows credentials
OAuth token is issued and stored in Cloudflare KV
All subsequent MCP tool calls use that token to hit the QRflows API

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 }
);

Smart Rules through chat

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:

Response format: markdown first

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:

![QR Code](https://qrflows.app/qr/abc123.png)

**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:

How to connect it right now

The MCP server is live at https://mcp.qrflows.app/mcp.

To connect in Claude (claude.ai):

Go to Settings → Connectors
Click Add custom connector
Enter https://mcp.qrflows.app/mcp
Authorize with your QRflows account

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

Submitting to Anthropic's connector directory

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.

What I'd do differently

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.

推荐订阅源

DEV Community