Servidor MCP do QR Branding

Converse com o seu editor ou aplicativo de IA para desktop e peça que ele gere QR codes pelo motor do QR Branding. O servidor MCP envolve a API pública em um conjunto de ferramentas que qualquer cliente compatível com MCP pode chamar. Você pode usá-lo de duas formas:

• Servidor remoto em https://qr-branding.com/mcp: nada para instalar, basta colar uma URL e a sua chave de API no cliente.
• Servidor local, o pacote npm @qr-branding/mcp-server (Node 20+), que o seu cliente inicia por stdio.

Os dois expõem as mesmas sete ferramentas e se autenticam com a mesma chave de API do QR Branding. Código-fonte: mcp-server/.

O que você ganha

Sete ferramentas mapeadas para o gateway público em https://qr-branding.com/api/v1/*:

qr_build_vcard aceita estes campos: firstName (obrigatório), lastName, organization, phone, email e url. Endereço postal, cargo e notas ainda não são aceitos. qr_build_geo recebe apenas latitude e longitude (sem altitude).

Os formatos bitmap (PNG, JPG, WEBP) e o SVG chegam como blocos de conteúdo de imagem inline, então os clientes que exibem imagens MCP mostram o QR direto no chat. PDFs não podem ser inline: o servidor local os grava em um arquivo temporário e retorna o caminho; o servidor remoto os retorna como um recurso application/pdf incorporado.

Pré-requisitos

1. Uma chave de API: entre em qr-branding.com, vá em Painel → Chaves de API, clique em Gerar chave e copie o valor qrb_… nesse momento. Você não vai vê-lo de novo, mas pode emitir outras.
2. Plano Studio: a API exige um pacote Studio ativo. Com qualquer outro plano, as chamadas das ferramentas falham com studio_required e o erro chega ao modelo com uma sugestão de upgrade. As gerações com IA também gastam créditos de IA do Studio (out_of_api_credits quando eles acabam).
3. Node 20+, só para o servidor local, na máquina que hospeda o processo MCP (normalmente o seu notebook). O npx cuida da instalação.

Servidor remoto (Streamable HTTP)

O endpoint é https://qr-branding.com/mcp e usa o transporte Streamable HTTP do MCP (sem estado, respostas JSON). Envie a sua chave em qualquer um destes cabeçalhos:

• Authorization: Bearer qrb_PASTE_YOUR_KEY (o que a maioria dos clientes configura)
• X-API-Key: qrb_PASTE_YOUR_KEY (o mesmo cabeçalho da API REST)

Uma requisição sem chave válida recebe 401 com um cabeçalho 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"

Execute /mcp em uma sessão para conferir se o servidor está conectado e peça coisas como "gere um QR para https://qr-branding.com com módulos em forma de folha e cor dourada"; o Claude vai chamar qr_generate.

Cursor

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

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

VS Code (modo agente do GitHub Copilot)

.vscode/mcp.json no seu workspace:

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

Outros clientes

Qualquer cliente que aceite Streamable HTTP com cabeçalhos personalizados funciona com o mesmo par url + headers. Um cliente que só inicia servidores stdio pode usar o servidor local.

Conectores personalizados do claude.ai e do Claude Desktop

Os conectores personalizados adicionados pelo claude.ai (web e as configurações de Conectores do Claude Desktop) se autenticam com OAuth, que o servidor MCP do QR Branding ainda não suporta: eles não conseguem enviar um cabeçalho com a chave de API. Até lá, use o servidor local no Claude Desktop (abaixo) ou o Claude Code com o servidor remoto.

Servidor local (npm, stdio)

O seu cliente inicia npx @qr-branding/mcp-server e troca JSON-RPC pela entrada e saída padrão do processo. A chave vai na variável de 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)

Abra o arquivo de configuração:

• 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" }
    }
  }
}

Feche o Claude Desktop por completo e abra de novo. O servidor do QR Branding deve aparecer como disponível no menu de ferramentas ao lado do campo de mensagem.

