Server MCP di QR Branding

Parla con il tuo editor o con la tua app desktop di IA e fai generare codici QR dal motore di QR Branding. Il server MCP racchiude l'API pubblica in un insieme di strumenti che qualsiasi client compatibile con MCP può chiamare. Puoi usarlo in due modi:

• Server remoto su https://qr-branding.com/mcp: niente da installare, incolli un URL e la tua chiave API nel client.
• Server locale, il pacchetto npm @qr-branding/mcp-server (Node 20+), che il tuo client avvia tramite stdio.

Entrambi espongono gli stessi sette strumenti e si autenticano con la stessa chiave API di QR Branding. Codice sorgente: mcp-server/.

Cosa ottieni

Sette strumenti mappati sul gateway pubblico sotto https://qr-branding.com/api/v1/*:

qr_build_vcard supporta questi campi: firstName (obbligatorio), lastName, organization, phone, email e url. Indirizzo postale, qualifica e note non sono ancora supportati. qr_build_geo accetta solo latitude e longitude (niente altitudine).

I formati bitmap (PNG, JPG, WEBP) e l'SVG tornano come blocchi di contenuto immagine inline, quindi i client che mostrano le immagini MCP visualizzano il QR direttamente in chat. I PDF non possono essere inline: il server locale li scrive in un file temporaneo e restituisce il percorso; il server remoto li restituisce come risorsa application/pdf incorporata.

Prerequisiti

1. Una chiave API: accedi a qr-branding.com, vai su Dashboard → Chiavi API, fai clic su Genera chiave e copia subito il valore qrb_…. Non lo vedrai più, ma puoi emettere altre chiavi.
2. Piano Studio: l'API richiede un pacchetto Studio attivo. Con qualsiasi altro piano le chiamate agli strumenti falliscono con studio_required, e l'errore arriva al modello con un suggerimento per passare a Studio. Le generazioni IA consumano inoltre crediti IA di Studio (out_of_api_credits quando finiscono).
3. Node 20+, solo per il server locale, sulla macchina che ospita il processo MCP (di solito il tuo portatile). npx si occupa dell'installazione.

Server remoto (Streamable HTTP)

L'endpoint è https://qr-branding.com/mcp e usa il trasporto Streamable HTTP di MCP (senza stato, risposte JSON). Invia la chiave in uno dei due header:

