Servidor MCP de GrowSurf

La interfaz de línea de comandos (CLI) oficial de GrowSurf y el servidor de código abierto del Model Context Protocol (MCP) para implementar programas de referidos y afiliados de GrowSurf con pasos guiados y envoltorios seguros de la API REST.

Conéctalo a un agente de IA y, en lenguaje natural, el agente puede crear un programa de referidos o afiliados, configurar recompensas, instalar el seguimiento, añadir y gestionar participantes, y leer análisis, todo respaldado por la API REST de GrowSurf.

• Más información sobre GrowSurf en https://growsurf.com

• Más información sobre este servidor MCP en https://docs.growsurf.com/build-with-ai

¿Para quién es esto?

Este servidor MCP es para:

• Desarrolladores que usan herramientas compatibles con MCP (Claude Code, Codex, Cursor, Copilot y otros clientes MCP)

• Equipos que quieren integraciones de GrowSurf guiadas y asistidas por IA

Este servidor MCP NO es para:

• Usuarios solo de navegador que quieren una instalación local de stdio. ChatGPT web, Claude.ai y Claude Desktop no ejecutan un servidor MCP local, pero los tres se conectan a GrowSurf a través del conector remoto alojado en https://mcp.growsurf.com. Consulta la lista completa de clientes y la configuración en https://docs.growsurf.com/build-with-ai#mcp.

Related MCP server: SurfRank MCP Server

Lo que obtienes

• Integración guiada:

  • Instalación del código universal

  • Guía de implementación del SDK nativo para iOS/Android

  • Guía de la ventana nativa de GrowSurf

  • Flujo de registro

  • Flujo de acción de calificación

  • Seguimiento de ventas/transacciones de afiliados

  • Webhooks

• Recetas de agente:

  • Prompts de MCP para crear programas de referidos, crear programas de afiliados, incrustar el widget, listar y obtener programas y participantes, configurar recompensas, conectar webhooks y leer análisis

  • Paquete de habilidades de agente instalable en skills/growsurf-agent-toolkit

  • Orientación para revisar el contenido inicial de Diseño, Correos, Opciones, Instalación, recompensas y la ventana de GrowSurf antes de aplicar cambios

  • Prompts de evaluación de creación de programas de una sola vez y comprobaciones de aceptación para revisar el contenido inicial y la configuración

• Envoltorios de la API REST de ruta feliz:

  • Crear una cuenta y obtener una clave de API sin credenciales existentes

  • Leer y renombrar el equipo vinculado, solicitar la verificación del equipo y reenviar el correo de verificación del propietario del equipo

  • Listar y obtener campañas

  • Obtener análisis de campaña (totales, series temporales opcionales por período, métricas de correo, totales del período anterior, recuentos de estados y tasas)

  • Crear, actualizar y clonar programas (campañas)

  • Listar, crear, actualizar y eliminar recompensas de campaña

  • Obtener/actualizar la configuración de Diseño, Correos, Opciones e Instalación

  • Capturar capturas de pantalla temporales de vista previa de GrowSurf cuando el usuario pide explícitamente una prueba visual

  • Listar, crear, actualizar, eliminar y probar webhooks de programa

  • Listar, obtener y añadir participantes

  • Actualizar un participante, enviar un correo a un participante y obtener sus análisis y registros de actividad

  • Activar crédito de referido (para programas de referidos), con concesión retrasada opcional (1-90 días)

  • Cancelar una activación de referido retrasada pendiente (para programas de referidos)

  • Registrar venta/transacción de afiliado (para programas de afiliados)

  • Crear tokens de participante móvil para usuarios de aplicaciones nativas con sesión iniciada

• Fragmentos de la biblioteca oficial de la API:

  • TypeScript

  • Python

  • PHP

  • Ruby

  • Java

• Ayudantes:

  • Calcular el hash HMAC de autenticación automática de participante

  • Normalizar cargas útiles de webhook

  • Generar claves de idempotencia de mejor esfuerzo para la deduplicación de webhooks

Requisitos

• Node.js 22+

• Una cuenta de GrowSurf para OAuth alojado

• Una clave de API de GrowSurf para la configuración local de stdio o la configuración remota manual con clave de API. Una clave con ámbito funciona siempre que tenga acceso a las herramientas y programas que quieras que use el agente.

