Issuebage MCP Server

Servidor MCP IssueBadge

Emite certificados e selos 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 selos 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	as mesmas + create_badge
Armazenamento	nenhum, sem estado	nenhum

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

Instalação

Cursor

Instale IssueBadge no Cursor Marketplace e cole sua chave de API quando solicitado. Ou adicione 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 habilidade issuebadge que ensina ao agente o fluxo de 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 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 IssueBadge

issue_badge envia o certificado por e-mail ao destinatário e retorna uma URL pública de verificação. Cada chamada com um novo idempotency_key emite um novo certificado (um é gerado como mcp-<uuid> se você o omitir). A API rejeita uma chave reutilizada, então após uma chamada 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 de Conclusão do Curso para Jane Doe, jane@example.com."

ChatGPT e OAuth

O servidor remoto também fala OAuth 2.1 para hosts que não podem enviar uma chave de API (apps ChatGPT, conectores Claude): uma solicitaçã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 clientes), 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 não tem estado. Sua chave de API é lida do cabeçalho Authorization de cada solicitação, encaminhada para app.issuebadge.com, e nunca é armazenada ou registrada. Solicitações sem chave recebem 401.
• O único host contatado é app.issuebadge.com. Nome do destinatário, e-mail e o ID do selo 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-hospede 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 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 de API), src/tools.ts (registro de ferramentas compartilhado por ambos os hosts), src/stdio.ts (bin npm), src/createBadge.ts (ferramenta somente stdio), worker/index.ts (Cloudflare Worker), .cursor-plugin/ + mcp.json (plugin Cursor), .claude-plugin/ + .mcp.json (plugin Claude Code), skills/issuebadge/SKILL.md, server.json (MCP Registry).

Licença

MIT