Using xQR with AI Agents

Use the xQR MCP Server to let AI agents create links, generate QR codes, query analytics, and manage your workspace — all from natural language prompts.

Why Use AI Agents with xQR?

Automate Workflows

Let AI agents batch-create links, generate branded QR codes, or pull analytics reports as part of larger automation pipelines.

Natural Language Queries

Ask “which link got the most scans last week?” and get an answer without writing API calls.

Supported Clients

Client	Transport	Setup
Claude Desktop	stdio	Config file
Claude Code (CLI)	stdio	Config file
VS Code (Copilot/MCP extension)	stdio	settings.json
Cursor	stdio	Config file
Windsurf	stdio	Config file
Custom agents (Agent SDK)	stdio	Programmatic

Quick Setup

1. Get an API key — Go to Settings → Developers in your xQR dashboard and create a key with * scope

2. Configure your AI client — Add the xQR MCP server to your client’s config

3. Start chatting — Ask your AI agent to interact with your xQR workspace

Configuration by Client

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "xqr": {
      "command": "npx",
      "args": ["@xqr/mcp-server"],
      "env": {
        "XQR_API_KEY": "xqr_pk_a1b2c3d4.your_secret_here"
      }
    }
  }
}

Claude Code

Edit ~/.claude/settings.json:

{
  "mcpServers": {
    "xqr": {
      "command": "npx",
      "args": ["@xqr/mcp-server"],
      "env": {
        "XQR_API_KEY": "xqr_pk_a1b2c3d4.your_secret_here"
      }
    }
  }
}

VS Code

Add to your .vscode/settings.json:

{
  "mcp.servers": {
    "xqr": {
      "command": "npx",
      "args": ["@xqr/mcp-server"],
      "env": {
        "XQR_API_KEY": "xqr_pk_a1b2c3d4.your_secret_here"
      }
    }
  }
}

Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "xqr": {
      "command": "npx",
      "args": ["@xqr/mcp-server"],
      "env": {
        "XQR_API_KEY": "xqr_pk_a1b2c3d4.your_secret_here"
      }
    }
  }
}

Caution

Never commit API keys to version control. Use environment variables or a secrets manager in production environments.

Example Conversations

Creating links

You: Create a short link to https://example.com/black-friday with the slug “bf2026” and labels “campaign” and “q4”

Agent: Created short link https://xqr.co/bf2026 pointing to https://example.com/black-friday with labels campaign and q4.

Querying analytics

You: What are my top 5 performing links this month?

Agent: Here are your top 5 links by scan count for the last 30 days:

1. promo-spring — 2,341 scans
2. bf2026 — 1,892 scans
3. docs — 1,204 scans
4. careers — 987 scans
5. signup — 756 scans

Generating QR codes

You: Generate a QR code for https://example.com with my “brand-primary” template

Agent: Generated a QR code using the “brand-primary” template. The image has been saved as qr-brand.svg.

Bulk operations

You: Create 5 short links for these URLs: [list of URLs]

Agent: Created 5 short links. Here are the results:

1. https://xqr.co/abc123 → https://example.com/page-1
2. https://xqr.co/def456 → https://example.com/page-2 …

Building Custom Agents

Use the xQR MCP server programmatically with the Claude Agent SDK:

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

const response = await client.messages.create({
  model: "claude-sonnet-4-20250514",
  max_tokens: 1024,
  messages: [
    {
      role: "user",
      content: "Create a short link to https://example.com and get its QR code",
    },
  ],
  // MCP tools are automatically available when configured
});

Or use the REST API directly for non-MCP agent frameworks:

import httpx

class XQRAgent:
    def __init__(self, api_key: str):
        self.client = httpx.Client(
            base_url="https://xqr.co/api/v1",
            headers={"Authorization": f"Bearer {api_key}"},
        )

    def create_link(self, url: str, slug: str = None) -> dict:
        body = {"url": url}
        if slug:
            body["custom_slug"] = slug
        res = self.client.post("/links", json=body)
        res.raise_for_status()
        return res.json()["data"]

    def get_analytics(self, period: str = "30d") -> dict:
        res = self.client.get("/analytics/summary", params={"period": period})
        res.raise_for_status()
        return res.json()["data"]

Available MCP Tools

The xQR MCP server exposes 27 tools across 6 domains:

Domain	Tools	Examples
Links	7	Create, list, get, update, delete, bulk create, get QR
QR Codes	4	Generate, list/create/render templates
Analytics	6	Summary, timeseries, geography, devices, top links, link stats
Link-in-Bio	5	CRUD + publish/unpublish
Assets	4	List, get, publish, delete
Workspace	3	Info, usage, members

See the full Tools Reference for parameter details.

Tips for Effective AI Integration

1. Use descriptive labels — Help AI agents organize and find links by using meaningful labels
2. Leverage analytics queries — AI agents can identify trends and suggest optimizations
3. Batch operations — Ask the agent to create multiple links at once using the bulk endpoint
4. Template-based QR — Create branded templates once, then let agents render them repeatedly
5. Webhook automation — Combine MCP with webhooks to build event-driven AI workflows