• Un ID de campaña (programa) para las herramientas con ámbito de campaña. Establece GROWSURF_CAMPAIGN_ID como valor predeterminado, pasa un argumento campaignId para apuntar a un programa específico, o llama a growsurf_list_campaigns para encontrar los programas disponibles. Para un programa recién creado, pasa el id devuelto por growsurf_create_campaign a las demás herramientas.

• Las herramientas de guía y fragmentos estáticos pueden ejecutarse sin credenciales

• Excepción: growsurf_create_account no necesita ninguna clave de API. Crea una nueva cuenta y devuelve una clave de API. Las herramientas a nivel de equipo no necesitan un ID de campaña.

• Cada herramienta listada publica indicaciones estándar de seguridad de MCP de solo lectura, destructivas, idempotentes y de mundo abierto. Las acciones empresariales con ámbito siguen disponibles; la rotación de claves de API no es intencionalmente una herramienta de MCP. Rota las claves en la configuración de GrowSurf o mediante un cliente REST/SDK directo.

CLI oficial

El paquete npm instala el comando growsurf-mcp. Ejecútalo sin una instalación global:

npx -y @growsurfteam/growsurf-mcp

La CLI inicia el servidor MCP local de stdio de GrowSurf. Establece GROWSURF_API_KEY para acciones respaldadas por la API y GROWSURF_CAMPAIGN_ID para un programa predeterminado. Los recursos públicos de desarrollo y la guía de integración estática funcionan sin credenciales.

Inspecciona el comando instalado sin iniciar el servidor stdio:

npx -y @growsurfteam/growsurf-mcp --help
npx -y @growsurfteam/growsurf-mcp --version

Hosts MCP compatibles

La ruta recomendada es el endpoint OAuth alojado de GrowSurf en https://mcp.growsurf.com cuando tu host admite HTTP Streamable remoto con OAuth. Usa el servidor local npx cuando tu host necesite un proceso stdio o configuración manual con clave de API. ¿Aún no tienes una cuenta de GrowSurf? Un agente puede conectarse al endpoint de incorporación alojado https://mcp.growsurf.com/onboard sin credenciales y llamar a growsurf_create_account para registrarse.

El servidor MCP de GrowSurf funciona con cualquier host compatible con MCP. Los ejemplos a continuación cubren algunos hosts basados en configuración y CLI. Para la lista completa y actual de clientes compatibles (incluidos ChatGPT web, Claude.ai, Claude Desktop, GitHub Copilot, Gemini CLI, Devin Desktop y Cline) con configuración paso a paso, consulta https://docs.growsurf.com/build-with-ai#mcp.

• Cursor

• Claude Code (basado en CLI)

• Antigravity

• Codex (basado en CLI)

Cursor

1. Abre o crea la configuración global de MCP de Cursor en ~/.cursor/mcp.json.

2. Añade un servidor llamado growsurf con el endpoint OAuth alojado:

{
  "mcpServers": {
    "growsurf": {
      "type": "http",
      "url": "https://mcp.growsurf.com"
    }
  }
}

Para stdio local en su lugar, usa:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Claude Code (basado en CLI)

Abre tu terminal y conecta Claude Code al endpoint OAuth alojado:

claude mcp add --transport http --scope user growsurf https://mcp.growsurf.com
claude mcp login growsurf

Para stdio local en su lugar, instala el servidor directamente en Claude Code:

claude mcp add growsurf \
  -e GROWSURF_API_KEY=your_api_key \
  -e GROWSURF_CAMPAIGN_ID=your_campaign_id \
  -- npx -y @growsurfteam/growsurf-mcp

Antigravity

1. Abre Antigravity.

2. Haz clic en el menú … en el panel de la derecha y selecciona MCP Servers.

3. Haz clic en Manage MCP Servers > View raw config.

4. Recomendado: en el archivo mcp_config.json, añade el endpoint OAuth alojado:

{
  "mcpServers": {
    "growsurf": {
      "serverUrl": "https://mcp.growsurf.com"
    }
  }
}

5. Guarda la configuración, abre Settings > Customizations y selecciona Authenticate para GrowSurf.

Para stdio local en su lugar, usa:

{
  "mcpServers": {
    "growsurf": {
      "command": "npx",
      "args": ["-y", "@growsurfteam/growsurf-mcp"],
      "env": {
        "GROWSURF_API_KEY": "YOUR_API_KEY",
        "GROWSURF_CAMPAIGN_ID": "YOUR_CAMPAIGN_ID"
      }
    }
  }
}

Codex

Recomendado: conecta Codex al endpoint OAuth alojado:

codex mcp add growsurf --url https://mcp.growsurf.com
codex mcp login growsurf

O crea o edita ~/.codex/config.toml:

[mcp_servers.growsurf]
url = "https://mcp.growsurf.com"

Para stdio local en su lugar, añade lo siguiente:

[mcp_servers.growsurf]
command = "npx"
args = ["-y", "@growsurfteam/growsurf-mcp"]

[mcp_servers.growsurf.env]
GROWSURF_API_KEY = "YOUR_API_KEY"
GROWSURF_CAMPAIGN_ID = "YOUR_CAMPAIGN_ID"

O configura stdio local desde la CLI:

codex mcp add growsurf \
  --env GROWSURF_API_KEY=YOUR_API_KEY \
  --env GROWSURF_CAMPAIGN_ID=YOUR_CAMPAIGN_ID \
  -- npx -y @growsurfteam/growsurf-mcp

Configuración

Establece las siguientes variables de entorno al ejecutar el servidor MCP:

• GROWSURF_API_KEY (opcional para el inicio; requerida para las herramientas que llaman a la API. Usa una clave con los ámbitos y el acceso a programas que esas herramientas necesiten)

• GROWSURF_CAMPAIGN_ID (opcional; el programa predeterminado para las herramientas con ámbito de campaña. El argumento campaignId de una herramienta lo anula, por lo que un solo servidor puede operar en cualquiera de tus programas)

