Sweeppea MCP

Gestiona sorteos, participantes y sorteos de ganadores con cumplimiento legal en EE. UU. y Canadá directamente desde tu agente de IA. El acceso requiere una suscripción activa a Sweeppea y una clave API.

Documentación

 ___
/ __|_ __ _____ ___ _ __ _ __  ___ __ _
\__ \ V  V / -_) -_) '_ \ '_ \/ -_) _` |
|___/\_/\_/\___\___| .__/ .__/\___\__,_|
                   |_|  |_|

Servidor MCP de Sweeppea

Protocolo de Contexto de Modelo para la Gestión de Sorteos

MCP Protocol Server Version Tools Transport License


Cómo Funciona

El Servidor MCP de Sweeppea es un puente seguro entre los asistentes de IA y la API de Sweeppea. Traduce interacciones en lenguaje natural en llamadas estructuradas a la API, brindando a tu asistente de IA acceso completo a la gestión de sorteos: participantes, reglas oficiales, ganadores, calendarios, facturación y más.

Your AI Assistant  →  MCP (Model Context Protocol)  →  Sweeppea MCP Server  →  Sweeppea API v3

No se requiere configuración local: solo apunta tu cliente MCP al endpoint y autentícate.


Autenticación y Precios

Este servidor MCP requiere una Clave de API de Sweeppea vinculada a una suscripción activa.

Realizar sorteos en los Estados Unidos y/o Canadá es legalmente complejo. Cada estado tiene sus propias regulaciones: requisitos de registro, umbrales de fianza, reglas de nulidad donde esté prohibido, leyes de divulgación de premios y reglas oficiales que deben cumplir con los estatutos de protección al consumidor a nivel federal y estatal. Cometer un error en cualquiera de estos aspectos expone a los patrocinadores a una responsabilidad legal real.

Sweeppea maneja esa complejidad por ti y mucho más. La plataforma genera reglas oficiales legalmente conformes, gestiona la elegibilidad multiestatal, aplica límites de participación y proporciona un registro auditable de cada participante y sorteo de ganadores. La Clave de API que usas para conectarte no es solo autenticación: es tu acceso a un sistema construido específicamente para mantener los sorteos legalmente defendibles.

Para comenzar:

  1. Crea una cuenta en www.sweeppea.com
  2. Elige un plan que se ajuste a tus necesidades
  3. Obtén tu Clave de API desde el panel de API
  4. Conecta tu cliente MCP usando las guías de configuración a continuación

Documentación:


Validaciones del Lado del Servidor

El servidor aplica reglas comerciales y legales antes de que una herramienta se ejecute. Si una llamada viola una regla, la herramienta se rechaza y nunca llega a la API de Sweeppea: no se crean recursos.

Dos capas se ejecutan en cada tools/call:

  • Protecciones legales codificadas (inviolables): lotería ilegal sin AMOE, COPPA (edad mínima inferior a 13), control de edad 21+ para alcohol, control de edad 21+ y exclusiones estatales para nicotina, sin productos de nicotina como premios, y confirmación explícita para promociones dirigidas a menores.
  • Reglas declarativas dinámicas (editables por Sweeppea): verificaciones adicionales sobre create_sweepstakes, update_entry_settings, create_rules_wizard, create_note, create_ticket y add_participant.

Un rechazo devuelve un payload estructurado para que tu asistente de IA pueda recuperarse:

{
  "blocked_by": "server_validation",
  "error_code": "ALCOHOL_AGE_GATE_REQUIRED",
  "error_message": "Alcohol-related sweepstakes require an age gate of 21+.",
  "rule_id": "age_gate_must_be_21_when_active_v1"
}

rule_id solo está presente para reglas dinámicas. El asistente de IA puede leer estos campos y ajustar los argumentos antes de reintentar.

Las herramientas irreversibles — cada delete_*, además de send_message, send_code, cancel_campaign, remove_suppression, unassign_code y remove_drip_contact — requieren confirm: true y se rechazan sin ello.


Inicio Rápido

Usando Claude Code CLI:

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

Consulta Configuración de Plataformas para Claude Desktop, Cursor, Windsurf, GitHub Copilot, Gemini CLI y más.


Herramientas Disponibles (116)

Herramientas de Cuenta (4)

HerramientaDescripción
health_checkVerifica la conexión con la API de Sweeppea y valida tu clave de API
get_profileObtiene la información del perfil de usuario de una cuenta de Sweeppea
get_businessObtiene información comercial, incluidos detalles de la empresa y dirección
get_planObtiene detalles del plan de suscripción, incluidos precios, límites y funciones

Herramientas de Página de Participación (3)

HerramientaDescripción
get_entry_fieldsObtiene todos los campos de formulario para una página de participación de sorteos. Úsalo antes de agregar participantes
get_entry_settingsObtiene toda la configuración de la página de participación: visualización, colores, cumplimiento, confirmación, ganadores, control de edad, AMOE y más
update_entry_settingsActualiza de 1 a 5 configuraciones de la página de participación por solicitud. Admite más de 80 campos configurables

Herramientas de Sorteos (7)

HerramientaDescripción
fetch_sweepstakesLista sorteos con paginación. Devuelve un resumen con un estado de ciclo de vida calculado (programado, en curso, finalizado)
create_sweepstakesCrea un nuevo sorteo con tipo, manejador, fechas y horas
update_sweepstakesActualiza un sorteo existente (nombre, fechas, horas)
clone_sweepstakesClona un sorteo existente con nuevos parámetros y fechas
pause_sweepstakesPausa un sorteo, poniéndolo en inactivo mientras conserva los datos
unpause_sweepstakesReactiva un sorteo pausado para permitir nuevas participaciones
delete_sweepstakesElimina permanentemente un sorteo y todos los datos asociados

Herramientas de Participantes (6)

HerramientaDescripción
add_participantAgrega un nuevo participante a un sorteo con campos personalizados. Se requieren tanto el correo electrónico como el teléfono
get_participantObtiene un solo participante por token, correo electrónico o número de teléfono
fetch_participantsLista participantes con paginación (20/página), búsqueda y filtros de fecha
count_participantsObtiene recuentos de participantes con filtrado opcional por tipo y fecha
update_bonus_entriesActualiza el valor de participaciones de bonificación para un participante en un sorteo
delete_participantElimina permanentemente a un participante de un sorteo

Herramientas de Grupos (4)

HerramientaDescripción
fetch_groupsObtiene todos los grupos de un sorteo para la segmentación de participantes
create_groupCrea un nuevo grupo dentro de un sorteo
update_groupActualiza el nombre de un grupo existente en un sorteo
delete_groupElimina un grupo. No se puede eliminar un grupo primario, bloqueado o con participantes

Herramientas de Notas (5)

HerramientaDescripción
fetch_notesObtiene todas las notas, descifradas y en orden cronológico inverso
get_noteObtiene una sola nota por token. El contenido se descifra automáticamente
create_noteCrea una nueva nota. El contenido se cifra con AES-256-CBC
update_noteActualiza una nota existente. Admite actualizaciones parciales
delete_noteElimina permanentemente una nota. Esta acción no se puede deshacer

Herramientas de Calendario (5)

HerramientaDescripción
fetch_calendar_eventsObtiene todos los eventos del calendario con fechas, horas y estado
get_calendar_eventObtiene un solo evento del calendario por su token con todos los detalles
create_calendar_eventCrea un nuevo evento de calendario con título, fechas y notificaciones
update_calendar_eventActualiza un evento de calendario existente. No se puede actualizar a fechas pasadas
delete_calendar_eventElimina permanentemente un evento de calendario. No se puede deshacer

Herramientas de Reglas (5)

HerramientaDescripción
fetch_rulesObtiene todas las reglas oficiales, incluidas las reglas primarias y secundarias
create_ruleCrea un nuevo documento de reglas oficiales con contenido HTML
update_ruleActualiza un documento de reglas oficiales existente. Admite actualizaciones parciales
delete_ruleElimina permanentemente un documento de reglas oficiales. No se puede deshacer
create_rules_wizardGenera reglas oficiales mediante un asistente de 14 pasos. Reglas HTML completas en el servidor

Herramientas de Facturación y Billetera (4)

HerramientaDescripción
fetch_wallet_transactionsObtiene todas las transacciones de la billetera, incluidos créditos, débitos y pagos
fetch_billing_transactionsObtiene todas las transacciones de facturación, incluidas facturas y montos
fetch_billing_consumptionsObtiene los totales de consumo de facturación mensual y anual
fetch_data_transferObtiene los registros de transferencia de datos para un sorteo específico con costos

Herramientas de Tickets de Soporte (7)

HerramientaDescripción
fetch_open_ticketsObtiene tickets abiertos con paginación, búsqueda, filtros de plataforma y prioridad
fetch_closed_ticketsObtiene tickets cerrados con paginación, búsqueda, filtros de plataforma y prioridad
get_ticketObtiene detalles completos del ticket por número de caso, incluidas notas y archivos
create_ticketCrea un nuevo ticket de soporte con título, descripción, prioridad, asignado y plataforma
resolve_ticketCierra/resuelve un ticket de soporte abierto
update_ticketActualiza un ticket de soporte abierto. Se requiere al menos un campo
delete_ticketElimina permanentemente un ticket de soporte abierto. No se puede deshacer

Herramientas de Ganadores (5)

HerramientaDescripción
fetch_winnersObtiene ganadores de un sorteo con paginación y búsqueda
draw_winnersSorteo de ganadores aleatorios entre participantes elegibles
schedule_drawingPrograma un sorteo de ganadores futuro para un sorteo
fetch_scheduled_drawingsObtiene todos los sorteos programados para un sorteo
delete_scheduled_drawingElimina un sorteo programado pendiente. Solo se pueden eliminar sorteos pendientes

Herramientas de Tareas Pendientes (4)

HerramientaDescripción
fetch_todosObtiene todos los elementos de Tareas Pendientes con paginación (20 por página), búsqueda y filtros avanzados
create_todoCrea un nuevo elemento interno de Tareas Pendientes
update_todoActualiza un elemento existente de Tareas Pendientes. Admite actualizaciones parciales
delete_todoElimina permanentemente un elemento de Tareas Pendientes. Esta acción no se puede deshacer

Herramientas de Archivos (5)

HerramientaDescripción
fetch_filesLista todos los archivos en el Drive del usuario con uso de almacenamiento, categorías y paginación
upload_fileSube un archivo al Drive del usuario. El archivo debe estar codificado en base64
get_file_urlGenera una URL S3 presignada de corta duración para descargar o previsualizar un archivo del Drive del usuario
send_fileEnvía un archivo del Drive del usuario como adjunto de correo electrónico
delete_fileElimina permanentemente un archivo del Drive del usuario

Herramientas de Facturas (5)

Requiere el módulo de Facturas habilitado en la cuenta: deshabilitado por defecto. La API devuelve 403 "module is not enabled" hasta que Sweeppea lo active; contacta al soporte para solicitar acceso.

HerramientaDescripción
create_invoiceCrea una factura. El subtotal, el impuesto y el total se calculan en el servidor ($1–$1,000,000, máximo 60 líneas de artículos)
fetch_invoicesLista facturas con paginación y filtros por estado y rango de fechas
get_invoiceObtiene el detalle completo de la factura: líneas de artículos, información de pago, enlace público, código QR, estadísticas y línea de tiempo de eventos
update_invoiceActualiza una factura. Máquina de estados borrador → pendiente → pagada; pagada y cancelada son inmutables
delete_invoiceElimina permanentemente una factura. No se puede deshacer: usa el estado cancelled para conservarla como historial

Herramientas de Encuestas (7)

Requiere el módulo de Encuestas habilitado en la cuenta: deshabilitado por defecto. La API devuelve 403 "module is not enabled" hasta que Sweeppea lo active; contacta al soporte para solicitar acceso.

HerramientaDescripción
create_surveyCrea una encuesta vinculada a un sorteo, opcionalmente con su conjunto completo de preguntas
fetch_surveysLista encuestas con paginación, filtradas por sorteo, estado habilitado o estado archivado
get_surveyObtiene el detalle completo de la encuesta, incluido su conjunto completo de preguntas, ordenado por página y luego por orden
update_surveyActualiza una encuesta. El conjunto de preguntas es un reemplazo completo y se bloquea una vez que existen respuestas
delete_surveyElimina permanentemente una encuesta, sus preguntas, respuestas, estadísticas y archivos. No se puede deshacer
fetch_survey_responsesObtiene respuestas individuales con cada respuesta. Los metadatos de dispositivo/IP son PII y están desactivados por defecto
fetch_survey_reportObtiene el informe agregado: totales, tasa de finalización, desglose por dispositivo, línea de tiempo, distribuciones

Herramientas de Códigos y Cupones (14)

Las escrituras requieren el módulo de Códigos y Cupones habilitado en la cuenta: devuelven 403 "module not enabled" en caso contrario. Las cuatro lecturas (fetch_code_stats, fetch_codes, get_code, get_code_settings) no documentan ese 403; si una de ellas responde 403, la causa es otra. | Herramienta | Descripción | |------|-------------| | fetch_code_stats | Contar los códigos de un sorteo por estado | | fetch_codes | Listar códigos con el participante al que está asignado cada uno. Filtros del lado del servidor, búsqueda y ordenamiento | | get_code | Obtener un código por token, o por el código en sí más el token del sorteo (punto de venta) | | create_codes | Importar de 1 a 1,000 códigos que ya tengas. Reporta Creados, Duplicados e Inválidos por separado | | generate_codes | Generar hasta 5,000 códigos aleatorios con prefijo, sufijo, valor y expiración opcionales | | update_code | Actualizar parcialmente un código. null limpia un campo; el código en sí solo puede renombrarse mientras no esté asignado | | delete_codes | Eliminar permanentemente hasta 1,000 códigos. Los códigos asignados, canjeados y anulados se omiten. Requiere confirm: true | | assign_code | Asignar un código disponible a un participante del mismo sorteo. No notifica a nadie | | unassign_code | Recuperar un código de un participante, limpiando también su canje. Requiere confirm: true | | redeem_code | Canjear un código por token, o por el código en sí en el punto de venta. Reversible | | unredeem_code | Deshacer un canje manteniendo la asignación | | get_code_settings | Obtener cómo las páginas de participación y AMOE entregan códigos | | update_code_settings | Configurar los modos de registro de códigos, generación y entrega para las páginas de participación y AMOE | | send_code | Enviar un código al participante que lo tiene por correo electrónico y/o SMS. No se puede recuperar. Requiere confirm: true |

Herramientas de Mensajería (12)

Las escrituras requieren el módulo Enviar Mensaje habilitado en la cuenta; de lo contrario devuelven 403 "module not enabled". Las seis lecturas no documentan ese 403.

El envío directo (send_message, send_code) es un interruptor separado del módulo: una cuenta con el módulo habilitado aún puede recibir 403 hasta que el soporte de Sweeppea habilite los mensajes directos. fetch_messaging_usage informa ambos, además de los canales del plan, la asignación, las pausas de envío y la preparación para 10DLC.

Las campañas no se pueden crear a través de la API; se crean en la aplicación Sweeppea. Estas herramientas las leen, pausan, reanudan y cancelan.

HerramientaDescripción
fetch_messaging_usageObtener acceso de mensajería, canales del plan, asignación, pausas de envío y estado de 10DLC
fetch_campaignsListar campañas con filtros por sorteo, canal, categoría, estado y nombre
get_campaignObtener contenido de campaña, audiencia, perfil de remitente, contadores y las acciones que su estado permite
fetch_campaign_reportObtener el informe de la campaña. Las tasas se calculan sobre los mensajes enviados, no sobre la audiencia
fetch_campaign_recipientsListar destinatarios con estado de entrega, filtrados por estado o una dirección exacta
pause_campaignPausar una campaña en cola o en envío. Los mensajes ya entregados al operador aún se envían
resume_campaignReanudar una campaña pausada después de volver a verificar todo lo que podría detenerla nuevamente
cancel_campaignCancelar una campaña permanentemente. No se puede reanudar. Requiere confirm: true
fetch_suppressionsListar direcciones suprimidas: bajas, respuestas STOP, quejas, rebotes y entradas manuales
add_suppressionsSuprimir hasta 500 direcciones de correo electrónico o números de teléfono. Nunca degrada una exclusión existente
remove_suppressionEliminar una supresión agregada manualmente. Las bajas, respuestas STOP y quejas nunca se pueden eliminar. Requiere confirm: true
send_messageEnviar un mensaje de texto plano por correo electrónico y/o SMS a un participante de tu cuenta. No se puede recuperar. Requiere confirm: true

Herramientas de Campañas de Goteo (7)

Las lecturas requieren el módulo Marketing de Goteo. Las escrituras (pause_drip, resume_drip, remove_drip_contact) requieren Marketing de Goteo y Enviar Mensaje; cada módulo faltante devuelve su propio 403. Esta restricción está documentada por la API, aún no observada.

Los goteos se crean, editan, activan y eliminan solo en la aplicación Sweeppea, por diseño; la API no tiene endpoints para ellos. Estas herramientas leen goteos, los pausan y reanudan, y eliminan un solo contacto.

HerramientaDescripción
fetch_dripsListar secuencias automatizadas de correo electrónico/SMS, con can_run (si el plan permite ejecutar goteos) y el límite del plan
get_dripObtener un goteo completo: cada paso con su retraso y contenido, resumen de audiencia y configuración de envío
fetch_drip_reportObtener estadísticas de goteo por paso, en total, día a día y enlaces clicados, durante 7, 30, 90 o 180 días
fetch_drip_enrollmentsListar contactos inscritos: posición en la secuencia, próximo paso programado y motivo de salida
pause_dripPausar un goteo activo: no hay nuevas inscripciones ni pasos enviados hasta que se reanude
resume_dripReanudar un goteo pausado que no se haya editado desde entonces. Los rechazos explican la causa
remove_drip_contactEliminar un contacto de un goteo. Permanente: ese goteo nunca vuelve a inscribirlo. Requiere confirm: true

Herramientas de Documentación (1)

HerramientaDescripción
fetch_documentationObtener artículos de ayuda y documentación de soporte con paginación y búsqueda

Herramientas de Utilidades (5)

HerramientaDescripción
fetch_timezonesObtener todas las zonas horarias disponibles con identificadores IANA y desfases UTC
fetch_statesObtener todos los estados de EE. UU., incluidos DC, Puerto Rico y territorios
fetch_zipcodesBuscar códigos postales de EE. UU. por código, ciudad o estado. Hasta 10 resultados
fetch_areacodesBuscar códigos de área telefónicos de EE. UU. por código o estado. Hasta 10 resultados
fetch_countriesBuscar países por nombre, código de marcación o abreviatura ISO. Hasta 10 resultados

Herramientas de Pruebas (1)

HerramientaDescripción
hello_worldHerramienta de prueba simple para verificar que la conexión MCP funciona correctamente

Ejemplos de Uso

Inicializar conexión:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "client"}
    }
  }'

Agregar un participante:

curl -X POST https://mcp.sweeppea.com/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "MCP-Session-Id: uuid-xxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "add_participant",
      "arguments": {
        "sweepstakes_token": "xxx-xxx-xxx",
        "email": "user@example.com",
        "fields": {"First_Name": "John", "Last_Name": "Doe"}
      }
    }
  }'

Configuración de la Plataforma

Claude Code (CLI)

claude mcp add sweeppea https://mcp.sweeppea.com/ \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  --header "MCP-Protocol-Version: 2025-11-25"

Claude Desktop / Cowork

Ubicación del archivo de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Requiere Node.js instalado.

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header", "Authorization: Bearer YOUR_API_KEY",
        "--header", "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Cursor

~/.cursor/mcp.json (global) o .cursor/mcp.json (proyecto)

  1. Crear o editar el archivo de configuración con el JSON a continuación
  2. Reemplazar YOUR_API_KEY con tu Clave API de Sweeppea
  3. Reiniciar Cursor
  4. Ir a Configuración > Herramientas y MCP
  5. Habilitar el servidor sweeppea con el interruptor
{
  "mcpServers": {
    "sweeppea": {
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json (global)

  1. Crear o editar el archivo de configuración con el JSON a continuación
  2. Reemplazar YOUR_API_KEY con tu Clave API de Sweeppea
  3. Ir a Configuración > Cascade > Servidores MCP
  4. Verificar que sweeppea aparezca y esté habilitado
{
  "mcpServers": {
    "sweeppea": {
      "serverUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

GitHub Copilot (VS Code)

.vscode/mcp.json (espacio de trabajo) o Configuración de Usuario

{
  "inputs": [
    {
      "type": "promptString",
      "id": "sweeppea-api-key",
      "description": "Sweeppea API Key",
      "password": true
    }
  ],
  "servers": {
    "sweeppea": {
      "type": "http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer ${input:sweeppea-api-key}",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Gemini CLI

~/.gemini/settings.json (global) o .gemini/settings.json (proyecto)

{
  "mcpServers": {
    "sweeppea": {
      "httpUrl": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Agent Zero

Marco de trabajo de agente de IA de código abierto con soporte MCP.

  1. Ir a Configuración > MCP/A2A > Servidores MCP
  2. Agregar la configuración JSON a continuación
  3. Reemplazar YOUR_API_KEY con tu Clave API de Sweeppea
  4. Hacer clic en Guardar
{
  "mcpServers": {
    "sweeppea": {
      "description": "Sweeppea - Sweepstakes Management API",
      "type": "streamable-http",
      "url": "https://mcp.sweeppea.com/",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY",
        "MCP-Protocol-Version": "2025-11-25"
      }
    }
  }
}

Antigravity de Google

~/.gemini/antigravity/mcp_config.json (global)

{
  "mcpServers": {
    "sweeppea": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.sweeppea.com/",
        "--header",
        "Authorization: Bearer YOUR_API_KEY",
        "--header",
        "MCP-Protocol-Version: 2025-11-25"
      ]
    }
  }
}

Protocolo

PropiedadValor
Versión2025-11-25
TransporteHTTP transmisible
AutenticaciónToken Bearer
FormatoJSON-RPC 2.0
Endpointhttps://mcp.sweeppea.com/

Licencia

Licencia MIT: consulta el archivo LICENCIA para más detalles.

(c) Sweeppea | Todos los derechos reservados