Cursor

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

Reinicie o Cursor. As ferramentas ficam disponíveis tanto para o agente do chat quanto para o Composer.

ChatGPT Desktop

O ChatGPT Desktop lê ~/.openai/chatgpt/mcp-config.json (o caminho pode variar conforme a versão; confira em 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 (extensão do VS Code / JetBrains)

Na configuração do Continue (~/.continue/config.json ou .continue/config.json do workspace), dentro de mcpServers:

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

Zed

Abra ~/.config/zed/settings.json e adicione em 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" }
  }
}

Variáveis de ambiente (servidor local)

Como verificar se funciona

Servidor remoto: liste as ferramentas com 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"}'

Servidor local: rode o smoke test a partir do código-fonte:

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

O smoke test consulta /api/v1/qr/ping e /api/v1/qr/templates, imprime a quantidade de modelos e (com SMOKE_GENERATE=1) gera de ponta a ponta um QR de teste bem pequeno.

Custos e limites

• As chamadas de geração: a geração manual, os modelos e os utilitários de conteúdo não gastam créditos; a geração com IA nas nossas chaves (qr_generate_ai) gasta um crédito de IA do Studio. As chamadas de listagem e de metadados de modelos também não consomem créditos. Veja Preços e créditos.
• Os limites de requisições são os do gateway: veja a visão geral da API. No servidor remoto, cada chamada de ferramenta conta como uma requisição no limite por minuto e no teto diário da sua chave; o handshake e o tools/list contam apenas no limite por rede.
• O custo do lado do assistente de IA depende dos preços do seu assistente (uso do Claude, assinatura do ChatGPT etc.). O servidor MCP em si é gratuito.

Privacidade e segurança

• O servidor MCP encaminha para qr-branding.com os seus prompts e as URLs ou textos que você passar. Sem telemetria de terceiros e sem SDKs de analytics.
• A chave de API fica na configuração do seu cliente; ela nunca aparece nas transcrições do chat nem no contexto do modelo. O servidor remoto só a recebe por HTTPS e a confere contra um hash, como a API REST.
• Troque a chave quando quiser em Painel → Chaves de API; as chaves antigas são revogadas na hora.

Solução de problemas

• "QR_BRANDING_API_KEY not set" (local): a variável de ambiente não chegou ao processo npx iniciado. Confira se o JSON é válido e reinicie o aplicativo host.
• 401 invalid_api_key / missing_api_key (remoto): o cabeçalho não chegou ou a chave foi revogada. Confira o cabeçalho Authorization: Bearer qrb_… na configuração do cliente.
• studio_required: a sua conta não tem um pacote Studio ativo (Starter e Pro incluem só o editor). Adquira o Studio em preços.
• out_of_api_credits: os seus créditos de IA do Studio acabaram. Recarregue em preços.
• A imagem não aparece inline: o seu cliente pode não tratar o conteúdo de imagem do MCP. Bitmaps e SVGs usam o tipo de conteúdo de imagem da especificação; PDFs chegam como um caminho de arquivo (local) ou um recurso incorporado (remoto).
• Erros de rede / timeouts: o gateway fica em https://qr-branding.com. Se a sua rede o bloqueia, sobrescreva QR_BRANDING_API_BASE_URL (servidor local).

Próximos passos

Estamos acompanhando estes itens para as próximas versões:

• OAuth no servidor remoto, para que ele possa ser adicionado como conector personalizado no claude.ai e em outros clientes que o exijam.
• Uma ferramenta qr_dynamic_create que cria QR dinâmicos imprimíveis (o redirecionador /q/{slug}) sem sair do chat.
• Handlers de recursos para navegar pelos modelos como recursos MCP (para que clientes com seletor de recursos possam exibi-los na interface).

Abra issues ou pedidos de recursos no repositório. O código do pacote está no mesmo monorepo do motor.