QR for Agent Documentation

Everything you need to create, update, and track dynamic QR codes -- via MCP or REST API.

Quick Start

From zero to your first QR code in 30 seconds.

Install the MCP server

$ npx qr-for-agent

Works with Claude Desktop, Cursor, and any MCP-compatible client.

Get your API key

Get Your API Key

Your key follows the format qr_ + 32-character random string. Keep it in your environment variables.

Create your first QR code

Ask your agent:

Prompt

Create a dynamic QR code for https://example.com

Or call the REST API directly:

Request

$ curl -X POST https://api.qragentcore.com/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY_HERE" \
  -d '{"target_url": "https://example.com", "label": "My first QR"}'

Response

{
  "id": 1,
  "short_id": "wkQ5W-fm",
  "short_url": "https://api.qragentcore.com/r/wkQ5W-fm",
  "target_url": "https://example.com",
  "label": "My first QR",
  "format": "svg",
  "image_data": "<svg>...</svg>",
  "created_at": "2026-02-24T10:00:00.000Z"
}

That's it. One command, one API call, one QR code. The short URL redirects to your target -- and you can change the target later without regenerating the image.

MCP Setup

QR for Agent ships as a standalone MCP server on npm. One package, 6 tools, 3 dependencies.

Claude Desktop

Add to your claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qragentcore.com"
      }
    }
  }
}

Restart Claude Desktop. Your agent now has 6 QR code tools available.

Cursor

Add to .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "qr-for-agent": {
      "command": "npx",
      "args": ["-y", "qr-for-agent"],
      "env": {
        "API_KEY": "your-api-key",
        "BASE_URL": "https://api.qragentcore.com"
      }
    }
  }
}

Reload the window. The tools appear in Cursor's MCP panel.

Any MCP client

The server runs via npx qr-for-agent and communicates over stdio. Any client that supports the MCP standard can use it. Set API_KEY and BASE_URL as environment variables.

API Reference

