DEV Community

QRflows
QRflows

Posted on

Smart Rules over MCP: routing QR scans by country from a Claude chat

Back in May I wrote about building an MCP server so Claude can create QR codes from chat. In the comments, Harjot Singh made a point that stuck with me: keep every tool narrow and well-described, because vague or overloaded tools get called wrong. I replied that the next thing I wanted to expose over MCP was Smart Rules — routing one printed QR code to different destinations by country, device or time — and promised to write it up once it shipped.

In that post I only showed the happy path: one sentence in chat ("send people in Spain to /es, everyone else to the homepage") becomes a create_qr call with qr_type: "smart_rules". This post is about everything under that one-liner — how the rules tool is designed so the model calls it correctly, what I got wrong first, and where the visitor's country actually comes from when someone scans.

What "Smart Rules" means here

I'm building QRflows, a dynamic QR code service. A dynamic QR code doesn't encode your final URL — it encodes a short redirect URL that you control. That's what lets you change the destination after the code is printed.

Smart Rules take that one step further: the same printed short URL sends different people to different places.

  • A visitor in Spain gets the Spanish landing page, everyone else gets English.
  • iOS goes to the App Store, Android to Google Play.
  • 08:00–12:00 shows the breakfast menu, the rest of the day shows the main menu.
  • On a specific date (an event day), the code points somewhere special.

In the web dashboard this is a rule builder. The question was: what does it look like when the "UI" is a chat with Claude?

The tool: apply_smart_rules

Here's the real input schema of the tool as the MCP server exposes it today (trimmed descriptions only):

{
  "name": "apply_smart_rules",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false,
    "required": ["qr_id", "default_url", "rules"],
    "properties": {
      "qr_id": { "type": "string", "description": "QR code ID to apply rules to" },
      "default_url": { "type": "string", "format": "uri",
        "description": "Fallback URL when no rules match" },
      "rules": {
        "type": "array",
        "description": "List of routing rules, evaluated in order",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": ["condition_type", "condition_value", "destination_url"],
          "properties": {
            "condition_type": {
              "type": "string",
              "enum": ["time_range", "country", "device", "language", "date"]
            },
            "condition_value": {
              "type": "string",
              "description": "Value, e.g. 08:00-12:00, ES, US, ios, de, 2026-05-04"
            },
            "destination_url": { "type": "string", "format": "uri" },
            "label": { "type": "string", "description": "Optional label, e.g. Breakfast menu" }
          }
        }
      }
    }
  }
}
Enter fullscreen mode Exit fullscreen mode

A few deliberate choices in there:

1. One flat list, evaluated in order. I considered nested conditions (country = ES AND device = ios). I dropped it for the MCP surface. A flat ordered list is something Claude gets right almost every time, and something a human can read back in the chat and verify at a glance. First match wins, default_url catches everything else.

2. condition_value is a string with examples, not five different typed fields. The enum on condition_type does the heavy lifting; the examples in the description (08:00-12:00, ES, ios, de, 2026-05-04) show the expected format for each type. In practice, examples in the description did more for correct calls than any amount of prose.

3. default_url is required. If no rule matches, a scan must still go somewhere. Making it required means Claude has to ask the user for a fallback instead of silently leaving one out.

4. additionalProperties: false everywhere. If the model invents a field, the call fails loudly instead of being half-applied.

Why Smart Rules is a separate QR type

This was the part I got wrong first.

My original idea was "any dynamic QR can have rules". In chat, that turned out to be confusing. A user would say "make my menu QR show breakfast in the morning" and the model would try to bolt rules onto a menu code, which in my data model is a single-destination type.

So Smart Rules became its own type, smart_rules, and the tool description says so explicitly:

Update routing rules only for QR type smart_rules. If the user asked for breakfast/lunch on a menu or url code, explain they need a smart_rules QR (create with qr_type smart_rules); this tool rejects other types.

That last sentence is not for the server — the server rejects the call anyway. It's for the model. It tells Claude what to say when the user asks for something the current code can't do, instead of retrying the call in a loop.