• Authorization: Bearer qrb_PASTE_YOUR_KEY (quello che la maggior parte dei client configura)
• X-API-Key: qrb_PASTE_YOUR_KEY (lo stesso header dell'API REST)

Una richiesta senza chiave valida riceve 401 con un header WWW-Authenticate: Bearer.

Claude Code (CLI)

claude mcp add --transport http qr-branding https://qr-branding.com/mcp \
  --header "Authorization: Bearer qrb_PASTE_YOUR_KEY"

Esegui /mcp in una sessione per verificare che il server sia connesso, poi chiedi cose come "genera un QR per https://qr-branding.com con moduli a forma di foglia e colore oro"; Claude chiamerà qr_generate.

Cursor

~/.cursor/mcp.json (oppure Settings → MCP):

{
  "mcpServers": {
    "qr-branding": {
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

VS Code (modalità agente di GitHub Copilot)

.vscode/mcp.json nel tuo workspace:

{
  "servers": {
    "qr-branding": {
      "type": "http",
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

Altri client

Qualsiasi client che supporti Streamable HTTP con header personalizzati funziona con la stessa coppia url + headers. Un client che avvia solo server stdio può usare il server locale.

Connettori personalizzati di claude.ai e Claude Desktop

I connettori personalizzati aggiunti da claude.ai (web e impostazioni Connettori di Claude Desktop) si autenticano con OAuth, che il server MCP di QR Branding non supporta ancora: non possono inviare un header con la chiave API. Nel frattempo usa il server locale in Claude Desktop (sotto) oppure Claude Code con il server remoto.

Server locale (npm, stdio)

Il tuo client avvia npx @qr-branding/mcp-server e scambia JSON-RPC su stdin/stdout del processo. La chiave va nella variabile d'ambiente QR_BRANDING_API_KEY.

Claude Code (CLI)

claude mcp add qr-branding --env QR_BRANDING_API_KEY=qrb_PASTE_YOUR_KEY -- npx -y @qr-branding/mcp-server

Claude Desktop (macOS / Windows)

Apri il file di configurazione:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Chiudi completamente Claude Desktop e riaprilo. Il server QR Branding dovrebbe comparire come disponibile nel menu degli strumenti accanto al campo del messaggio.

Cursor

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Riavvia Cursor. Gli strumenti sono esposti sia all'agente della chat sia al Composer.

ChatGPT Desktop

ChatGPT Desktop legge ~/.openai/chatgpt/mcp-config.json (il percorso può variare a seconda della versione: controlla Settings → Beta features → Model Context Protocol):

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Continue (estensione VS Code / JetBrains)

Nella configurazione di Continue (~/.continue/config.json oppure .continue/config.json del workspace), sotto mcpServers:

"mcpServers": [
  {
    "name": "qr-branding",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
]

Zed

Apri ~/.config/zed/settings.json e aggiungi sotto context_servers:

"context_servers": {
  "qr-branding": {
    "source": "custom",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
}

Variabili d'ambiente (server locale)

Verificare che funzioni

Server remoto: elenca gli strumenti con curl:

curl -s https://qr-branding.com/mcp \
  -H "Authorization: Bearer qrb_PASTE_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Server locale: esegui lo smoke test dal checkout del codice sorgente:

cd mcp-server
npm install
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

Lo smoke test interroga /api/v1/qr/ping e /api/v1/qr/templates, stampa il numero di modelli e (con SMOKE_GENERATE=1) genera end-to-end un piccolo QR di prova.

Costi e limiti

• Le chiamate di generazione: la generazione manuale, i modelli e le utility per i contenuti non consumano crediti; la generazione IA sulle nostre chiavi (qr_generate_ai) consuma un credito IA di Studio. Nemmeno le chiamate di elenco e di metadati dei modelli consumano crediti. Vedi Prezzi e crediti.
• I limiti di richieste sono quelli del gateway: vedi la panoramica dell'API. Sul server remoto ogni chiamata a uno strumento conta come una richiesta rispetto al limite al minuto e al tetto giornaliero della tua chiave; l'handshake e tools/list contano solo rispetto al limite per rete.
• Il costo lato assistente IA dipende dai prezzi del tuo assistente (uso di Claude, abbonamento a ChatGPT, ecc.). Il server MCP in sé è gratuito.

Privacy e sicurezza

• Il server MCP inoltra a qr-branding.com i tuoi prompt e gli URL o testi che passi. Nessuna telemetria di terze parti, nessun SDK di analytics.
• La chiave API resta nella configurazione del tuo client; non compare mai nelle trascrizioni della chat né nel contesto del modello. Il server remoto la riceve solo via HTTPS e la confronta con un hash, come l'API REST.
• Ruota la chiave in qualsiasi momento da Dashboard → Chiavi API: le chiavi vecchie vengono revocate all'istante.

Risoluzione dei problemi

• "QR_BRANDING_API_KEY not set" (locale): la variabile d'ambiente non è arrivata al processo npx avviato. Controlla che il JSON sia valido e riavvia l'app host.
• 401 invalid_api_key / missing_api_key (remoto): l'header non è arrivato oppure la chiave è stata revocata. Controlla l'header Authorization: Bearer qrb_… nella configurazione del client.
• studio_required: il tuo account non ha un pacchetto Studio attivo (Starter e Pro includono solo l'editor). Passa a Studio dalla pagina prezzi.
• out_of_api_credits: hai esaurito i crediti IA di Studio. Ricarica dalla pagina prezzi.
• L'immagine non viene mostrata inline: il tuo client potrebbe non gestire il contenuto immagine MCP. Bitmap e SVG usano il tipo di contenuto immagine della specifica; i PDF tornano come percorso di file (locale) o come risorsa incorporata (remoto).
• Errori di rete / timeout: il gateway si trova su https://qr-branding.com. Se la tua rete lo blocca, sovrascrivi QR_BRANDING_API_BASE_URL (server locale).

Prossime novità

Stiamo monitorando questi punti per le prossime versioni:

• OAuth sul server remoto, così da poterlo aggiungere come connettore personalizzato in claude.ai e negli altri client che lo richiedono.
• Uno strumento qr_dynamic_create che crea QR dinamici stampabili (il redirector /q/{slug}) senza uscire dalla chat.
• Gestori di risorse per sfogliare i modelli come risorse MCP (così i client con selettore di risorse possono mostrarli nella loro interfaccia).

Apri issue o richieste di funzionalità sul repository. Il codice del pacchetto si trova nello stesso monorepo del motore.