All /api/* endpoints require an X-API-Key header. Public endpoints (/r/*, /i/*) don't require auth.

QR Code Endpoints

Method	Path	Description	Auth
POST	/api/qr	Create a new dynamic QR code	Yes
GET	/api/qr	List all QR codes (paginated)	Yes
GET	/api/qr/:shortId	Get QR code details	Yes
PATCH	/api/qr/:shortId	Update target URL or label	Yes
DELETE	/api/qr/:shortId	Delete QR code and analytics	Yes
GET	/api/qr/:shortId/image	Download QR image	Yes

Analytics Endpoint

Method	Path	Description	Auth
GET	/api/analytics/:shortId	Scan count and recent events	Yes

Public Endpoints

Method	Path	Description	Auth
GET	/r/:shortId	Redirect to target URL (records scan)	No
GET	/i/:shortId	Serve QR image (cacheable)	No
GET	/health	Health check	No
GET	/documentation	Swagger UI (OpenAPI docs)	No

POST /api/qr -- Create a QR code

Request body:

Parameter	Type	Required	Default	Description
target_url	string	Yes	--	The destination URL. Must be a fully-qualified absolute URL.
label	string	No	null	A human-readable label for organizing QR codes.
format	string	No	"svg"	Image format: `"svg"` (recommended) or `"png"`.

Request

$ curl -X POST https://api.qragentcore.com/api/qr \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY" \
  -d '{
    "target_url": "https://conf.example.com/2026",
    "label": "Conference landing page",
    "format": "svg"
  }'

Response (201):

Response

{
  "id": 1,
  "short_id": "wkQ5W-fm",
  "short_url": "https://api.qragentcore.com/r/wkQ5W-fm",
  "target_url": "https://conf.example.com/2026",
  "label": "Conference landing page",
  "format": "svg",
  "image_data": "<svg>...</svg>",
  "created_at": "2026-02-24T10:00:00.000Z"
}

PATCH /api/qr/:shortId -- Update destination

The QR image stays the same. Only the redirect target changes. This is the core dynamic link feature.

Request

$ curl -X PATCH https://api.qragentcore.com/api/qr/wkQ5W-fm \
  -H "Content-Type: application/json" \
  -H "X-API-Key: qr_YOUR_KEY" \
  -d '{"target_url": "https://new-destination.com"}'

GET /api/qr -- List QR codes

Query parameters:

Parameter	Type	Default	Description
limit	integer	20	Max results (1-100).
offset	integer	0	Number of records to skip.

Request

$ curl https://api.qragentcore.com/api/qr?limit=10&offset=0 \
  -H "X-API-Key: qr_YOUR_KEY"

GET /api/analytics/:shortId -- Scan analytics

Returns total scan count and the 50 most recent scan events.

Request

$ curl https://api.qragentcore.com/api/analytics/wkQ5W-fm \
  -H "X-API-Key: qr_YOUR_KEY"

Response:

Response

{
  "short_id": "wkQ5W-fm",
  "total_scans": 142,
  "recent_scans": [
    {
      "scanned_at": "2026-02-24T14:32:00.000Z",
      "user_agent": "Mozilla/5.0 ...",
      "referer": null
    }
  ]
}

DELETE /api/qr/:shortId -- Delete a QR code

Permanently removes the QR code and all associated scan analytics. The short URL stops working immediately. This cannot be undone.

Request

$ curl -X DELETE https://api.qragentcore.com/api/qr/wkQ5W-fm \
  -H "X-API-Key: qr_YOUR_KEY"

Authentication

All /api/* endpoints require an X-API-Key header.

Format: qr_ + 32-character random string
Multi-tenant: each API key only sees its own QR codes
Isolation: no data leaks between API keys -- build agents for multiple clients safely

MCP Tools

6 tools. That's it. No context bloat, no "too many tools" problem. Each tool maps 1:1 to a REST endpoint.

Tool	Parameters	Description
create_qr_code	`target_url` (string, required), `label` (string, optional), `format` ("svg" or "png", default "svg")	Create a new dynamic QR code. Returns the QR image and short URL.
get_qr_code	`short_id` (string, required)	Retrieve details and metadata for an existing QR code.
update_qr_destination	`short_id` (string, required), `target_url` (string, required), `label` (string, optional)	Change where a QR code redirects without regenerating the image.
list_qr_codes	`limit` (number, default 20), `offset` (number, default 0)	List all QR codes with pagination.
delete_qr_code	`short_id` (string, required)	Permanently delete a QR code and its scan analytics.
get_qr_analytics	`short_id` (string, required)	Get total scan count and recent scan events with timestamps.

Tool details

create_qr_code

Creates a new managed QR code. The QR code points to a short URL that redirects to your target URL. You can change the target URL later without regenerating the QR image. Returns the QR image data (SVG or PNG) and the short URL.

update_qr_destination

This is the key "dynamic link" feature: the QR image stays the same, but scanning it goes to the new URL. Use it to update campaigns, fix broken links, or A/B test landing pages.

get_qr_analytics

Returns aggregated scan statistics and recent scan events. Your agent can pull analytics and adjust campaigns without opening a dashboard.

Environment Variables

MCP Server (qr-for-agent)

Variable	Required	Default	Description
API_KEY	Yes	--	Your QR for Agent API key. Format: `qr_` + 32 chars.
BASE_URL	No	http://localhost:3100	The URL of your QR for Agent instance. Use `https://api.qragentcore.com` for the hosted service.

Self-Hosted Server

Variable	Required	Default	Description
PORT	No	3100	HTTP port.
HOST	No	0.0.0.0	Bind address.
BASE_URL	No	http://localhost:3100	Public URL used in generated short URLs. Set this to your domain.
DATABASE_URL	No	./data/qr-agent.db	SQLite file path.
SHORT_ID_LENGTH	No	8	Length of generated short IDs.

Self-Hosting

QR for Agent is open source and MIT-licensed. Run it on your own infrastructure or use the hosted service. Your call.

Docker

$ git clone https://github.com/benswel/qr-agent-core.git
$ cd qr-agent-core
$ docker compose up -d

The database is persisted in a Docker volume. Your server runs at http://localhost:3100.

On first startup, an API key is auto-generated and printed to the console. Use docker compose logs to retrieve it.

docker-compose.yml:

docker-compose.yml

services:
  qr-agent-core:
    build: .
    ports:
      - "3100:3100"
    volumes:
      - qr-data:/app/data
    environment:
      - PORT=3100
      - HOST=0.0.0.0
      - BASE_URL=https://your-domain.com
      - DATABASE_URL=/app/data/qr-agent.db
    restart: unless-stopped

volumes:
  qr-data:

Railway

The project includes railway.toml and a multi-stage Dockerfile. Deploy in three steps:

Fork the repo on GitHub
Connect it to Railway
Railway builds and deploys automatically with health checks on /health

Set BASE_URL to your Railway domain in the environment variables.

Without Docker

$ git clone https://github.com/benswel/qr-agent-core.git
$ cd qr-agent-core
$ npm install
$ npm run dev

On first startup, an API key is auto-generated and printed to the console.

Managing API keys:

$ npm run key:create "my-label"   # Create a new API key
$ npm run key:list                 # List all API keys

Teams keep rebuilding small but critical utilities -- QR codes, short URLs, tokens -- over and over again. We built it once, correctly, and opened the source.

View on GitHub

Start building

Free tier. Full API access. No credit card.

$ npx qr-for-agent

Get Your API Key View on GitHub

Questions? Open an issue on GitHub or check the OpenAPI docs (Swagger UI).