The create_qr tool carries the same hint from the other side:

Routing: use smart_rules for country/device/language/time/date; menu is single URL.

Same lesson Harjot pointed at: the description is part of the API. For an LLM client it's arguably the most important part.

Changing rules on a code that's already printed

Creating a geo-routed code was covered in the first post. The more realistic case is editing one that's already on 500 flyers. That's what apply_smart_rules is for — it replaces the rule list on an existing smart_rules code:

Me: The trade fair moved to Germany. Keep Spain on /es, add German visitors → /de.

Claude: (calls list_qr_codes to find the code, then apply_smart_rules)

{
  "qr_id": "123",
  "default_url": "https://example.com/en",
  "rules": [
    { "condition_type": "country", "condition_value": "ES",
      "destination_url": "https://example.com/es", "label": "Spain" },
    { "condition_type": "country", "condition_value": "Germany",
      "destination_url": "https://example.com/de", "label": "Germany" }
  ]
}
Enter fullscreen mode Exit fullscreen mode

Two things worth noticing:

  • The call carries the whole rule list. Claude sends Spain again, not just "add Germany" — so the user can read back exactly what the printed code will do before anything changes.
  • Germany instead of DE. For country rules the server accepts either an ISO code or a country name, because that's how people talk ("send Germans to the German page"). Normalizing is the server's job, not the model's.

Where the country comes from: Cloudflare

The routing decision doesn't happen in the MCP server. The MCP server (TypeScript on Cloudflare Workers) only writes the rules through the QRflows API. The redirect itself is served by the main app — Laravel — when somebody scans the code.

The app sits behind Cloudflare, so I don't run a GeoIP database at all. Cloudflare adds a CF-IPCountry header with an ISO 3166-1 alpha-2 code to every proxied request. The idea, as pseudocode:

country = header "CF-IPCountry"
for rule in qr.rules (in order):
    if rule matches (country / device / language / time / date):
        redirect to rule.destination_url
redirect to qr.default_url
Enter fullscreen mode Exit fullscreen mode

One detail: Cloudflare sends XX when the country is unknown and T1 for Tor. Neither should match a country rule or end up in your analytics as a "country" — treat them as unknown. That cleanup is on my list right now.

Two things I learned the hard way:

Don't trust the header if the origin is reachable directly. CF-IPCountry is just a request header. If someone can hit your origin server by its IP, bypassing Cloudflare, they can set any country they want. For QR routing that's mostly harmless, but the same header feeds analytics, and it's a bad habit anyway. The fix is to lock the origin down so it only accepts traffic from Cloudflare — another item I'm working through.

Your server sees Cloudflare's IP, not the visitor's. That broke my "exclude internal traffic" filter in analytics before I fixed it. That's a whole separate story (CF-Connecting-IP, real_ip in nginx) — I'll write it up next.

What I'd tell anyone exposing "rules" over MCP

  1. Flatten. Ordered list + required fallback beats a nested condition tree for an LLM client.
  2. Use enums for the "what" and examples for the "value". condition_type is an enum; condition_value has one example per type in its description.
  3. Write the description for the model, not for the docs site. Tell it what to do when the call isn't possible ("explain they need a smart_rules QR").
  4. Make the separate concept a separate type. Routing on a single-destination type was the source of most bad calls.
  5. Accept human values and normalize server-side. "Germany" and "DE" should both work.
  6. Keep the decision at the edge of your real app, not in the MCP server. The MCP server writes config; the redirect path reads it. One source of truth.

Latency, since someone asked on my llms.txt post: a single MCP call on Workers adds roughly 300–500 ms. Creating a geo-routed QR is one call, so it feels instant in chat. The slow part is never the network — it's the model deciding which tool to call, which is exactly why the descriptions matter.

Connection setup is in the first post; Smart Rules are on the Pro plan, and the API is described on the developer page.

Harjot — this one's for you. Thanks for the push in May.

I'm Ivan, I build QRflows solo. Questions about the schema or the Cloudflare part — ask in the comments, I answer all of them.

Top comments (0)