Scanova MCP Server

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

QR Code Management

QR Code Design

Folder Management

Forms & Lead Lists

Analytics

Account Administration

Documentation

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 servesthe 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'sCursor, 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'sauthorization 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 returns401 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 Appsextension (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 byrelease-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, theimage 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 rollback, 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 thisrepository's production environment (release tags v* only) and can only push this image, updatethe 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

License

This project is licensed under the terms of the MIT open source license. Please refer to MIT for the full terms.