• GROWSURF_API_BASE_URL (opcional; por defecto https://api.growsurf.com/v2. Útil para pasarelas MCP locales o alojadas que deban llamar a un origen diferente de la API de GrowSurf)

• GROWSURF_PARTICIPANT_AUTH_SECRET (opcional; usado por el ayudante de hash)

• GROWSURF_WEBHOOK_TOKEN (opcional; usado para tu propio esquema de token de URL de webhook)

Ejecutar con npx

Después de publicar este paquete, los clientes pueden ejecutar:

npx @growsurfteam/growsurf-mcp

Para desarrollo local en este repositorio:

npm install
npm run build
node dist/cli.js

Herramientas MCP

Cada herramienta declara un esquema de salida de MCP y devuelve structuredContent, para que los hosts conozcan la forma del resultado de cada herramienta. Las herramientas REST devuelven la respuesta de la API (más un bloque de texto JSON para clientes más antiguos); las herramientas de guía y fragmentos devuelven su documento markdown bajo markdown.

Integración guiada

• growsurf_integration_guide Guía paso a paso para implementar un programa de referidos o afiliados de GrowSurf.

• growsurf_mobile_sdk_guide Guía del SDK nativo para iOS/Android para atribución, shareUrl, trackShare y la ventana nativa de GrowSurf.

• growsurf_api_library_snippets Fragmentos de la biblioteca oficial de la API REST para TypeScript, Python, PHP, Ruby y Java.

• growsurf_get_integration_connect_link Obtén un enlace del panel que abre el panel de conexión de una integración específica (Stripe, PayPal, Tango Card, Mailchimp y muchos más). Entrégalo al usuario cuando quiera conectar una. La conexión se realiza en el panel, no a través de la API.

Fragmentos de cliente y UI

• growsurf_client_snippets SDK de JavaScript, ventana de GrowSurf y ejemplos incrustables. Incluye un recordatorio de usar un flujo de trabajo de diseño frontend al colocar o estilizar UI incrustable.

• growsurf_embeddable_element_snippet Fragmento HTML para un elemento incrustable específico de GrowSurf.

• growsurf_grsf_config_snippet Fragmento <head> para configurar window.grsfConfig y la autenticación automática de participante.

Incorporación de cuenta

• growsurf_create_account Crea una cuenta de GrowSurf y obtén una clave de API. Esta es la única herramienta que no requiere GROWSURF_API_KEY. La clave devuelta se muestra una vez y queda bloqueada (403 EMAIL_NOT_VERIFIED_ERROR) hasta que el propietario verifique su correo. La clave se rota en el primer inicio de sesión del propietario en el panel. Crear una cuenta acepta, en nombre del titular de la cuenta, los Términos de servicio y la Política de privacidad de GrowSurf.

Equipo

• growsurf_get_team Obtén el equipo vinculado a la clave de API o a la conexión OAuth, incluido su estado de verificación de GrowSurf.

• growsurf_update_team Actualiza el nombre para mostrar del equipo vinculado.

• growsurf_request_team_verification Solicita a GrowSurf que verifique el equipo vinculado, lo cual es necesario antes de que un programa pueda enviar correos a los participantes.

• growsurf_resend_team_owner_verification_email Reenvía el correo de verificación al propietario del equipo vinculado sin revelar su dirección de correo.

API y seguimiento

• growsurf_get_campaign Obtener la configuración de la campaña.

• growsurf_list_campaigns Listar los programas disponibles para la credencial. Úsalo para encontrar un campaignId antes de llamar a las herramientas específicas de campaña.

• growsurf_get_campaign_analytics Obtener las analíticas del programa, con series opcional por período, comparación, estado, tasa y datos de entrega de correo y participación mediante include=email.

• growsurf_create_campaign Crear un nuevo programa (campaña) con contenido inicial apropiado para el tipo y recompensas integradas opcionales (solo necesita GROWSURF_API_KEY, no GROWSURF_CAMPAIGN_ID). Revisa el contenido inicial de Diseño, Correos, Opciones, Instalación, recompensas y Ventana de GrowSurf antes de aplicar cambios.

• growsurf_agent_program_creation_eval Generar indicaciones de evaluación de creación de programas de una sola vez y comprobaciones de aceptación para el contenido inicial, recompensas conservadoras, revisión de configuración, prueba de instalación en el frontend y copia pública limpia.

• growsurf_update_campaign Actualizar la identidad y el ciclo de vida del programa: nombre, marca de la empresa y estado (solo se cambian los campos que envías).

• growsurf_clone_campaign Clonar el programa en un nuevo programa DRAFT (las integraciones y credenciales no se copian).

• growsurf_list_campaign_rewards Listar las recompensas configuradas del programa.

• growsurf_create_campaign_reward Crear una recompensa de campaña.

• growsurf_update_campaign_reward Actualizar una recompensa de campaña por su clave de recompensa.

• growsurf_delete_campaign_reward Eliminar una recompensa de campaña por su clave de recompensa.

• growsurf_get_campaign_design / growsurf_update_campaign_design Leer o modificar la configuración de diseño, incluida la pestaña Diseño del Editor de Programas y el texto de la página de confirmación del destino de pago.

• growsurf_get_campaign_emails / growsurf_update_campaign_emails Leer o modificar la configuración de la pestaña Correos del Editor de Programas.

• growsurf_get_campaign_options / growsurf_update_campaign_options Leer o modificar la configuración de la pestaña Opciones del Editor de Programas.

• growsurf_get_campaign_installation / growsurf_update_campaign_installation Leer o modificar la configuración de la pestaña Instalación del Editor de Programas.

• growsurf_capture_referral_flow_screenshots Capturar capturas de pantalla de vista previa temporales de GrowSurf para el programa actual después de que el usuario solicite explícitamente una prueba visual. Esto devuelve la Ventana del referidor controlada y la experiencia del amigo referido; usa la automatización del navegador en su lugar para demostrar el sitio instalado del usuario.

• growsurf_list_campaign_webhooks Listar los webhooks del programa (los secretos nunca se devuelven).

• growsurf_create_campaign_webhook Añadir un webhook al programa (con eventos y un secreto de firma de solo escritura).

• growsurf_update_campaign_webhook Actualizar un webhook por id (primary para el webhook principal del programa).

• growsurf_delete_campaign_webhook Eliminar un webhook por id.

• growsurf_test_campaign_webhook Enviar un evento de prueba en vivo a un webhook usando su URL y secreto almacenados.

• growsurf_add_participant Añadir un participante (o participante referido) durante el registro.

• growsurf_list_participants Listar los participantes del programa actual, paginados por nextId. Úsalo para encontrar un ID de participante antes de llamar a las herramientas específicas de participante.

• growsurf_get_participant Obtener un participante por ID de participante de GrowSurf o dirección de correo electrónico.

• growsurf_update_participant Actualizar un participante por ID o correo electrónico (incluidas las notes internas).

• growsurf_bulk_delete_participants Eliminar permanentemente hasta 200 participantes (por ID y/o correo electrónico, se permiten listas mixtas) en una sola solicitud, con resultados DELETED/NOT_FOUND/DUPLICATE/ERROR por fila. Irreversible: elimina las referencias, recompensas, comisiones y registros de pago de los participantes.

• growsurf_email_participant Enviar un correo electrónico a un participante usando una plantilla configurada o un asunto/cuerpo de formato libre.

• growsurf_get_participant_analytics Obtener la participación, clasificación, compartidos, ingresos de afiliado, comisión, pago y métricas de correo opcionales de un participante. Usa include=series, include=email o ambos separados por comas.

• growsurf_get_participant_activity_logs Listar los registros de actividad de un participante (paginados por offset/límite).

• growsurf_trigger_referral Activar la referencia (solo para programas de referidos). Opcionalmente, pasa delayInDays (1-90) para retener el crédito durante N días antes de otorgarlo (por ejemplo, para cubrir un período de reembolso).

• growsurf_cancel_delayed_referral Cancelar una activación de referencia retrasada pendiente antes de que transcurra el retraso (por ejemplo, en caso de reembolso/cancelación).

• growsurf_get_participant_payout_destination Obtener el estado del destino de pago de un participante en todos los proveedores habilitados para el programa (PayPal y/o Wise): estado por proveedor, correo de pago confirmado, tipo de destinatario legal y motivo de reparación.

• growsurf_request_participant_payout_destination_confirmation Pedir a un participante que confirme su destino de pago para un proveedor: le envía un enlace de confirmación de un solo uso (solo el participante puede confirmar).

• growsurf_record_sale Registrar ventas o transacciones de afiliado (solo para programas de afiliados).

• growsurf_refund_transaction Registrar una modificación (reembolso, reembolso parcial o contracargo) contra una transacción registrada; revierte o ajusta la comisión del referidor (solo para programas de afiliados). Es la operación inversa de growsurf_record_sale.

• growsurf_create_mobile_participant_token Crear u obtener un participante y, a continuación, crear un token de SDK móvil específico del participante para un usuario móvil con sesión iniciada.

Ayudantes

• growsurf_participant_auth_hash Generar hashes HMAC de autenticación automática de participantes (para autenticar participantes automáticamente).

• growsurf_webhook_normalize Normalizar las cargas útiles de webhook y generar claves de idempotencia (para deduplicar las entregas de webhooks).

Webhooks

Los webhooks de GrowSurf notifican a tu servidor cuando ocurren eventos importantes de referidos o afiliados, como cuando se crean nuevos objetos como participantes, referencias, recompensas o transacciones. Estos son casos de uso comunes:

• Cumplir recompensas automáticamente

• Mantener sistemas internos de puntos o créditos

• Sincronizar los datos de participantes y referencias en tu base de datos

Manejo de Entregas Duplicadas

Los manejadores de webhooks deben ser idempotentes porque el mismo evento puede llegar más de una vez. Almacena una clave de idempotencia antes de cambiar cualquier cosa en tu sistema.

Seguridad e Idempotencia de Webhooks

GrowSurf firma las entregas de webhooks cuando el webhook tiene un secret configurado: cada entrega incluye un encabezado HMAC GrowSurf-Signature calculado con ese secreto (el secreto es de solo escritura y nunca se devuelve). Para usar webhooks de forma segura, recomendamos lo siguiente:

• Configurar un secret en el webhook y verificar el encabezado GrowSurf-Signature al recibirlo

• Validar la forma de la carga útil y el tipo de evento esperado

• Deduplicar los eventos de webhook usando una clave de idempotencia, porque el mismo evento puede llegar más de una vez

El servidor MCP de GrowSurf proporciona una herramienta auxiliar (growsurf_webhook_normalize ) que normaliza las cargas útiles de webhook y genera una clave de idempotencia de mejor esfuerzo para simplificar el procesamiento seguro de webhooks.

Desarrollo y Pruebas

npm run dev
npm test

Recursos Adicionales

Lee la documentación para desarrolladores en los siguientes enlaces:

• Referencia del SDK de JavaScript: https://docs.growsurf.com/developer-tools/javascript-sdk/api-reference

• Referencia de la API REST: https://docs.growsurf.com/developer-tools/rest-api/api-reference

• Bibliotecas de la API REST: https://docs.growsurf.com/developer-tools/rest-api/api-libraries

• Guía para móviles nativos: https://docs.growsurf.com/getting-started-for-native-mobile

• SDK de iOS: https://docs.growsurf.com/developer-tools/ios-sdk

• SDK de Android: https://docs.growsurf.com/developer-tools/android-sdk

• Primeros pasos con GrowSurf: https://docs.growsurf.com/getting-started

El servidor MCP de GrowSurf ayuda a los clientes de GrowSurf a implementar programas de referidos y programas de afiliados rápidamente.