# Servidor MCP

> Conecte agentes de codificación con IA a graph8 mediante el Protocolo de Contexto de Modelo

Source: https://docs.graph8.com/es/developers/mcp/

El servidor MCP de graph8 conecta agentes de codificación con IA (Claude Code, Cursor, Windsurf, Claude Desktop) a su espacio de trabajo de graph8. Expone herramientas para búsqueda de contactos, gestión de campañas, instalación de fragmentos de seguimiento y generación de formularios progresivos, todo desde su IDE.

> **Tip:**
> Pruebe el nivel de desarrollador gratis: 1.000 créditos, sin necesidad de tarjeta. [Comience aquí](https://auth.graph8.com/en/signup).
>
> Agentes de IA: obtenga el índice completo de documentación en [https://docs.graph8.com/llms.txt](https://docs.graph8.com/llms.txt).

## Configuración personal vs. de administrador

La mayoría de los usuarios deben utilizar la **configuración MCP personal desde el Perfil**. No necesita acceso de administrador de la organización.

| Caso de uso | Dónde configurarlo | Credencial |
|----------|---------------------|------------|
| MCP personal en Claude Desktop, Cursor, Windsurf, Claude Code | **Perfil -> Desarrollador** | Clave API personal (para local) u OAuth (para remoto) |
| Automatización de organización compartida e integraciones gestionadas por el administrador | **Configuración -> API** | Clave API de la organización |

> **Tip:**
> Si es un usuario sin privilegios de administrador y desea MCP para uso personal, utilice el flujo personal en **Perfil**. No utilice la configuración de API de organización, reservada exclusivamente para administradores.

## Configuración

Hay dos formas de conectarse: **Remota** (recomendada) y **Local**. La conexión remota utiliza OAuth: no requiere clave API ni instalación. La conexión local ejecuta el servidor en su máquina mediante stdio.

### Remota (OAuth), recomendada

Pegue esta configuración en su cliente de IA. Su cliente le solicitará iniciar sesión mediante OAuth la primera vez que se conecte. No se necesita clave API.

**Claude.ai**

1. Vaya a **Customize > Connectors > Add custom connector**
2. Pegue la URL del servidor: `https://be.graph8.com/mcp/`
3. Haga clic en **Add** y luego en **Connect**
4. Autorice cuando se le solicite (una sola vez)

**Claude Desktop**

1. Vaya a **Settings > MCP Servers > Add**
2. Pegue la URL del servidor: `https://be.graph8.com/mcp/`
3. Autorice cuando se le solicite (una sola vez)

**Claude Code**

Añada a `~/.claude/mcp.json`:

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

**Cursor**

Añada a `.cursor/mcp.json` en la raíz de su proyecto:

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

**Windsurf**

Añada a su configuración MCP de Windsurf:

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

**ChatGPT**

1. Vaya a **Settings > Apps > Developer Mode**
2. Añada el servidor MCP y pegue: `https://be.graph8.com/mcp/`
3. Autorice mediante OAuth

> **Tip:**
> El modo remoto gestiona la autenticación automáticamente mediante OAuth. La primera vez que utilice una herramienta de graph8, su cliente abrirá una ventana del navegador para iniciar sesión. No se necesita clave API, variables de entorno ni instalación de Python.
>
> En graph8, las sesiones OAuth remotas activas aparecen en **Perfil -> Conexiones**. Las configuraciones locales de Claude Desktop y stdio permanecen en **Perfil -> Desarrollador** porque utilizan su clave API personal en lugar de una sesión OAuth.

## Guías de configuración

Elija su cliente. Cada guía cubre las variantes de OAuth remoto y stdio local.

**Cursor**

    Cursor IDE con OAuth remoto o stdio local.
    [Abrir guía](https://docs.graph8.com/developers/cursor-setup/)

**Claude Desktop**

    La aplicación de escritorio de Anthropic con clave API personal o de organización.
    [Abrir guía](https://docs.graph8.com/developers/claude-desktop-setup/)

**Claude Code**

    El agente de terminal de Anthropic mediante `~/.claude/mcp.json`.
    [Abrir guía](https://docs.graph8.com/developers/claude-code-setup/)

**VS Code**

    MCP nativo mediante `.vscode/mcp.json` para el modo Copilot Agent.
    [Abrir guía](https://docs.graph8.com/developers/vscode-setup/)

**n8n**

    Automatización de flujos de trabajo mediante el nodo MCP o solicitud HTTP.
    [Abrir guía](https://docs.graph8.com/developers/n8n-setup/)

**LangChain**

    `langchain-mcp-adapters` + LangGraph para agentes en Python.
    [Abrir guía](https://docs.graph8.com/developers/langchain-setup/)

**LlamaIndex**

    `llama-index-tools-mcp` para agentes Python tipados.
    [Abrir guía](https://docs.graph8.com/developers/llamaindex-setup/)

**CrewAI**

    `MCPServerAdapter` para equipos multiagente.
    [Abrir guía](https://docs.graph8.com/developers/crewai-setup/)

**Pydantic AI**

    Salidas de agente tipadas con `MCPServerHTTP` y `MCPServerStdio`.
    [Abrir guía](https://docs.graph8.com/developers/pydantic-ai-setup/)

**OpenAI Agents SDK**

    MCP nativo mediante `MCPServerStreamableHttp`.
    [Abrir guía](https://docs.graph8.com/developers/openai-sdk-setup/)

**Ejemplos de extremo a extremo**

    Seis flujos de trabajo completos que encadenan herramientas MCP.
    [Abrir guía](https://docs.graph8.com/developers/mcp-examples/)

**Qué puede preguntar**

    Patrones de prompts en lenguaje libre y flujos de trabajo compatibles.
    [Abrir guía](https://docs.graph8.com/developers/what-you-can-ask/)

## Claude Desktop (MCP local)

Utilice Claude Desktop cuando quiera las herramientas de graph8 directamente dentro de la aplicación de escritorio con MCP local y su clave API personal.

1. Vaya a **Perfil -> Desarrollador**
2. Copie la configuración MCP local para el modo que desee (`gtm`, `dev` o `all`)
3. Péguela en la configuración MCP de Claude Desktop
4. Reinicie Claude Desktop

Para un recorrido paso a paso, consulte la [guía de configuración de Claude Desktop](https://docs.graph8.com/developers/claude-desktop-setup/).

## Claude.ai (Actions)

Claude.ai utiliza acciones basadas en el navegador en lugar de MCP local.

1. Genere una **clave API personal** en **Perfil -> Desarrollador**
2. Utilice las acciones OpenAPI de graph8 con autenticación Bearer
3. Llame a las API de graph8 desde Claude.ai usando sus credenciales personales

Utilice esta opción cuando desee búsqueda de cuentas en el navegador, inteligencia de empresas y acciones de flujo de trabajo sin ejecutar un servidor MCP local.

## ChatGPT (Actions)

ChatGPT también utiliza acciones basadas en el navegador en lugar de MCP local.

1. Genere una **clave API personal** en **Perfil -> Desarrollador**
2. Importe el OpenAPI de graph8 en su GPT o capa de acciones
3. Autentíquese con Bearer auth usando su clave API personal

Esta es la mejor opción para investigación de cuentas, búsqueda de contactos y elaboración de secuencias en flujos de trabajo del navegador con ChatGPT.

### Local (stdio)

Si prefiere ejecutar el servidor localmente (o su cliente no admite MCP remoto), utilice el transporte stdio. Esto requiere Python 3.10+ y una clave API.

Reemplace `<your-api-key>` con:

- su **clave API personal** de **Perfil -> Desarrollador** (recomendada para usuarios finales), o
- una **clave API de organización** de **Configuración -> API** (integraciones de administrador o compartidas).

**Developer Mode**

Para desarrolladores en Cursor, Windsurf o Claude Code:

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

**GTM Mode**

Para gestores de campañas en Claude Desktop:

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

`uvx` ejecuta el servidor directamente desde PyPI sin instalarlo. Si prefiere instalarlo de forma permanente, utilice `pip install g8-mcp-server`, aunque esto es principalmente para la [CLI](https://docs.graph8.com/developers/cli/).

#### Variables de entorno (solo local)

| Variable | Requerida | Predeterminado | Descripción |
|----------|----------|---------|-------------|
| `G8_API_KEY` | Sí | — | Su clave API personal (Perfil) o clave API de organización (Configuración -> API) ([detalles](https://docs.graph8.com/developers/authentication/)) |
| `G8_MCP_MODE` | No | `all` | Conjunto de herramientas a cargar: `dev`, `gtm` o `all` |
| `G8_API_URL` | No | `https://be.graph8.com` | URL base de la API (para instancias propias o entornos de prueba) |

## Modos

La variable `G8_MCP_MODE` controla qué herramientas se cargan. Esto aplica solo a conexiones locales (stdio); las conexiones remotas cargan todas las herramientas.

### Modo Desarrollador (`dev`)

Para desarrolladores que crean productos en Cursor, Windsurf o Claude Code. Proporciona herramientas con alcance de repositorio para analizar bases de código, instalar seguimiento, generar formularios y gestionar campañas.

**Establecer:** `G8_MCP_MODE=dev`

### Modo GTM (`gtm`)

Para gestores de campañas y operaciones de marketing en Claude Desktop. Proporciona herramientas con alcance de organización para crear campañas, explorar contenido de la base de conocimiento y ejecutar prospección, sin necesidad de contexto de repositorio.

**Establecer:** `G8_MCP_MODE=gtm`

### Modo All (predeterminado)

Carga todas las herramientas heredadas para compatibilidad con versiones anteriores. Si no establece `G8_MCP_MODE`, este es el modo predeterminado.

**Establecer:** `G8_MCP_MODE=all` (o no incluya la variable)

### Alcance de conjunto de herramientas en la URL remota (próximamente)

Actualmente, el endpoint OAuth remoto `https://be.graph8.com/mcp/` carga todas las herramientas que su rol permite. El alcance por conjunto de herramientas está en la hoja de ruta para que distintos clientes puedan cargar solo las herramientas que necesitan:

- `https://be.graph8.com/mcp/?mode=dev` - cargar solo las 17 herramientas de desarrollador
- `https://be.graph8.com/mcp/?mode=gtm` - cargar solo las 23 herramientas GTM
- `https://be.graph8.com/mcp/?groups=audience-sync,inbox` - cargar grupos de herramientas específicos

Esto forma parte de la hoja de ruta, aún no está disponible. Utilice `G8_MCP_MODE` en stdio mientras tanto.

## Herramientas disponibles

Para la referencia completa por herramienta (parámetros, formatos de respuesta, ejemplos JSON, advertencias), consulte la [Referencia de herramientas MCP](https://docs.graph8.com/developers/mcp-tools/). Las tablas a continuación son un índice rápido.

### Herramientas de plataforma (todos los modos)

Disponibles en todos los modos: operaciones principales de contactos y empresas.

| Herramienta | Descripción |
|------|-------------|
| `g8_search_contacts` | Buscar contactos que ya están en su CRM |
| `g8_search_companies` | Buscar empresas que ya están en su CRM |
| `g8_find_contacts` | Buscar en el índice de datos abiertos de 700M+ de graph8 para nuevos prospectos (consume créditos) |
| `g8_find_companies` | Buscar en el índice de datos abiertos de graph8 para nuevas empresas (consume créditos) |
| `g8_lookup_person` | Enriquecer una sola persona: devuelve el perfil completo (2 créditos, solo se cobran si hay coincidencia) |
| `g8_lookup_company` | Enriquecer una sola empresa: devuelve datos firmográficos (2 créditos, solo se cobran si hay coincidencia) |
| `g8_create_contact` | Crear un contacto en su CRM |
| `g8_enrich_contacts` | Enriquecer contactos existentes del CRM con datos de terceros; opciones `providers[]` + `email_verification` (consume créditos) |
| `g8_get_lists` | Listar listas de contactos y empresas |
| `g8_create_list` | Crear una lista vacía de contactos o empresas |
| `g8_add_to_list` | Añadir contactos existentes a una lista |
| `g8_build_contact_list` | Buscar y guardar prospectos que coincidan en una nueva lista (consume créditos) |
| `g8_get_deals` | Listar oportunidades con filtros de etapa o pipeline |
| `g8_get_deal` | Obtener una sola oportunidad |
| `g8_get_pipeline` | Listar pipelines y etapas de oportunidades |
| `g8_get_tasks` | Listar tareas con filtros |
| `g8_create_task` | Crear una tarea vinculada a un contacto |
| `g8_get_activities` | Listar actividades recientes del CRM |
| `g8_create_note` | Añadir una nota a un contacto |
| `g8_list_sequences` | Listar secuencias outbound |
| `g8_add_to_sequence` | Añadir un contacto a una secuencia de prospección |

### Gestión de secuencias (todos los modos)

Control completo del ciclo de vida de las secuencias de prospección.

| Herramienta | Descripción |
|------|-------------|
| `g8_create_sequence` | Crear una nueva secuencia con pasos, canales y programación |
| `g8_get_sequence_preview` | Previsualizar los pasos y canales de una secuencia antes de iniciarla |
| `g8_update_sequence` | Actualizar el nombre, la descripción o los indicadores de una secuencia |
| `g8_update_sequence_step` | Actualizar un solo paso (plantilla, temporización, canal) |
| `g8_pause_sequence` | Pausar una secuencia activa (sin nuevos envíos hasta que se reanude) |
| `g8_resume_sequence` | Reanudar una secuencia pausada |
| `g8_get_sequence_analytics` | Obtener métricas de rendimiento (tasa de respuesta, finalización, interacción) |
| `g8_delete_sequence` | Archivar una secuencia (eliminación lógica) |

> **Caution:**
> Pausar, reanudar y eliminar secuencias afectan la prospección activa. Estas herramientas requieren confirmación antes de ejecutarse.

### Bandeja de entrada y respuestas (todos los modos)

Gestione hilos de respuesta por correo electrónico, SMS y LinkedIn desde una superficie unificada.

| Herramienta | Descripción |
|------|-------------|
| `g8_list_inbox` | Listar hilos de respuesta, filtrables por canal, secuencia, estado, responsable o etiqueta |
| `g8_get_reply` | Obtener un solo hilo de respuesta con el historial completo de mensajes |
| `g8_assign_reply` | Asignar un hilo de respuesta a un miembro del equipo |
| `g8_tag_reply` | Etiquetar un hilo de respuesta para su categorización |
| `g8_get_reply_draft` | Generar un borrador de respuesta con IA basado en el contexto de la conversación (consume créditos) |
| `g8_send_reply` | Enviar una respuesta por correo electrónico, SMS o LinkedIn |

> **Caution:**
> `g8_send_reply` envía un mensaje real al contacto. `g8_get_reply_draft` consume créditos para la generación con IA.

### Audiencias y sincronización con CRM (todos los modos)

Envíe audiencias a plataformas publicitarias y sincronice contactos con CRMs.

| Herramienta | Descripción |
|------|-------------|
| `g8_list_audience_syncs` | Listar las sincronizaciones de audiencias configuradas |
| `g8_create_audience_sync` | Crear una sincronización con Meta, LinkedIn Ads, Google Ads o X |
| `g8_get_audience_sync` | Obtener los detalles de configuración de una sincronización |
| `g8_update_audience_sync` | Actualizar la cadencia, el modo o las listas de supresión de una sincronización |
| `g8_delete_audience_sync` | Eliminar una configuración de sincronización (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 con recuentos de registros |
| `g8_get_audience_sync_errors` | Ver los registros de errores de ejecuciones de sincronización fallidas |
| `g8_list_crm_syncs` | Listar integraciones CRM conectadas (HubSpot, Salesforce, Pipedrive, Zoho, SugarCRM) |
| `g8_push_to_crm_contact` | Enviar contactos a un proveedor CRM |
| `g8_push_to_crm_company` | Enviar empresas a un proveedor CRM |
| `g8_push_to_crm_list` | Enviar membresías de listas a un proveedor CRM |
| `g8_get_crm_fields` | Descubrir los mapeos de campos disponibles para un proveedor CRM |
| `g8_get_crm_status` | Verificar el estado de la conexión CRM y los límites de velocidad |

### Herramientas de desarrollador (modo `dev`)

Herramientas con alcance de repositorio para integrar graph8 en su base de código.

| Herramienta | Descripción |
|------|-------------|
| `g8_connect_repo` | Conectar un repositorio de GitHub/GitLab a graph8 |
| `g8_scan_repo` | Registrar los resultados del análisis que produjiste leyendo el código (graph8 no analiza en el servidor) |
| `g8_get_scan_results` | Obtener los resultados del análisis (frameworks, páginas, componentes) |
| `g8_status` | Verificar el estado de integración del repositorio |
| `g8_doctor` | Informar el estado del lado graph8 de un repo: conexión, write key, análisis, patch set |
| `g8_install_spine` | Generar un plan de instalación de seguimiento |
| `g8_apply_install` | Aplicar la instalación de seguimiento |
| `g8_list_campaigns` | Listar campañas de un repositorio |
| `g8_get_campaign` | Obtener detalles de una campaña |
| `g8_search_kb` | Buscar artículos en la base de conocimiento |
| `g8_list_kb_documents` | Listar todos los documentos de la base de conocimiento |

### Seguimiento y formularios (modo `dev`)

Instale el seguimiento JavaScript de graph8 y genere formularios progresivos.

| Herramienta | Descripción |
|------|-------------|
| `g8_get_tracking_snippet` | Obtener el fragmento de seguimiento específico para cada framework (p.js). Compatible con: HTML, React, Next.js, Vue, WordPress, Webflow, Shopify |
| `g8_get_form_template` | Obtener la plantilla de formulario progresivo (embebido o emergente). Compatible con los mismos frameworks que el fragmento de seguimiento |

> **Caution:**
> El fragmento de seguimiento debe instalarse antes de que los formularios progresivos funcionen. Llame siempre a `g8_get_tracking_snippet` primero.

## Fragmento de seguimiento: lado del servidor vs. lado del cliente

El fragmento de seguimiento de graph8 (`p.js`) funciona de manera diferente según si su framework renderiza en el servidor o en el cliente. Comprender esto es fundamental para una instalación correcta.

### Renderizado en el servidor (SSR)

Frameworks: **Next.js**, **WordPress**, **Shopify**, **Webflow**, **HTML**

El fragmento se incluye en el diseño HTML renderizado en el servidor (por ejemplo, `app/layout.tsx`, `theme.liquid`, `functions.php`). Se carga en cada página desde el primer renderizado, sin demora de hidratación.

```javascript
// SSR — snippet is always available, call directly
g8.identify("user-123", { email: "user@example.com" });
g8.track("page_view", { page: "/pricing" });
```

### Renderizado en el cliente (CSR)

Frameworks: **React**, **Vue**

El fragmento se inyecta mediante `useEffect` (React) o `onMounted` (Vue) después de la hidratación. Es posible que el script no esté listo de inmediato; utilice encadenamiento opcional para llamar a los métodos de seguimiento de forma segura.

```javascript
// CSR — use optional chaining since g8 loads after hydration
window.g8?.identify("user-123", { email: "user@example.com" });
window.g8?.track("button_click", { button: "signup" });
```

### Opciones de privacidad

Añada estos atributos de datos a la etiqueta del script para controlar el comportamiento de privacidad:

| Atributo | Valores | Descripción |
|-----------|--------|-------------|
| `data-privacy-dont-send` | `"true"` | Desactiva las cookies y el envío de eventos |
| `data-privacy-user-ids` | `"true"` | Desactiva el almacenamiento de identificadores de usuario |
| `data-privacy-ip-policy` | `"keep"`, `"stripLastOctet"`, `"remove"` | Controla el manejo de la dirección IP |
| `data-init-only` | `"true"` | Inicializa el script sin enviar un evento de página |

### Verificación

Después de instalar el fragmento, verifique que funcione correctamente:

1. Abra la pestaña **DevTools -> Network** del navegador
2. Busque solicitudes a su host de seguimiento (`/p.js`)
3. En **Console**: `window.g8` debe estar definido
4. Llame a `g8.track('test_event')`: debería ver una solicitud de red

### Gestión de campañas (modo `gtm`)

Herramientas con alcance de organización para gestores de campañas, sin necesidad de contexto de repositorio.

| Herramienta | Descripción |
|------|-------------|
| `g8_list_campaigns` | Listar todas las campañas de la organización |
| `g8_get_campaign` | Obtener los detalles y el estado de una campaña |
| `g8_get_campaign_document` | Obtener un documento de campaña (correos electrónicos, páginas de destino) |
| `g8_create_campaign` | Crear una nueva campaña con audiencia, canales y contenido |
| `g8_update_campaign` | Actualizar la configuración de una campaña |
| `g8_launch_campaign` | Iniciar una campaña (o realizar una ejecución de prueba) |
| `g8_search_kb` | Buscar en la base de conocimiento |
| `g8_list_kb_documents` | Listar documentos de la base de conocimiento |

## Recursos

Los recursos MCP proporcionan contexto de solo lectura que los agentes pueden incluir en los prompts.

| URI del recurso | Descripción |
|-------------|-------------|
| `g8://repos` | Lista de repositorios conectados |
| `g8://repos/{repo_id}/scan` | Resultados del análisis de un repositorio |
| `g8://repos/{repo_id}/kb` | Documentos de la base de conocimiento para un repositorio |
| `g8://repos/{repo_id}/kb/{doc_id}` | Contenido de un documento de la base de conocimiento |
| `g8://repos/{repo_id}/campaigns` | Campañas de un repositorio |
| `g8://repos/{repo_id}/campaigns/{campaign_id}/brief` | Resumen de una campaña |
| `g8://contacts` | Resumen de una lista de contactos |
| `g8://companies` | Resumen de una lista de empresas |

## Plantillas de prompts

Prompts prediseñados para flujos de trabajo GTM comunes.

| Prompt | Argumentos | Descripción |
|--------|-----------|-------------|
| `gtm_setup` | `repo_url` | Flujo de trabajo de configuración completo: conectar, analizar, instalar, iniciar |
| `campaign_review` | `campaign_id` | Revisar y optimizar una campaña |
| `icp_refinement` | `feedback` | Refinar el perfil de cliente ideal a partir de los comentarios |

## Primeros pasos

Un flujo de trabajo típico de desarrollador con el servidor MCP:

1. **Configurar**: añada la configuración remota a su cliente de IA (sin instalación necesaria)
2. **Conectar**: pida a su agente que conecte su repositorio: *"Conecta mi repositorio github.com/org/app"*
3. **Analizar**: el agente analiza su base de código en busca de frameworks y puntos de integración
4. **Instalar fragmento**: *"Instala el fragmento de seguimiento de graph8 para Next.js"*
5. **Configurar seguimiento**: añada `g8.identify()` en el inicio de sesión y `g8.track()` en acciones clave
6. **Añadir formularios**: *"Genera un formulario progresivo embebido para React"*
7. **Iniciar campañas**: *"Crea una campaña dirigida a usuarios en período de prueba"*

## ¿Necesita ayuda?

- [Preguntas frecuentes sobre MCP](https://docs.graph8.com/developers/mcp-faq/) - errores comunes, autenticación, múltiples organizaciones, seguridad, límites de velocidad
- [Ejemplos de extremo a extremo](https://docs.graph8.com/developers/mcp-examples/) - seis flujos de trabajo completos que puede copiar
- [Documentación interactiva de Swagger](https://be.graph8.com/api/v1/docs) - la misma superficie, expuesta como REST
- [Precios](https://docs.graph8.com/developers/pricing/) - nivel gratuito y costos de créditos