Issuebage MCP Server

oficial

plataforma de emissão de crachás digitais

O que você pode fazer com Issuebage MCP?

  • Valide sua chave de API — Peça ao seu assistente para verificar se suas credenciais do IssueBadge funcionam usando validate_key.
  • Liste os modelos de selo — Recupere seus modelos de selo disponíveis para escolher o certo antes de emitir.
  • Emita um certificado — Envie um certificado a um destinatário por nome e e-mail, retornando uma URL pública de verificação.
  • Inspecione os códigos QR — Liste os códigos QR dinâmicos, busque um com sua imagem PNG ou revise seu histórico de leituras.
  • Exclua um código QR — Remova um código QR dinâmico existente pelo seu código.

Documentação

Servidor MCP IssueBadge

Emita certificados e badges verificáveis a partir de qualquer agente de IA. Este servidor Model Context Protocol permite que Cursor, Claude, VS Code e outros clientes MCP listem seus modelos de badge do IssueBadge e enviem um certificado a um destinatário por nome e e-mail.

Duas formas de executá-lo:

Remoto (recomendado)Local (stdio)
Endpointhttps://issuebadge-mcp.issuebadge.workers.dev/mcpnpx issuebadge-mcp-server
Autenticaçãocabeçalho Authorization: Bearer <API key>variável de ambiente ISSUEBADGE_API_KEY
Ferramentasvalidate_key, get_all_badges, issue_badge, list_qr_codes, get_qr_code, get_qr_code_scans, delete_qr_codeas mesmas + create_badge
Armazenamentonenhum, sem estadonenhum

Você precisa de uma chave de API do IssueBadge: app.issuebadge.com → Developer → API key (https://app.issuebadge.com/developer/index).

Instalação

Cursor

Instale o IssueBadge a partir do Cursor Marketplace e cole sua chave de API quando solicitado. Ou adicione-o manualmente em Settings → MCP:

{
  "mcpServers": {
    "issuebadge": {
      "type": "streamable-http",
      "url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
    }
  }
}

Claude Code

claude mcp add --transport http issuebadge https://issuebadge-mcp.issuebadge.workers.dev/mcp \
  --header "Authorization: Bearer YOUR_ISSUEBADGE_API_KEY"

Este repositório também é um plugin do Claude Code (.claude-plugin/plugin.json) e inclui uma skill issuebadge que ensina ao agente o fluxo listar → confirmar → emitir. O .mcp.json do plugin lê a chave da variável de ambiente ISSUEBADGE_API_KEY, então exporte-a antes de iniciar o Claude Code.

Claude Desktop / qualquer cliente stdio

{
  "mcpServers": {
    "issuebadge": {
      "command": "npx",
      "args": ["-y", "issuebadge-mcp-server"],
      "env": { "ISSUEBADGE_API_KEY": "YOUR_ISSUEBADGE_API_KEY" }
    }
  }
}

VS Code (modo agente do Copilot)

.vscode/mcp.json:

{
  "servers": {
    "issuebadge": {
      "type": "http",
      "url": "https://issuebadge-mcp.issuebadge.workers.dev/mcp",
      "headers": { "Authorization": "Bearer YOUR_ISSUEBADGE_API_KEY" }
    }
  }
}

Ferramentas

FerramentaEntradaRetorna
validate_key–{ valid, message }
get_all_badgeslimit?{ badges: [{ id, name, description?, created_at? }] }
issue_badgebadge_id, name, email?, phone?, idempotency_key?, metadata?{ issue_id, certificate_url, idempotency_key }
create_badge (somente stdio)name, description, issuing_organization_name, idempotency_key, opcional badge_logo_path, custom_fields, …Resposta da API do IssueBadge

issue_badge envia o certificado por e-mail ao destinatário e retorna uma URL pública de verificação. Toda chamada com uma nova idempotency_key emite um novo certificado (um é gerado como mcp-<uuid> se você omiti-la). A API rejeita uma chave reutilizada, então após uma chamada com falha verifique se o certificado foi emitido antes de chamar novamente com uma nova chave.

Exemplo de prompt após a instalação: "Emita o certificado Course Completion para Jane Doe, jane@example.com."

QR codes dinâmicos

FerramentaEntradaRetorna
list_qr_codestype?, limit?{ qr_codes: [...], total }
get_qr_codecodeo QR code + bloco de imagem PNG
get_qr_code_scanscode, limit?{ code, scan_count, scans: [{ scanned_at, referer }], total }
delete_qr_codecode{ deleted: true, code }

Tipos: url, vcard, paypal, wifi, email, phone, sms, maps, event, facebook, twitter, youtube, text, mecard. Os códigos são criados e redirecionados no painel do IssueBadge; a imagem codifica um redirecionamento do IssueBadge (scan_url), então um código impresso continua funcionando quando seu destino muda.

Exemplo de prompt: "Crie um QR code chamado Menu que abre https://example.com/menu e mostre-o para mim."

ChatGPT e OAuth

O servidor remoto também fala OAuth 2.1 para hosts que não conseguem enviar uma chave de API (apps do ChatGPT, conectores do Claude): uma requisição sem bearer recebe 401 + WWW-Authenticate: Bearer resource_metadata=…, /.well-known/oauth-protected-resource aponta para https://app.issuebadge.com (PKCE S256, registro dinâmico de cliente), e o token de acesso emitido é encaminhado exatamente como uma chave de API. issue_badge carrega um widget (ui://widget/certificate.html, MCP Apps / ChatGPT Apps SDK) que renderiza o cartão do certificado. Veja CHATGPT.md.

Privacidade e segurança

  • O servidor remoto é sem estado. Sua chave de API é lida do cabeçalho Authorization de cada requisição, encaminhada para app.issuebadge.com e nunca armazenada ou registrada em log. Requisições sem chave recebem 401.
  • O único host contatado é app.issuebadge.com. Nome do destinatário, e-mail e o id do badge são enviados para lá para criar o certificado.
  • Política de privacidade: https://issuebadge.com/h/policy · Termos: https://issuebadge.com/h/terms · Suporte: https://issuebadge.com/h/contact

Auto-hospedar o servidor remoto

git clone https://github.com/issuebadge/mcp-server && cd mcp-server
npm install
npm test
npx wrangler deploy --config worker/wrangler.toml   # needs a Cloudflare account

GET /health retorna { ok: true }. Aponte ISSUEBADGE_BASE_URL para um host de API diferente para o servidor stdio se você executar o IssueBadge em outro lugar.

Desenvolvimento

npm install
npm test          # vitest: client, tools, worker (mocked IssueBadge API)
npm run build     # tsc → dist/ (stdio bin)
npm run dev:worker

Estrutura: src/issuebadge.ts (cliente da API), src/tools.ts (registro de ferramentas compartilhado por ambos os hosts), src/stdio.ts (bin do npm), src/createBadge.ts (ferramenta somente stdio), worker/index.ts (Cloudflare Worker), .cursor-plugin/ + mcp.json (plugin do Cursor), .claude-plugin/ + .mcp.json (plugin do Claude Code), skills/issuebadge/SKILL.md, server.json (MCP Registry).

Licença

MIT