<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0"><channel><title><![CDATA[FreeQrly]]></title><description><![CDATA[FreeQrly]]></description><link>https://freeqrly.hashnode.dev</link><generator>RSS for Node</generator><lastBuildDate>Sat, 21 Nov 2026 18:18:19 GMT</lastBuildDate><atom:link href="https://freeqrly.hashnode.dev/rss.xml" rel="self" type="application/rss+xml"/><language><![CDATA[en]]></language><ttl>60</ttl><item><title><![CDATA[I built a free QR code API + MCP server on Cloudflare Pages — here's the whole design]]></title><description><![CDATA[Most QR code generators are either ad-covered landing pages or SaaS products with a paywall behind "dynamic codes". I wanted the opposite: a generator…]]></description><link>https://freeqrly.hashnode.dev/i-built-a-free-qr-code-api-mcp-server-on-cloudflare-pages-here-s-the-whole-design</link><guid isPermaLink="true">https://freeqrly.hashnode.dev/i-built-a-free-qr-code-api-mcp-server-on-cloudflare-pages-here-s-the-whole-design</guid><category><![CDATA[mcp]]></category><category><![CDATA[api]]></category><category><![CDATA[cloudflare]]></category><category><![CDATA[Qrcode]]></category><dc:creator><![CDATA[Zane Bin]]></dc:creator><pubDate>Mon, 02 Nov 2026 11:07:28 GMT</pubDate><content:encoded><![CDATA[<p>Most QR code generators are either ad-covered landing pages or SaaS products with a paywall behind "dynamic codes". I wanted the opposite: a generator that's free, private by default, and natively callable by AI agents. So I built <a href="https://freeqrly.com">FreeQrly</a> — open source (<a href="https://github.com/BryceBin/freeqrly">BryceBin/freeqrly</a>, MIT), running entirely on Cloudflare Pages + D1.</p>
<p>Here's the architecture, including the part I think is most interesting: <strong>one shared auth/quota core serving three surfaces — web UI, REST API, and MCP.</strong></p>
<h2>The three surfaces</h2>
<p><strong>1. Static QR API — no key, no signup, CORS wide open</strong></p>
<pre><code>GET https://freeqrly.com/api/qr?data=https://example.com&amp;size=1024&amp;color=2F4A62&amp;bgcolor=ffffff&amp;margin=4&amp;ecc=M
</code></pre>
<p>Returns an SVG. <code>data</code> is required (400 with a clear error otherwise), everything else has sane defaults, input is validated (data ≤ 2000 chars, color format checked). Static codes are generated 100% in the browser on the web UI — the API just mirrors that server-side for agents and scripts.</p>
<p><strong>2. Dynamic codes — login-gated, editable after print</strong></p>
<p>Dynamic codes resolve through short <code>/q/xxxxxxx</code> links, so you can change the destination after printing and see scan stats (date / country / device / city breakdowns). Free tier: 20 codes (currently unlimited during the limited-time promotion). Login via Google, GitHub, or email+password (Turnstile-protected). The <code>/q/</code> hosted pages carry <code>noindex</code> + <code>X-Robots-Tag</code> so they never end up in search results.</p>
<p><strong>3. MCP — Streamable HTTP, no auth for static, token for dynamic</strong></p>
<pre><code>POST https://freeqrly.com/mcp
</code></pre>
<p><code>generate_qr</code> works with zero auth. Send an <code>Authorization: Bearer &lt;token&gt;</code> header and five more tools appear in <code>tools/list</code>: <code>dynamic_qr_create</code>, <code>dynamic_qr_list</code>, <code>dynamic_qr_update</code>, <code>dynamic_qr_delete</code>, <code>dynamic_qr_stats</code>.</p>
<h2>The design decision I'm happiest with</h2>
<p>The API-token flow reuses the UI's auth and quota logic instead of duplicating it:</p>
<ul>
<li>Users create tokens in the Dashboard ("API Tokens" section). Tokens start with <code>fqly_</code>, are shown exactly once, and only a SHA-256 hash is stored. Max 20 per account, revocable anytime.</li>
<li>All five dynamic-code REST endpoints (<code>POST/GET /api/codes</code>, <code>GET /api/codes/[code]/stats</code>, <code>PATCH</code>/<code>DELETE /api/codes/[code]</code>) share one module (<code>functions/_lib/codes_api.js</code>) with the UI and the MCP tools — same validation, same 20-code quota (currently unlimited during the limited-time promotion), same ownership checks. A token can't create or revoke other tokens (that requires a login session), and deleting your account wipes your tokens.</li>
<li>Quota violations return <code>403 quota_exceeded</code>; cross-user access returns <code>403</code>; revoked/unknown tokens return <code>401</code>.</li>
</ul>
<p>Because it's one code path, the three surfaces can't drift apart: what the UI enforces, the API and MCP enforce identically. I verified this end to end with a real test account in a real browser — login, token creation, REST create→list→stats→update→scan-redirect→delete, MCP tool calls, then 401s after revocation — and cleaned up all test data afterward.</p>
<h2>Publishing to the MCP ecosystem</h2>
<p>I added a <code>server.json</code> and published to the official MCP Registry as <code>io.github.BryceBin/freeqrly</code> (v1.1.0). Directories like Smithery and PulseMCP sync from the Registry, so one publish covers several. The repo also ships <code>llms.txt</code> and a <code>skills/qr-generator/SKILL.md</code> so agents can discover the API without reading docs.</p>
<h2>What's deliberately boring</h2>
<ul>
<li>No framework on the frontend for the generator core — vanilla JS, so the page stays fast and the logic stays auditable.</li>
<li>SQLite via D1 for dynamic codes and token hashes. No ORM magic; the schema is tiny.</li>
<li>Analytics: Cloudflare Web Analytics for pageviews + Analytics Engine events (<code>qr_download</code>, <code>batch_generate</code>, <code>scan_decode</code>) that I query with plain SQL.</li>
</ul>
<p>If you run an agent that needs QR codes — event badges, WiFi cards, vCards, batch generation (CSV in, ZIP out) — the static API and MCP are free with no signup: <code>https://freeqrly.com/developers/</code> has the full reference. Happy to answer questions about the token/quota design in the comments.</p>
]]></content:encoded></item></channel></rss>