# Configuración de n8n

> Conectar n8n a graph8 mediante MCP usando el endpoint remoto con una clave de API Bearer

Source: https://docs.graph8.com/es/developers/n8n-setup/

Conecte n8n a graph8 para automatizar flujos de trabajo con sus campañas, cuentas, contactos y datos de inteligencia.

> **Tip:**
> n8n se ejecuta de forma headless, por lo que **no** usa el flujo interactivo de OAuth por navegador. En su lugar, se autentica en el servidor MCP remoto de graph8 con una **clave de API personal o de organización** enviada como encabezado `Authorization: Bearer`. No hay `session_id` que copiar ni archivo de configuración con `session_id` — eso pertenecía a un flujo dado de baja.

## ¿Qué es n8n?

[n8n](https://n8n.io) es una herramienta de automatización de flujos de trabajo de código abierto. Con la integración MCP de graph8 puede:

- Activar flujos de trabajo cuando cambian campañas, oportunidades o contactos
- Sincronizar datos de graph8 con su CRM o almacén de datos
- Crear automatizaciones personalizadas con las herramientas y el índice de graph8

## Requisitos previos

- Una instancia de n8n (autohospedada o en la nube)
- Una cuenta de graph8 ([empiece gratis](https://auth.graph8.com/en/signup) — 1000 créditos, sin tarjeta)
- Una clave de API de graph8:
  - **Clave de API personal** — **Perfil → Developer** (limitada a usted dentro de la organización activa), o
  - **Clave de API de organización** — **Configuración → API** (solo administradores; para automatizaciones compartidas o de servicio)

> **Note:**
> Guarde la clave de API en las **Credenciales** de n8n, no incrustada en los nodos. Así la rota en un solo lugar. Las claves de API de graph8 son de larga duración — no expiran tras 24 horas de inactividad, por lo que no hay "renovación de sesión" por ejecución que gestionar.

## Configuración

Hay dos formas de llamar a graph8 desde n8n. Ambas apuntan al mismo endpoint:

```
https://be.graph8.com/mcp/
```

**Nodo MCP Client Tool**

Las versiones recientes de n8n incluyen un nodo nativo **MCP Client Tool**.

1. **Agregue el nodo MCP Client Tool** a su flujo de trabajo (o conéctelo a un nodo AI Agent como herramienta).

2. **Establezca la URL del servidor**

```
   https://be.graph8.com/mcp/
```

3. **Configure la autenticación como Header Auth**

   Agregue una credencial de encabezado:

   | Campo | Valor |
   |-------|-------|
   | Nombre | `Authorization` |
   | Valor | `Bearer YOUR_G8_API_KEY` |

   Reemplace `YOUR_G8_API_KEY` con su clave de API personal o de organización (comienzan con `g8_`).

4. **Seleccione herramientas y ejecute**

   El nodo lista las herramientas de graph8 que su rol permite. Elija una herramienta (por ejemplo `g8_list_campaigns`) y ejecute el nodo para verificar la conexión.

**Nodo HTTP Request**

Si su versión de n8n no tiene nodo MCP, llame al endpoint JSON-RPC con un nodo **HTTP Request**:

```json
{
  "method": "POST",
  "url": "https://be.graph8.com/mcp/",
  "headers": {
    "Authorization": "Bearer YOUR_G8_API_KEY",
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "g8_list_campaigns",
      "arguments": {
        "status": "active"
      }
    },
    "id": 1
  }
}
```

Guarde la clave de API como una credencial **Header Auth** de n8n y refiérala desde el nodo en lugar de pegarla en el cuerpo o la URL.

## Acciones disponibles

Una vez conectado, sus flujos de trabajo de n8n pueden llamar a cualquier herramienta MCP de graph8 que su rol permita. Los nombres de las herramientas llevan el prefijo `g8_`. Algunas comunes:

> **Note:**
> Los nombres exactos de las herramientas **dependen del modo**. Cuando el endpoint se ejecuta en modo combinado `all`, las herramientas de GTM llevan un espacio de nombres — por ejemplo `g8_gtm_list_campaigns` en lugar de `g8_list_campaigns`. Los nombres sin prefijo de abajo son la forma canónica; el nodo MCP lista los nombres exactos que su rol permite, y siempre puede confirmarlos en la [Referencia de herramientas MCP](https://docs.graph8.com/developers/mcp-tools/).

| Herramienta | Descripción |
|------|-------------|
| `g8_list_campaigns` | Lista campañas con un filtro de estado opcional |
| `g8_get_campaign` | Obtiene los detalles de una campaña específica |
| `g8_search_companies` | Busca empresas que ya están en su CRM |
| `g8_find_companies` | Busca en el índice de empresas de graph8 nuevas cuentas |
| `g8_search_contacts` | Busca contactos que ya están en su CRM |
| `g8_get_deals` | Lista oportunidades del pipeline con filtros de etapa/texto |
| `g8_list_intelligence_data` | Lista datos de inteligencia (scrapes, enriquecimiento, investigación de competidores) |
| `g8_tool_search` | Descubre y activa otras herramientas por palabra clave |

Para la lista completa con parámetros y formatos de respuesta, consulte la [Referencia de herramientas MCP](https://docs.graph8.com/developers/mcp-tools/).

## Ejemplos de flujos de trabajo

### Sincronizar nuevas campañas con Slack

1. **Activador**: programado (cada hora) o webhook
2. **Herramienta de graph8**: `g8_list_campaigns` con `status="active"`
3. **Nodo de filtro**: solo campañas nuevas desde la última ejecución
4. **Nodo Slack**: publicar en #marketing

### Enriquecer el CRM con inteligencia de empresa

1. **Activador**: webhook desde el CRM (nueva oportunidad creada)
2. **Herramienta de graph8**: `g8_find_companies` (o `g8_search_companies`) por nombre
3. **Herramienta de graph8**: `g8_list_intelligence_data` para la empresa
4. **Nodo HTTP**: actualizar el registro del CRM con los datos de inteligencia

### Reporte diario del pipeline

1. **Activador**: programado (9 a. m. diariamente)
2. **Herramienta de graph8**: `g8_get_deals`
3. **Nodo de código**: resumir el pipeline por etapa
4. **Nodo de correo**: enviar el reporte al equipo comercial

## Solución de problemas

Aquí encontrará los detalles específicos de n8n. Los problemas genéricos de MCP (autenticación, permisos, nombres de herramientas, tiempos de espera) se responden en el [FAQ de MCP](https://docs.graph8.com/developers/mcp-faq/).

### Errores de ejecución de flujos de trabajo

- Utilice **Execute Workflow** de n8n en modo paso a paso para identificar qué nodo falla
- Inspeccione el cuerpo de la respuesta del nodo HTTP Request / MCP para ver el error real del servidor
- En n8n autohospedado, revise los registros del contenedor para detectar errores a nivel de conexión

### Otros problemas

- Autenticación fallida → [FAQ](https://docs.graph8.com/developers/mcp-faq/#authentication-failed-or-401) (verifique el encabezado `Authorization: Bearer` y que la clave no esté revocada)
- Herramienta no encontrada → [FAQ](https://docs.graph8.com/developers/mcp-faq/#tool-not-found)
- Límite de tasa (50 rps) → [FAQ](https://docs.graph8.com/developers/mcp-faq/#what-is-the-rate-limit)
- Tiempos de espera en herramientas de larga duración → [FAQ](https://docs.graph8.com/developers/mcp-faq/#why-does-my-tool-call-time-out)

## Credenciales y claves

- Guarde la clave de API como una credencial **Header Auth** de n8n (`Authorization: Bearer g8_...`) para rotarla en un solo lugar.
- Revoque o rote claves desde **Perfil → Developer** (personal) o **Configuración → API** (organización). La revocación es inmediata — la siguiente llamada devuelve 401.
- Prefiera una clave de API de organización dedicada para automatizaciones en producción, de modo que quede desacoplada de la cuenta de una sola persona.

## Preguntas frecuentes

### ¿Puedo usar n8n Cloud o necesito una instancia autohospedada?

Ambas funcionan. Las instancias de n8n Cloud y las autohospedadas se conectan a graph8 de la misma forma — el endpoint remoto con una clave de API Bearer. El método del nodo HTTP Request funciona universalmente si su versión no tiene nodo MCP.

### ¿Necesito hacer el inicio de sesión OAuth por navegador como en Claude Desktop?

No. El flujo OAuth por navegador es para clientes interactivos (Claude, Cursor, etc.). n8n es headless y se autentica con una clave de API en el encabezado `Authorization`.

### ¿Existen límites de tasa en las llamadas MCP desde n8n?

Sí — 50 solicitudes por segundo y 1000 por minuto por organización en REST, SDK y MCP. Añada pausas en flujos de alto volumen; un pico por encima del límite devuelve HTTP 429 con un encabezado `Retry-After`.

### ¿Puedo activar flujos de trabajo de n8n desde graph8?

Utilice webhooks. Configure un webhook saliente en graph8 que llame a la URL de activación del webhook de n8n cuando ocurran eventos (campaña creada, inteligencia completada, etc.).

### ¿Cómo pruebo las llamadas MCP antes de construir flujos de trabajo completos?

Ejecute un solo nodo con una herramienta de solo lectura como `g8_list_campaigns` y use el botón **Execute step** de n8n para inspeccionar la respuesta antes de conectarla al resto del flujo.

## Recursos relacionados

- [Descripción general de MCP](https://docs.graph8.com/developers/mcp)
- [Qué puede consultar](https://docs.graph8.com/developers/what-you-can-ask/)
- [Plataformas de automatización](https://docs.graph8.com/developers/automation-platforms/)