API, MCP y CLI

Genere claves de API para integrar graph8 con sus herramientas y flujos de trabajo. Conecte asistentes de IA mediante MCP o utilice la CLI para acceder desde la línea de comandos.

Nota

Esta página corresponde a las claves administradas por la organización o el administrador en Configuración.

Si está configurando MCP o la CLI como usuario final, vaya a Perfil -> Desarrollador y utilice su clave de API personal. Consulte Autenticación, Servidor MCP y CLI.

Credenciales personales vs. de organización

Tipo	Ubicación	Ideal para
Clave de API personal	Perfil -> Desarrollador	Configuración individual de MCP o CLI
Clave de API de organización	Configuración -> API (esta página)	Integraciones compartidas, tareas en segundo plano, automatización administrada

Creación de claves

Generar una nueva clave

1. Vaya a Configuración → API
2. Haga clic en Crear clave de API
3. Asigne un nombre a la clave (p. ej., “Sincronización CRM”, “Panel interno”)
4. Seleccione los permisos de acceso
5. Haga clic en Generar
6. Copie la clave de inmediato: no se mostrará nuevamente

Permisos de acceso

Cada clave puede limitarse a áreas específicas de la API:

• Contactos: lectura y escritura de registros de contactos
• Empresas: lectura y escritura de registros de empresas
• Listas: lectura y escritura de listas y audiencias
• Pipeline: lectura y escritura de oportunidades y etapas
• Secuencias: lectura y escritura de secuencias e inscripciones
• Análisis: lectura de datos analíticos
• Acceso completo: acceso sin restricciones a todos los endpoints

Otorgue únicamente los permisos que requiera su integración.

Gestión de claves

Visualización de claves

La página de configuración de API muestra todas las claves activas con:

• Nombre: la etiqueta asignada
• Permisos: las áreas de la API a las que puede acceder la clave
• Creada: cuándo se generó la clave
• Último uso: la llamada a la API más reciente realizada con esta clave

Rotación de una clave

Para reemplazar una clave sin interrupciones:

1. Cree una nueva clave con los mismos permisos
2. Actualice su integración para utilizar la nueva clave
3. Verifique que la integración funcione correctamente
4. Revoque la clave anterior

Revocación de una clave

1. Localice la clave en la lista
2. Haga clic en Revocar
3. Confirme la acción

Las claves revocadas dejan de funcionar de inmediato. Cualquier integración que utilice la clave recibirá errores de autenticación.

Límites de uso

Las solicitudes a la API tienen límites por clave y por plan:

Plan	Solicitudes/minuto	Solicitudes/día
Starter	60	10,000
Pro	120	50,000
Enterprise	300	Ilimitado

Cuando se supera el límite, la API devuelve una respuesta 429 Too Many Requests con un encabezado Retry-After.

Autenticación

Incluya su clave de API en el encabezado de la solicitud:

Authorization: Bearer your-api-key-here

Todas las solicitudes a la API deben realizarse mediante HTTPS.

Ejemplo de solicitud

curl -H "Authorization: Bearer your-api-key-here" \
     -H "Content-Type: application/json" \
     https://be.graph8.com/v1/contacts

Webhooks

Reciba notificaciones en tiempo real cuando ocurran eventos en graph8.

Configuración de webhooks

1. Vaya a Configuración → API → Webhooks
2. Haga clic en Agregar webhook
3. Introduzca la URL de su endpoint (debe ser HTTPS)
4. Seleccione los tipos de eventos a los que desea suscribirse
5. Guarde la configuración

Tipos de eventos

• contact.created: se agrega un nuevo contacto
• contact.updated: se modifica un registro de contacto
• deal.stage_changed: una oportunidad avanza a una nueva etapa
• deal.won / deal.lost: una oportunidad se cierra
• sequence.completed: un contacto finaliza una secuencia
• meeting.booked: se programa una cita

Política de reintentos

Si su endpoint devuelve una respuesta distinta de 2xx, graph8 vuelve a intentarlo:

• 3 intentos de reenvío
• Retroceso exponencial (1 min, 5 min, 30 min)
• Tras 3 fallos, el webhook se pausa y se le notifica

Seguridad de webhooks

Cada webhook incluye un encabezado de firma para su verificación. Utilice el secreto de firma (visible durante la creación del webhook) para confirmar que las solicitudes provienen de graph8.

Servidor MCP

El servidor MCP (Model Context Protocol) de graph8 permite que asistentes de IA como Claude Desktop, Cursor, Windsurf y Claude Code interactúen directamente con sus datos de graph8.

Modos

graph8 MCP opera en dos modos según su flujo de trabajo:

