Issuebage MCP Server
oficialplataforma 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) | |
|---|---|---|
| Endpoint | https://issuebadge-mcp.issuebadge.workers.dev/mcp | npx issuebadge-mcp-server |
| Autenticação | cabeçalho Authorization: Bearer <API key> | variável de ambiente ISSUEBADGE_API_KEY |
| Ferramentas | validate_key, get_all_badges, issue_badge, list_qr_codes, get_qr_code, get_qr_code_scans, delete_qr_code | as mesmas + create_badge |
| Armazenamento | nenhum, sem estado | nenhum |
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
| Ferramenta | Entrada | Retorna |
|---|---|---|
validate_key | – | { valid, message } |
get_all_badges | limit? | { badges: [{ id, name, description?, created_at? }] } |
issue_badge | badge_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
| Ferramenta | Entrada | Retorna |
|---|---|---|
list_qr_codes | type?, limit? | { qr_codes: [...], total } |
get_qr_code | code | o QR code + bloco de imagem PNG |
get_qr_code_scans | code, limit? | { code, scan_count, scans: [{ scanned_at, referer }], total } |
delete_qr_code | code | { 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
Authorizationde cada requisição, encaminhada paraapp.issuebadge.come nunca armazenada ou registrada em log. Requisições sem chave recebem401. - 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