Manage QR Codes via Scanova API

Scanova MCP Server

A Model Context Protocol (MCP) server for managing your Scanova QR code platform using the Scanova API. This server provides tools for QR code creation, design, and lifecycle management; folder organization; lead-capture forms and lead lists; analytics exports; and account user administration, through MCP-compatible IDEs like Cursor, VS Code, and Claude Desktop.

Features

• ✅ QR Codes: Create, list, retrieve, update, activate/deactivate, and delete QR codes; download them as PNG/JPG/PDF/SVG/EPS or as print-ready PDFs; and browse QR categories
• ✅ QR Design: Customize QR code visuals - patterns, eye shapes, frames, gradients, and error correction
• ✅ Folders: Create, list, update, and delete folders, and move or unassign QR codes between them
• ✅ Forms & Lead Capture: List, retrieve, update, and delete lead-capture forms and lead lists, and attach or detach either from a QR code
• ✅ Analytics: Pull account-level usage stats and per-QR performance metrics, and export analytics reports or raw scan logs
• ✅ Account Administration: List users and roles, invite or remove users, and update user role assignments
• ✅ Documentation Bridge: Query Scanova's docs via a live bridge to the Scanova docs MCP server

Prerequisites

• Scanova API key (get one from https://app.scanova.io/)
• MCP-compatible IDE (Cursor, VS Code, Claude Desktop, etc.)

Quick Setup

Step 1: Get Your Scanova API Key

1. Visit https://app.scanova.io/
2. Sign up or log in to your account
3. Navigate to API settings [https://app.scanova.io/settings/api] and generate your API key.

Step 2: Configure Your IDE

Add the following configuration to your IDE's MCP settings:

For Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http",
      "url": "https://mcp.scanova.io/mcp",
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

For VS Code (~/.vscode/mcp.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http", 
      "url": "https://mcp.scanova.io/mcp",
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http",
      "url": "https://mcp.scanova.io/mcp", 
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

Tools

82 tools. Type is the tool's MCP annotation: read-only, write (only adds), or destructive (can change or switch off something live - hosts should confirm first).

Documentation

Categories & validation

QR code design

QR codes

Folders

Forms

Lead lists (legacy)

Analytics

Account & billing

Team

Custom domains

Bulk operations

Media

Integrations

Conversion tracking

Landing pages

Pages are written in the page builder's block format, so they open at app.scanova.io and can be edited there. Blocks are checked against Scanova's own schemas before saving; refresh them with python scripts/sync_page_blocks.py <qcg-backend> <qcg-frontend-next> when blocks change.

Usage

The server provides the following MCP tools that you can use in your MCP-compatible IDE:

API Endpoints

The deployed server provides these endpoints:

• POST /mcp - Main MCP endpoint (Streamable HTTP)
• GET /health - Health check endpoint
• GET / - Service information and documentation
• GET /.well-known/oauth-protected-resource - OAuth protected-resource metadata

Protocol

Built on the MCP Python SDK 2.x, which serves
the protocol. The server is dual-era:

• MCP 2026-07-28 (stateless): every request carries its protocol version; server/discover,
  cache hints, resultType and request-header validation are supported.
• Earlier revisions (2025-11-25 and before): clients that open with initialize - today's
  Cursor, VS Code, Claude Desktop, claude.ai and ChatGPT connectors - keep working unchanged.

Authentication. Send your Scanova API key (or an OAuth access token from Scanova's
authorization server) in Authorization - Bearer <key> or the bare key - or in X-API-Key.
Listing tools and UI resources needs no key; calling a tool without one returns
401 with a WWW-Authenticate challenge pointing at the protected-resource metadata.

Tool failures (for example a Scanova API error) come back as tool results with isError: true,
so the assistant can read and explain them.

UI widgets use the MCP Apps
extension (io.modelcontextprotocol/ui), plus openai/outputTemplate for ChatGPT.

Local Development (Optional)

If you want to run the server locally for development:

Installation

1. Clone the repository:

   git clone <repository-url>
   cd qcg-mcp
   

2. Install dependencies:

   uv sync
   

3. Run locally:

   # HTTP server mode (same app as production)
   uv run src/cloud_server.py
   
   # Or stdio mode for local MCP testing (uses MCP_ACCESS_TOKEN for the Scanova API)
   MCP_ACCESS_TOKEN=your-key uv run src/main.py --stdio
   

4. Configure for local testing:

   {
     "mcpServers": {
       "qcg-mcp": {
         "transport": "http",
         "url": "http://localhost:8000/mcp",
         "headers": {
           "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
         }
       }
     }
   }
   

Docker Deployment (Local)

1. Build the Docker image:

   docker build -t mcpserver:local .
   

2. Start the container:

   docker run -d --name mcpserver -p 8000:8000 mcpserver:local
   

   Or with Docker Compose:

   docker compose up -d
   

3. Verify the server is running:

   curl http://localhost:8000/health
   

4. Configure your IDE (HTTP transport):
   Use the "Configure for local testing" snippet above and point to http://localhost:8000/mcp, ensuring the Authorization header contains your Scanova API key.

5. View logs and stop:

   # View logs
   docker logs -f mcpserver
   
   # Stop and remove with Compose
   docker compose down
   
   # Or stop/remove single container
   docker stop mcpserver && docker rm mcpserver
   

Releases and deploys

Pull request titles follow Conventional Commits
(feat: …, fix: …, docs: …, chore: …; add ! - feat!: … - for a breaking change).
Merging adds the PR to the draft release, versioned by
release-drafter with semantic versioning:
feat → minor, fix and the rest → patch, breaking → major.

Publishing the draft release deploys it (.github/workflows/deploy.yml): tests run, the
image is built and tagged with the version, the scanova-mcp ECS Express service is updated to it,
and /health and initialize are checked. A merge to main does not deploy. To redeploy or roll
back, run the Deploy workflow from the Actions tab with that release's tag as the ref.

AWS access is GitHub OIDC → IAM role qcg-mcp-github-deploy (no stored keys): it trusts only this
repository's production environment (release tags v* only) and can only push this image, update
the scanova-mcp service and pass its task roles.

Troubleshooting

Common Issues

1. "API key is required"

   • Ensure your Scanova API key is correctly set in the headers
   • Check that the header format matches one of the supported formats
   • Get your API key from https://app.scanova.io/

2. "Invalid token" error

   • Verify your API key is valid and active
   • Ensure there are no extra spaces or characters in the API key
   • Try regenerating your API key from the Scanova dashboard

3. Connection errors

   • Check that the server URL is correct
   • Ensure your internet connection is working
   • Verify the server is deployed and running

4. Tool not found

   • Restart your IDE after adding the MCP configuration
   • Check that the JSON configuration is valid
   • Verify the server responds at the /health endpoint

scripts/sync_page_blocks.py

"""Refresh src/page_blocks/ from Scanova's own sources.

The page tools build landing pages in the page builder's block format. The
format is owned by two repos, so this copies it here rather than restating it:

- qcg-backend  src/qr_manager/json_schema/{v2,categories/components}: the JSON
  Schemas a page's blocks must pass to publish (copied as-is to schemas/).
- qcg-frontend-next  packages/blocks/src/blocks/landing/*/definition.ts: each
  block's label, limit, categories, fields and defaults (dumped to blocks.json
  by dump_block_definitions.mjs, which needs `npm i esbuild` next to it).

Usage: python scripts/sync_page_blocks.py <qcg-backend checkout> <qcg-frontend-next checkout>
"""

import json
import shutil
import subprocess
import sys
from pathlib import Path

HERE = Path(__file__).resolve().parent
OUT = HERE.parent / "src" / "page_blocks"

# Blocks an assistant shouldn't place on an ordinary page: they belong to a
# special page type (intro/document/image pages, cover/main pages), only make
# sense on a GS1 code, or run the customer's own JavaScript.
LEFT_OUT = {
    "auto_redirect", "document_viewer", "image_gallery", "cover_page", "main_page", "intro_page",
    "gs1_info", "custom_script",
}


def main(backend: Path, frontend: Path) -> None:
    src = backend / "src" / "qr_manager" / "json_schema"
    schemas = OUT / "schemas"
    if schemas.exists():
        shutil.rmtree(schemas)
    shutil.copytree(src / "v2", schemas / "v2")
    shutil.copytree(src / "categories" / "components", schemas / "categories" / "components")
    shutil.copytree(backend / "src" / "theme_manager" / "json_schema", schemas / "theme")

    dumped = json.loads(subprocess.run(
        ["node", str(HERE / "dump_block_definitions.mjs"), str(frontend)],
        check=True, capture_output=True, text=True,
    ).stdout)
    allowed = json.loads((src / "v2" / "page-types" / "component-page.json").read_text())
    allowed = allowed["items"]["allOf"][1]["properties"]["type"]["enum"]
    blocks = {}
    for block_type in allowed:
        d = dumped.get(block_type)
        if block_type in LEFT_OUT or not d or "error" in d:
            continue
        blocks[block_type] = {
            "label": d.get("label"),
            "description": d.get("description"),
            "limit": d.get("limit"),
            "removable": d.get("canDelete") is not False,
            "categories": d.get("allowedInCategories"),
            "fields": d.get("fields") or [],
            "defaults": d.get("defaults") or {},
        }
    (OUT / "blocks.json").write_text(json.dumps(blocks, indent=1, ensure_ascii=False) + "\n")
    print(f"{len(blocks)} blocks, schemas from {src}")


if __name__ == "__main__":
    main(Path(sys.argv[1]), Path(sys.argv[2]))