# API, MCP y CLI

> Cree y gestione claves de API, conecte herramientas MCP y configure la CLI.

Source: https://docs.graph8.com/es/settings/api/

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.

> **Note:**
> 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](https://docs.graph8.com/developers/authentication/), [Servidor MCP](https://docs.graph8.com/developers/mcp/) y [CLI](https://docs.graph8.com/developers/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

```bash
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.

```json
{
  "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:

```bash
pip install g8-mcp-server
```

**Modo Desarrollador:**

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

**Modo GTM:**

```json
{
  "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` | Registrar el conjunto tecnológico y la preparación GTM que leíste del código |
| `g8_get_scan_results` | Obtener los resultados del análisis de un repositorio |
| `g8_status` | Obtener el estado actual del repositorio |
| `g8_doctor` | Informar el estado del lado graph8 de la instalación GTM de un repo |
| `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:

```bash
pip install g8-mcp-server
```

Ejecute una herramienta directamente:

```bash
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:

```bash
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.

---

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