MCP server

What it does

The MCP server lets AI agents operate TurtleQR as a native capability. Your agent can create codes, read scan counts, change destinations, and export analytics without leaving the conversation. The tools proxy directly to the REST API: anything you can do in the dashboard you can do from a chat.

Supported clients: Claude Desktop, Claude.ai (via extension), Cursor, ChatGPT (via custom GPT), and any MCP-compatible client that can make HTTP POST requests.

Get an API key

The MCP server authenticates with a TurtleQR API key. Generate one in the dashboard:

1. Sign in at app.turtleqr.com.
2. Go to API keys.
3. Click Create API key. Give it a label (e.g., "Claude desktop"). Copy the token when it appears; it is shown once.

The token starts with qr_live_ (production) or qr_test_ (test workspaces).

Connect Claude Desktop

Add this block to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, or %APPDATA%Claudeclaude_desktop_config.json on Windows:

{
  "mcpServers": {
    "turtleqr": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.turtleqr.com/mcp",
        "--header",
        "Authorization:Bearer qr_live_YOUR_KEY_HERE"
      ]
    }
  }
}

Restart Claude Desktop. Try: "Create a TurtleQR code pointing to https://example.com."

The mcp-remote package bridges Claude's local stdio transport to the remote HTTP endpoint. It does not require installation; npx fetches and caches it on first run.

Connect Cursor

Add to your Cursor MCP config at ~/.cursor/mcp.json (create the file if it does not exist):

{
  "mcpServers": {
    "turtleqr": {
      "url": "https://mcp.turtleqr.com/mcp",
      "headers": {
        "Authorization": "Bearer qr_live_YOUR_KEY_HERE"
      }
    }
  }
}

Cursor supports direct HTTP transports without mcp-remote. Reload the Cursor window after saving. You should see TurtleQR listed under Settings > MCP.

Connect ChatGPT (custom GPT)

ChatGPT does not yet support the MCP transport natively, but you can expose the same tools via a custom GPT action that calls the MCP endpoint directly.

1. In ChatGPT, open Explore GPTs > Create.
2. Go to Configure > Actions > Add action.
3. Set the server URL to https://mcp.turtleqr.com/mcp.
4. Set the authentication type to API Key, key in header, header name Authorization, value Bearer qr_live_YOUR_KEY_HERE.
5. Import the OpenAPI schema from mcp.turtleqr.com/openapi.json.

The custom GPT can then call any of the 12 tools directly from the chat.

Generic MCP client (JSON-RPC curl)

The protocol is JSON-RPC 2.0 over HTTP POST to https://mcp.turtleqr.com/mcp. No special client is required for testing.

# List available tools (no auth required for tools/list)
curl -s -X POST https://mcp.turtleqr.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | jq

# Confirm authentication and workspace scope
curl -s -X POST https://mcp.turtleqr.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer qr_live_YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": { "name": "whoami", "arguments": {} }
  }' | jq

# Create a QR code
curl -s -X POST https://mcp.turtleqr.com/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer qr_live_YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "create_qr",
      "arguments": {
        "targetUrl": "https://example.com/autumn-menu",
        "slug": "autumn-menu"
      }
    }
  }' | jq

Tool results are returned in the standard MCP content envelope: {"content":[{"type":"text","text":"..."}]}. Error results also include "isError": true.

Tool reference

12 tools are available. All tool calls require a valid Bearer token in the Authorization header except as noted.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_qr",
    "arguments": {
      "targetUrl": "https://myshop.com/summer-sale",
      "slug": "summer-sale",
      "fallbackUrl": "https://myshop.com/"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_qr_codes", "arguments": {} }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "update_qr_target",
    "arguments": {
      "id": "code_abc123",
      "targetUrl": "https://myshop.com/new-page"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_qr_analytics",
    "arguments": { "codeId": "code_abc123", "range": "7d" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "bulk_create_qr_codes",
    "arguments": {
      "codes": [
        { "targetUrl": "https://example.com/page-1", "label": "Page 1" },
        { "targetUrl": "https://example.com/page-2", "label": "Page 2" }
      ]
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "whoami", "arguments": {} }
}

Troubleshooting

What is next for MCP

OAuth 2.1 (PKCE) is live for Claude.ai web. Use the /oauth/authorize flow at auth.turtleqr.com to grant access without sharing an API key. Self-hosted MCP clients (e.g. Cursor) can use a workspace API key via the Authorization: Bearer qr_live_* header.

Additional planned tools: visual customization (logo, color, frame), folder management, routing rule creation, and webhook management.