Issuebage MCP Server

Servidor MCP de IssueBadge

Emite certificados y credenciales verificables desde cualquier agente de IA. Este servidor de Model Context Protocol permite que Cursor, Claude, VS Code y otros clientes MCP listen tus plantillas de credenciales de IssueBadge y envíen un certificado a un destinatario por nombre y correo electrónico.

Dos formas de ejecutarlo:

	Remoto (recomendado)	Local (stdio)
Endpoint	https://issuebadge-mcp.issuebadge.workers.dev/mcp	npx issuebadge-mcp-server
Autenticación	Cabecera Authorization: Bearer <API key>	Variable de entorno ISSUEBADGE_API_KEY
Herramientas	validate_key, get_all_badges, issue_badge	Las mismas + create_badge
Almacenamiento	Ninguno, sin estado	Ninguno

Necesitas una clave de API de IssueBadge: app.issuebadge.com → Developer → API key (https://app.issuebadge.com/developer/index).

Instalación

Cursor

Instala IssueBadge desde el Cursor Marketplace y pega tu clave de API cuando se te solicite. O añádelo manualmente en 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 repositorio también es un plugin de Claude Code (.claude-plugin/plugin.json) e incluye una habilidad issuebadge que enseña al agente el flujo de trabajo listar → confirmar → emitir. El .mcp.json del plugin lee la clave de la variable de entorno ISSUEBADGE_API_KEY, así que expórtala antes de iniciar Claude Code.

Claude Desktop / cualquier 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" }
    }
  }
}

Herramientas

Herramienta	Entrada	Devuelve
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 (solo stdio)	name, description, issuing_organization_name, idempotency_key, opcional badge_logo_path, custom_fields, …	Respuesta de la API de IssueBadge

issue_badge envía el certificado por correo electrónico al destinatario y devuelve una URL pública de verificación. Cada llamada con un nuevo idempotency_key emite un nuevo certificado (se genera uno como mcp-<uuid> si lo omites). La API rechaza una clave reutilizada, así que después de una llamada fallida comprueba si el certificado se emitió antes de volver a llamar con una nueva clave.

Ejemplo de prompt una vez instalado: "Emite el certificado de Finalización del Curso a Jane Doe, jane@example.com."

ChatGPT y OAuth

El servidor remoto también habla OAuth 2.1 para hosts que no pueden enviar una clave de API (apps de ChatGPT, conectores de Claude): una solicitud sin bearer obtiene 401 + WWW-Authenticate: Bearer resource_metadata=…, /.well-known/oauth-protected-resource apunta a https://app.issuebadge.com (PKCE S256, registro dinámico de clientes), y el token de acceso emitido se reenvía exactamente como una clave de API. issue_badge incluye un widget (ui://widget/certificate.html, MCP Apps / ChatGPT Apps SDK) que renderiza la tarjeta del certificado. Ver CHATGPT.md.

Privacidad y seguridad

• El servidor remoto no tiene estado. Tu clave de API se lee de la cabecera Authorization de cada solicitud, se reenvía a app.issuebadge.com y nunca se almacena ni se registra. Las solicitudes sin clave reciben 401.
• El único host contactado es app.issuebadge.com. El nombre del destinatario, el correo electrónico y el id de la credencial se envían allí para crear el certificado.
• Política de privacidad: https://issuebadge.com/h/policy · Términos: https://issuebadge.com/h/terms · Soporte: https://issuebadge.com/h/contact

Autoalojar el 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 devuelve { ok: true }. Apunta ISSUEBADGE_BASE_URL a un host de API diferente para el servidor stdio si ejecutas IssueBadge en otro lugar.

Desarrollo

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

Estructura: src/issuebadge.ts (cliente de API), src/tools.ts (registro de herramientas compartido por ambos hosts), src/stdio.ts (bin npm), src/createBadge.ts (herramienta solo stdio), worker/index.ts (Cloudflare Worker), .cursor-plugin/ + mcp.json (plugin de Cursor), .claude-plugin/ + .mcp.json (plugin de Claude Code), skills/issuebadge/SKILL.md, server.json (MCP Registry).

Licencia

MIT