QRX

Art QR codes that always scan.

QRX makes branded, print-ready QR codes for posters, menus, packaging and signage. Describe the look you want and give it a link: QRX paints the code into artwork, checks that it decodes before handing it over, and points it at a hosted short link, https://qrx.to/<id> on qrx.codes, that you can re-point later on a paid plan. This repository connects QRX to Claude, ChatGPT, Cursor, VS Code and other MCP clients through the remote server at https://qrx.codes/mcp.

Listed in the official MCP Registry as codes.qrx/mcp.

_{The QRX logo is a QRX code. Point your phone at it.}

What you can do

Make a code: "Make a QR code for https://example.com/menu that looks like a watercolour café street."
Check on it: generation usually takes under a minute; the agent waits for it and returns the image and short link.
Find old codes: list the codes on your account, newest first.
Re-point a code: send an existing printed code to a new link, with no reprint (on a paid plan).
Check your allowance: see how many codes you have left today.

Connection details


Server URL	`https://qrx.codes/mcp`
Transport	Streamable HTTP (stateless)
Auth	Required to connect. Sign in with your QRX account (MCP authorization, OAuth 2.1); clients that support it need only the URL. The authorization server is `https://clerk.qrx.codes` (dynamic client registration or client ID metadata documents, PKCE S256, refresh tokens); scopes `qrx:read qrx:generate`
Auth with an API key	`Authorization: Bearer qrx_…` (preferred), or `X-API-Key: qrx_…` for clients that can't add the `Bearer` prefix. If both are sent, `Authorization` wins. For clients without sign-in, scripts and CI
Without auth	Every request, including `initialize`, answers `401` with a `WWW-Authenticate` header pointing at `https://qrx.codes/.well-known/oauth-protected-resource/mcp`, so the client asks you to sign in as soon as it connects
Public tool list	`https://qrx.codes/.well-known/mcp/server-card.json`
Docs	qrx.codes/developers/mcp (public: server URL, client set-up, tools, limits, privacy)

Sign in or use an API key

Every client below that takes a URL signs in with your QRX account: add the URL, then sign in (free) when the client asks as it connects. There is nothing to copy or keep secret.

For clients that only run local servers, and for scripts and CI, use an API key. Any client below can use one instead of signing in:

Sign in at qrx.codes (free).
Open qrx.codes/developers/keys and create a key. It starts with qrx_.

Keep it secret. The examples below read it from an environment variable called QRX_API_KEY wherever the client allows that:

server.ts

# macOS / Linux
export QRX_API_KEY="qrx_live_…"

powershell

# Windows PowerShell (current user, persistent)
[Environment]::SetEnvironmentVariable("QRX_API_KEY", "qrx_live_…", "User")

Revoke a key at any time from the same page.

Install

Claude Code

Option A: plugin (MCP server, the QRX skill and the code card)

text

/plugin marketplace add qrxcodes/qrx-mcp
/plugin install qrx@qrx

Then run /mcp, select qrx and sign in to QRX. The plugin also adds the qrx skill, which teaches Claude how to write good art prompts, wait for the code and prepare it for print.

The plugin also shows each finished code in the transcript, under the QRX tool call: its picture, the short link it scans to and a link to its QRX page, with a line while the code is still being painted. It is a mod, so it draws in the terminal (Claude Code 2.1.287 or later) and the Desktop app's Code tab; it fetches the picture with curl. Terminals with kitty graphics (kitty, Ghostty) show the full picture; other terminals show it in coloured character cells, with a link to the full-quality image.

Option B: MCP server only

Terminal

claude mcp add --transport http qrx https://qrx.codes/mcp --scope user

Then run /mcp, select qrx and sign in. Or commit this to a project's .mcp.json so the whole team gets it (each person signs in to their own account):

config.json

{
  "mcpServers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp"
    }
  }
}

With an API key instead (for example with claude -p or in CI):

Terminal

claude mcp add --transport http qrx https://qrx.codes/mcp \
  --header "Authorization: Bearer $QRX_API_KEY" --scope user

A configured Authorization header replaces sign-in; remove it to sign in instead.

Claude (claude.ai and Claude Desktop): custom connector

Claude Desktop uses the same connector settings as claude.ai; you don't edit claude_desktop_config.json for a remote server.

Open Customize → Connectors, select + Add, then Add custom connector. On Team and Enterprise, an Owner adds it under Organization settings → Connectors first, and each member then selects Connect.
Name: QRX. URL: https://qrx.codes/mcp.
Authentication: Sign in now, then sign in to QRX when Claude asks.
Save, then turn QRX on in a chat from the connectors menu.

With an API key instead, choose No sign-in and add Authorization with the value Bearer qrx_live_… under Request headers (where your organisation has request headers). Authentication can't be changed after saving; remove the connector and add it again.

Free Claude plans can add one custom connector.

ChatGPT