• Modo Desarrollador: para desarrolladores que crean productos. Incluye análisis de repositorios, instalación de infraestructura GTM, generación de campañas y búsqueda en la base de conocimiento. Todas las herramientas requieren un repo_id.
• Modo GTM: para gestores de campañas y profesionales de marketing. Explore campañas, edite textos, busque en la base de conocimiento, enriquezca contactos e inicie campañas de prospección, sin necesidad de repo_id.

Remoto (HTTP con streaming)

Los clientes compatibles con endpoints MCP remotos (Cursor, Claude Code, Windsurf) pueden conectarse directamente. La autenticación se gestiona mediante OAuth: no se requiere clave de API en la configuración.

{
  "mcpServers": {
    "graph8": {
      "url": "https://be.graph8.com/mcp/"
    }
  }
}

Su cliente le solicitará que inicie sesión mediante OAuth la primera vez que se conecte.

Local (stdio)

Para clientes que requieren un proceso local (Claude Desktop), instale el servidor MCP y proporcione su clave de API:

pip install g8-mcp-server

Modo Desarrollador:

{
  "mcpServers": {
    "graph8": {
      "command": "uvx",
      "args": ["g8-mcp-server"],
      "env": {
        "G8_API_KEY": "your-api-key-here",
        "G8_MCP_MODE": "dev"
      }
    }
  }
}

Modo GTM:

{
  "mcpServers": {
    "graph8": {
      "command": "uvx",
      "args": ["g8-mcp-server"],
      "env": {
        "G8_API_KEY": "your-api-key-here",
        "G8_MCP_MODE": "gtm"
      }
    }
  }
}

Anotaciones de herramientas

Cada herramienta MCP está anotada como solo lectura, escritura o destructiva, de modo que los clientes MCP (Claude Desktop, Cursor, Claude Code, etc.) puedan solicitar confirmación antes de ejecutar cualquier acción no trivial.

Anotación	Significado	Herramientas de ejemplo
solo lectura	Lee datos, nunca los modifica	g8_list_fields, g8_voice_get_dialer_stats, g8_search_contacts
escritura	Crea o actualiza datos	g8_create_field, g8_set_field_value, g8_voice_create_dialer_session
destructiva	Elimina o detiene algo	Eliminación de campos, g8_voice_stop_session

La mayoría de los clientes muestran una confirmación la primera vez que se invoca una herramienta de escritura o destructiva, para que pueda aprobar la acción antes de que afecte a sus datos.

Herramientas disponibles

Compartidas (todos los modos)

Herramienta	Descripción
g8_search_contacts	Buscar contactos por correo electrónico, nombre o lista
g8_get_contact	Obtener el perfil completo de un contacto
g8_search_companies	Buscar empresas por dominio o sector
g8_get_company	Obtener el perfil completo de una empresa
g8_lookup_person	Búsqueda instantánea de personas por correo electrónico o LinkedIn
g8_lookup_company	Búsqueda instantánea de empresas por dominio
g8_enrich_contacts	Iniciar el enriquecimiento para un lote de contactos
g8_verify_email	Verificar la capacidad de entrega de un correo electrónico
g8_create_sequence	Crear una nueva secuencia de prospección
g8_get_sequence_preview	Previsualizar los pasos de una secuencia antes de iniciarla
g8_update_sequence	Actualizar los metadatos de una secuencia
g8_update_sequence_step	Actualizar un paso individual de una secuencia
g8_pause_sequence	Pausar una secuencia activa
g8_resume_sequence	Reanudar una secuencia pausada
g8_get_sequence_analytics	Obtener métricas de rendimiento de una secuencia
g8_delete_sequence	Archivar una secuencia (eliminación lógica)
g8_list_inbox	Listar hilos de respuesta de correo electrónico, SMS y LinkedIn
g8_get_reply	Obtener un hilo de respuesta con sus mensajes
g8_assign_reply	Asignar una respuesta a un miembro del equipo
g8_tag_reply	Etiquetar un hilo de respuesta
g8_get_reply_draft	Generar un borrador de respuesta con IA (consume créditos)
g8_send_reply	Enviar una respuesta por correo electrónico, SMS o LinkedIn
g8_list_audience_syncs	Listar las configuraciones de sincronización de audiencias
g8_create_audience_sync	Crear una sincronización de audiencia con plataforma publicitaria
g8_get_audience_sync	Obtener detalles de la configuración de sincronización de audiencia
g8_update_audience_sync	Actualizar la configuración de sincronización de audiencia
g8_delete_audience_sync	Eliminar una sincronización de audiencia (eliminación lógica)
g8_trigger_audience_sync	Activar manualmente una ejecución de sincronización
g8_get_audience_sync_runs	Ver el historial de ejecuciones de sincronización
g8_get_audience_sync_errors	Ver los registros de errores de sincronización
g8_list_crm_syncs	Listar las integraciones de CRM conectadas
g8_push_to_crm_contact	Enviar contactos a un CRM
g8_push_to_crm_company	Enviar empresas a un CRM
g8_push_to_crm_list	Enviar membresías de listas a un CRM
g8_get_crm_fields	Descubrir las asignaciones de campos del CRM
g8_get_crm_status	Verificar el estado de la conexión con el CRM
g8_list_fields	Descubrir columnas o campos personalizados en contactos y empresas
g8_create_field	Crear una nueva columna personalizada en contactos o empresas
g8_set_field_value	Establecer el valor de una columna personalizada en un contacto o empresa específico
g8_voice_list_dialer_sessions	Listar sesiones del marcador paralelo y su estado
g8_voice_get_dialer_stats	Leer datos analíticos del marcador (llamadas, conexiones, tiempo de conversación, disposiciones)
g8_voice_list_agents	Listar los agentes de voz disponibles para llamadas
g8_voice_create_dialer_session	Crear una nueva sesión del marcador vinculada a una lista
g8_voice_pause_session	Pausar una sesión activa del marcador
g8_voice_resume_session	Reanudar una sesión pausada del marcador
g8_voice_stop_session	Detener una sesión del marcador de forma permanente