Open chatgpt.com/plugins on the web, select +, then Add custom MCP server.
Name: QRX. Server URL: https://qrx.codes/mcp.
Authentication: OAuth. Accept the risk warning and select Create as a plugin.
Sign in to QRX when ChatGPT asks.

ChatGPT's custom MCP servers don't take API keys. Workspace admins can restrict custom MCP servers on Business and Enterprise plans.

Cursor

Use the Install in Cursor button above, or add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

config.json

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

Cursor opens a browser to sign in to QRX when it connects.

With an API key instead:

config.json

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer ${env:QRX_API_KEY}" }
    }
  }
}

VS Code (GitHub Copilot)

Use the Install in VS Code button above, or add this to .vscode/mcp.json:

config.json

{
  "servers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp"
    }
  }
}

From a terminal:

bash

code --add-mcp '{"name":"qrx","type":"http","url":"https://qrx.codes/mcp"}'

VS Code opens a browser to sign in to QRX when it connects.

With an API key instead (VS Code asks for it and stores it securely):

config.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qrx-api-key",
      "description": "QRX API key (starts with qrx_)",
      "password": true
    }
  ],
  "servers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer ${input:qrx-api-key}" }
    }
  }
}

Windsurf / Devin Desktop

Edit mcp_config.json (macOS/Linux ~/.config/devin/mcp_config.json, Windows %APPDATA%\devin\mcp_config.json; older Windsurf installs use ~/.codeium/windsurf/mcp_config.json):

config.json

{
  "mcpServers": {
    "qrx": {
      "serverUrl": "https://qrx.codes/mcp"
    }
  }
}

Note the key is serverUrl, not url. Windsurf asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer ${env:QRX_API_KEY}" }.

Cline

Open MCP Servers → Configure MCP Servers and add to cline_mcp_settings.json:

config.json

{
  "mcpServers": {
    "qrx": {
      "type": "streamableHttp",
      "url": "https://qrx.codes/mcp",
      "disabled": false,
      "autoApprove": ["list_styles", "get_qr_code", "list_qr_codes", "get_account", "get_profile"]
    }
  }
}

Cline asks you to sign in to QRX when it connects. In the Cline CLI, run cline mcp, choose qrx and Authorize OAuth. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }.

Zed

Add to settings.json:

config.json

{
  "context_servers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

Zed asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }; Zed then skips sign-in.

Goose

Run goose configure → Add Extension → Remote Extension (Streamable HTTP) and enter https://qrx.codes/mcp. Or edit config.yaml (macOS/Linux ~/.config/goose/config.yaml, Windows %APPDATA%\Block\goose\config\config.yaml):

yaml

extensions:
  qrx:
    name: qrx
    type: streamable_http
    enabled: true
    uri: https://qrx.codes/mcp
    timeout: 300

Goose opens your browser to sign in to QRX when it connects. With an API key instead, add the header Authorization: Bearer qrx_live_… (headers: in config.yaml).

OpenAI Codex CLI

bash

codex mcp add qrx --url https://qrx.codes/mcp

Codex finds QRX's sign-in and opens your browser. Run codex mcp login qrx to sign in again later. The entry in ~/.codex/config.toml is just:

toml

[mcp_servers.qrx]
url = "https://qrx.codes/mcp"

With an API key instead, add bearer_token_env_var = "QRX_API_KEY" to that entry.

Gemini CLI

bash

gemini mcp add --transport http -s user qrx https://qrx.codes/mcp

Gemini CLI opens your browser to sign in to QRX when it connects; /mcp auth qrx signs in again later. Or in ~/.gemini/settings.json (note httpUrl, which selects Streamable HTTP):

config.json

{
  "mcpServers": {
    "qrx": {
      "httpUrl": "https://qrx.codes/mcp"
    }
  }
}

With an API key instead:

bash

gemini mcp add --transport http -s user --header "Authorization: Bearer $QRX_API_KEY" qrx https://qrx.codes/mcp

LM Studio

In the Program tab, choose Install → Edit mcp.json and add:

config.json

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

LM Studio asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }.

Agent Skills (any compatible agent)

The skills/qrx folder follows the Agent Skills standard, so the same skill works in Codex, Gemini CLI, GitHub Copilot, Cursor, Goose and others. Install it with the cross-agent installer:

Terminal

npx skills add qrxcodes/qrx-mcp

The skill expects the QRX MCP server to be connected (see your client above), or a QRX_API_KEY for the REST API.

Gemini CLI extension

bash

gemini extensions install https://github.com/qrxcodes/qrx-mcp

Gemini CLI opens your browser to sign in to QRX when it connects; /mcp auth qrx signs in again later.

Any other MCP client

Clients that support MCP authorization need only https://qrx.codes/mcp: the server answers 401 until you sign in, so they ask when they connect. Otherwise point a Streamable HTTP client at the URL and send Authorization: Bearer qrx_… (or X-API-Key: qrx_…). Clients that only run local stdio servers can use @qrxcodes/mcp, which forwards to the same server with your API key:

config.json

{
  "mcpServers": {
    "qrx": {
      "command": "npx",
      "args": ["-y", "@qrxcodes/mcp"],
      "env": { "QRX_API_KEY": "qrx_live_…" }
    }
  }
}

Tools

Connecting needs sign-in or an API key. The tool list is public at https://qrx.codes/.well-known/mcp/server-card.json.

Tool	What it does	Read-only
`generate_qr_code`	Starts a new art QR code from a prompt and a link. Returns the code's id straight away.	No
`vary_qr_code`	Makes a new code from one of your codes with a change to its picture, such as "more trees". The new code has its own short link to the same destination; the original doesn't change.	No
`get_qr_code`	Gets a code's status, image and short link. Waits up to `wait` seconds (0 to 25, default 25) for a code that's still being painted.	Yes
`list_qr_codes`	Lists your codes, newest first, a page at a time (`limit` 1 to 100, default 20; pass `nextCursor` as `cursor`).	Yes
`change_qr_code_destination`	Points an existing link code at a new absolute http or https URL (on a paid plan). The printed code keeps working. Marked destructive, because it replaces the old destination.	No
`get_account`	Shows your plan, how many codes are left today, when the count resets and what the account can do.	Yes
`get_profile`	Shows which QRX account is connected.	Yes
`list_styles`	Lists the looks you can pass to `generate_qr_code`.	Yes

In clients that show interactive views (MCP Apps), such as Claude, the code also appears in a card that fills in when it is ready.

Example prompts

"Make a QR code for https://example.com/menu that looks like a watercolour street of cafés."
"Design a QR code for our wedding RSVP page, https://example.com/rsvp, as eucalyptus leaves and gold foil on cream paper."
"I need a QR code for a gig poster that opens https://example.com/tickets. Neon synthwave city at night."
"Show me the styles QRX has, then make a code for https://example.com in the one that best suits a bakery."
"List my QR codes from this week and give me the short links."
"The flyer code we printed last month should now open https://example.com/spring-sale instead."
"How many QR codes can I still make today?"
"Make three variations of a QR code for https://example.com/shop with a Japanese woodblock wave, and tell me which scans are verified."

How generation works

generate_qr_code returns within a few seconds with an id and status: processing. The artwork usually takes under a minute on a GPU.
get_qr_code then waits for up to 25 seconds per call (wait, 0–25). Agents call it again until the status is succeeded (or failed). In MCP Apps clients the card fills in with the image when it's ready.
A finished code includes the image URL, the short link it encodes (shortUrl: https://qrx.to/<id> on qrx.codes) and the destination it redirects to. Every code is decoded before it's marked succeeded. A code's id and short link never change.
Each code you start counts against your plan, even if you don't keep the result.

Plans and limits

A free account has a daily allowance of codes; a paid plan has more, and lets you re-point links. Current plans are at https://qrx.codes/upgrade.

The API, the MCP server and the website share one allowance. Each key is also rate limited (30 requests a minute and 6 new codes per 10 seconds). If you hit a limit the tool returns an error; get_account shows what is left and when the daily count resets. Limits: qrx.codes/developers.

What this repository contains

Path	For
`.claude-plugin/plugin.json`, `.claude-plugin/marketplace.json`, `.mcp.json`	Claude Code plugin and its marketplace (`/plugin marketplace add qrxcodes/qrx-mcp`)
`skills/qrx/`	The `qrx` skill (Agent Skills standard): prompting, waiting for the code, print checks
`gemini-extension.json`, `GEMINI.md`	Gemini CLI extension
`server.json`	The entry for the official MCP Registry
`glama.json`	Glama maintainer claim
`llms-install.md`	Step-by-step set-up written for AI agents (Cline and others)

None of these files run code on your machine. They only point your client at https://qrx.codes/mcp.

Data and network use

Connecting to https://qrx.codes/mcp needs sign-in or an API key; without one the server answers 401. Clients send requests only to https://qrx.codes/mcp (and, when the skill falls back to the REST API, to https://qrx.codes/v1). Each request carries your sign-in token or API key and the prompt, destination link and style you asked for. Signing in goes through QRX's sign-in service at https://clerk.qrx.codes. A finished code's imageUrl is on https://qrx.codes/media/, which redirects to QRX's image CDN.

Privacy, terms and support

Privacy: https://qrx.codes/privacy
Terms: https://qrx.codes/terms
Support: https://qrx.codes/developers or hello@qrx.codes
API docs: qrx.codes/developers; MCP server: qrx.codes/developers/mcp; for agents: llms.txt and the OpenAPI document. No key needed to read them.

QRX stores the prompts, links and images you create so they appear in your account. It doesn't read your chat history; it only sees the arguments the client sends to its tools.

Licence

The configuration files, skill and documentation in this repository are released under the MIT licence. The QRX service itself is a hosted product, governed by the QRX terms.