Modo Desarrollador

Herramienta	Descripción
g8_connect_repo	Conectar un repositorio de GitHub o GitLab
g8_scan_repo	Analizar el repositorio en busca del conjunto tecnológico y la preparación GTM
g8_get_scan_results	Obtener los resultados del análisis de un repositorio
g8_status	Obtener el estado actual del repositorio
g8_doctor	Ejecutar verificaciones de estado en la instalación GTM
g8_install_spine	Generar parches de instalación GTM
g8_apply_install	Aplicar los parches generados al código base
g8_list_campaigns	Listar las campañas de un repositorio
g8_get_campaign	Obtener los detalles de una campaña
g8_search_kb	Buscar en la base de conocimiento del repositorio
g8_list_kb_documents	Listar todos los documentos de la base de conocimiento

Modo GTM

Herramienta	Descripción
g8_list_campaigns	Listar las campañas de la organización
g8_get_campaign	Obtener los detalles completos de la campaña y sus documentos
g8_get_campaign_document	Obtener el contenido de un documento (briefings, textos, etc.)
g8_create_campaign	Crear una nueva campaña
g8_update_campaign	Actualizar los campos de una campaña
g8_launch_campaign	Iniciar una campaña de prospección
g8_search_kb	Buscar en la base de conocimiento
g8_list_kb_documents	Listar todos los documentos de la base de conocimiento

CLI

La CLI de graph8 ofrece las mismas herramientas MCP como interfaz de línea de comandos. Instálela junto con el servidor MCP:

pip install g8-mcp-server

Ejecute una herramienta directamente:

g8 status --repo-id <repo-id>
g8 scan --repo-id <repo-id>
g8 doctor --repo-id <repo-id>

# Sequence management
g8 create-sequence --name "Q2 Outbound" --steps '[...]'
g8 pause-sequence --sequence-id <id>
g8 sequence-analytics --sequence-id <id>

# Inbox
g8 inbox-list --channel email --limit 20
g8 inbox-draft --reply-id <thread-id>
g8 inbox-send --reply-id <thread-id> --channel email --body "Thanks for your reply"

# Audience & CRM sync
g8 sync-audience-list
g8 sync-audience-trigger --config-id <id>
g8 sync-crm-push --provider hubspot --records '[...]'

Configure su clave de API como variable de entorno:

export G8_API_KEY=your-api-key-here

Preguntas frecuentes

¿Puedo tener varias claves de API?

Sí. Cree claves separadas para cada integración o entorno (producción, staging, pruebas).

¿Qué ocurre si pierdo mi clave de API?

Las claves de API no pueden recuperarse después de su creación. Revoque la clave perdida y genere una nueva.

¿Hay SDKs disponibles?

Consulte la documentación de la API de graph8 para conocer las bibliotecas de cliente y las referencias de SDK disponibles.

¿Puedo probar webhooks de forma local?

Utilice un servicio de túnel para exponer su endpoint local durante el desarrollo. Apunte la URL del webhook a la dirección de su túnel.

¿Necesito una clave de API para conexiones MCP remotas?

No. Las conexiones MCP remotas (Cursor, Claude Code, Windsurf) usan OAuth para la autenticación. Solo necesita una clave de API para el modo stdio local (Claude Desktop) o para llamadas directas a la API.

¿Qué modo MCP debo utilizar?

Utilice el Modo Desarrollador si está creando un producto y desea analizar repositorios, instalar infraestructura GTM y generar campañas desde el código. Utilice el Modo GTM si gestiona campañas, redacta textos o ejecuta acciones de prospección: no requiere un repositorio.

---

Consejo

Cree claves de API separadas por integración para poder revocar una sin afectar a las demás.