# Preguntas frecuentes sobre MCP

> Respuestas a preguntas comunes sobre el servidor MCP de graph8 - nivel gratuito, modos, errores, seguridad y múltiples organizaciones

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

Preguntas frecuentes sobre la conexión de agentes de IA e IDEs a graph8 mediante el Model Context Protocol. Si su pregunta no aparece aquí, consulte la [descripción general del servidor MCP](https://docs.graph8.com/developers/mcp/) o reporte un error en el repositorio de GitHub de la integración correspondiente.

> **Tip:**
> Pruebe el nivel para desarrolladores de forma gratuita: 1,000 créditos, sin necesidad de tarjeta. [Comenzar](https://auth.graph8.com/en/signup).

## Planes y créditos

### ¿Existe un nivel gratuito para MCP?

Sí. El nivel Developer PAYG incluye 1,000 créditos gratuitos al registrarse y no requiere tarjeta. Las llamadas a herramientas MCP se descuentan de ese saldo igual que las llamadas por SDK o REST. Las herramientas de navegación como `g8_find_contacts` son gratuitas para previsualizar; los créditos solo se descuentan al guardar, enriquecer o enviar. Consulte [Precios](https://docs.graph8.com/developers/pricing/) para más detalles.

### ¿Cuál es el precio por llamada a herramienta?

Cada crédito cuesta $0.05 en PAYG. La mayoría de las herramientas de lectura son gratuitas. Las herramientas que consumen créditos están señaladas en la [Referencia de herramientas MCP](https://docs.graph8.com/developers/mcp-tools/): busque la columna "credits". El enriquecimiento, los borradores de respuesta con IA y las sincronizaciones de audiencias son las principales funcionalidades de pago.

### ¿Cómo monitoreo el consumo de créditos desde MCP?

Abra **Perfil -> Desarrollador** en la aplicación de graph8. El panel de Uso muestra los créditos consumidos en las últimas 24 horas, 7 días y el mes de facturación, desglosados por origen (MCP, SDK, REST, UI). Cada llamada a herramienta aparece con una marca de tiempo y el costo en créditos.

## Autenticación

### ¿Dónde obtengo una clave de API personal frente a una clave de API de organización?

- **Clave de API personal**: **Perfil -> Desarrollador**. Con alcance limitado a su usuario dentro de la organización activa. Úsela para configuraciones MCP stdio locales en su propia máquina.
- **Clave de API de organización**: **Configuración -> API**. Solo para administradores. Con alcance a toda la organización para automatización compartida, cuentas de servicio o integraciones en producción.

La mayoría de los usuarios necesitan la clave personal. Consulte [Autenticación](https://docs.graph8.com/developers/authentication/).

### ¿Cuál es la diferencia entre OAuth remoto y stdio local?

| | OAuth remoto | stdio local |
|---|---|---|
| Dónde se ejecuta el servidor | Nube de graph8 | Su máquina |
| Cómo funciona la autenticación | OAuth en el navegador, una sola vez | Variable de entorno `G8_API_KEY` |
| Instalación requerida | No | `uvx g8-mcp-server` |
| Ideal para | Claude.ai, Claude Desktop, VS Code, agentes alojados | Cursor, Windsurf, desarrollo local, CI |
| Herramientas cargadas | Todas las herramientas (filtrado por modo próximamente) | Filtrable mediante `G8_MCP_MODE` |

OAuth remoto es la recomendación predeterminada. Consulte la [matriz de configuración de MCP](https://docs.graph8.com/developers/mcp/) para saber qué clientes admiten cada transporte.

### ¿Dónde se almacena en realidad mi clave de API?

Para stdio local, la clave se encuentra en:

- El bloque `env` de la configuración de su cliente MCP (`~/.cursor/mcp.json`, `~/.claude/mcp.json`, etc.), o
- `~/.g8/credentials.json` si ejecutó `g8 login --api-key`.

En OAuth remoto no existe clave de API. graph8 emite un token de sesión opaco vinculado a su identidad de PropelAuth. El token lo gestiona su cliente MCP (Claude.ai, Claude Desktop, etc.) y se rota automáticamente.

### ¿Cómo revoco una sesión o clave?

- **Sesiones OAuth**: **Perfil -> Conexiones** en la aplicación de graph8. Haga clic en revocar junto al nombre del cliente.
- **Claves de API personales**: **Perfil -> Desarrollador**. Elimine la clave.
- **Claves de API de organización**: **Configuración -> API**. Solo para administradores.

La revocación es inmediata. El cliente recibirá un error 401 en la siguiente llamada a herramienta.

## Modos

### ¿Cuándo uso el modo `dev`, `gtm` o `all`?

| Modo | Audiencia | Herramientas | Configurado en |
|---|---|---|---|
| `dev` | Desarrolladores que usan Cursor, Windsurf, Claude Code | 17: escaneo de repositorio, instalación de seguimiento, formularios, KB | solo stdio |
| `gtm` | Gestores de campañas en Claude Desktop | 23: campañas, secuencias, bandeja de entrada, sincronizaciones de audiencias | solo stdio |
| `all` | Alternativa predeterminada | 35: todo | solo stdio |

El modo se configura mediante `G8_MCP_MODE` en stdio. OAuth remoto carga actualmente todas las herramientas. El filtrado de modo por URL para conexiones remotas está en el roadmap (consulte la [descripción general del servidor MCP](https://docs.graph8.com/developers/mcp/)).

### ¿Por qué faltan algunas herramientas en mi cliente?

Tres causas probables:

1. Está usando stdio con `G8_MCP_MODE=dev` o `gtm` y la herramienta pertenece al otro modo. Configure `G8_MCP_MODE=all` o cambie de modo.
2. Su rol no otorga acceso. Verifíquelo con un administrador en **Configuración -> Miembros**.
3. Su versión de `g8-mcp-server` está desactualizada. Ejecute `uvx g8-mcp-server@latest` o `pip install -U g8-mcp-server`.

## Errores comunes

### `spawn uvx ENOENT`

El binario `uvx` no está en su `PATH`. Instale [uv](https://docs.astral.sh/uv/) (recomendado) o reemplace `uvx` con la ruta absoluta en su configuración:

```json
{
  "command": "/Users/you/.local/bin/uvx",
  "args": ["g8-mcp-server"]
}
```

### `Authentication failed` o 401

La clave de API de su configuración está vencida, revocada o tiene alcance en una organización distinta. Regenere la clave desde **Perfil -> Desarrollador** y actualice el bloque `env` en su configuración MCP. Reinicie el cliente MCP después de cambiar la configuración.

Para OAuth: revoque la sesión en **Perfil -> Conexiones** y vuelva a conectarse desde su cliente.

### `Permission denied`

El MCP solo puede hacer lo que su rol en graph8 permite. Si una herramienta devuelve "permission denied", tampoco tiene esa funcionalidad disponible en la aplicación. Solicite a un administrador que actualice su rol en **Configuración -> Miembros**.

### `Tool not found`

Tres causas probables:

1. Error tipográfico en el nombre de la herramienta. Los nombres distinguen entre mayúsculas y minúsculas y llevan el prefijo `g8_`.
2. La herramienta pertenece a un modo no cargado (consulte "¿Por qué faltan algunas herramientas?").
3. Su versión de `g8-mcp-server` es anterior a la herramienta. Actualice con `uvx g8-mcp-server@latest`.

### Bucle de redireccionamiento OAuth

Causado por cookies del navegador desactualizadas o un inicio de sesión incompleto. Borre las cookies de `be.graph8.com` y `app.graph8.com`, y vuelva a conectarse.

Si utiliza un dominio personalizado o una instancia autoalojada, asegúrese de que la `redirect_uri` registrada en su cliente coincida con la URL canónica de graph8.

### `JSON parse error` al iniciar Claude Desktop

El archivo `claude_desktop_config.json` tiene sintaxis inválida. Causas frecuentes: una coma al final, una comilla faltante o comillas tipográficas provenientes de un procesador de texto. Péguelo en un validador de JSON como [jsonlint.com](https://jsonlint.com) y corríjalo.

## Múltiples organizaciones e instancias

### ¿Cómo cambio de organización en graph8 dentro de mi cliente MCP?

Cada sesión MCP está vinculada a una organización. Para cambiar:

1. Revoque la sesión actual en **Perfil -> Conexiones** (OAuth) o reemplace su clave de API (stdio).
2. Cambie de organización en la interfaz web de la aplicación de graph8.
3. Vuelva a conectarse desde su cliente MCP o genere una nueva clave personal en la nueva organización.

Puede mantener una configuración por organización agregando varios servidores a `mcpServers`, por ejemplo `graph8-acme` y `graph8-staging`.

### ¿Puedo ejecutar varias instancias de MCP en paralelo?

Sí. Cada proceso de cliente MCP es independiente. Puede tener Cursor, Claude Desktop y una sesión CLI apuntando a graph8 al mismo tiempo. La facturación de créditos es por llamada, no por sesión.

Para frameworks de agentes (LangChain, CrewAI, etc.) que generan llamadas a herramientas en paralelo, el servidor gestiona solicitudes concurrentes por sesión. Los límites de velocidad se aplican por organización, no por sesión. Consulte [Límites de velocidad](https://docs.graph8.com/developers/rate-limits/).

## Seguridad

### ¿Qué datos ve la sesión OAuth?

La sesión ve exactamente lo que ve su cuenta de usuario en la aplicación web de graph8. Los mismos permisos de rol y los mismos límites de organización. La sesión no tiene acceso a otras organizaciones de las que no es miembro.

### ¿Se envían mis datos a Anthropic, OpenAI, etc.?

graph8 devuelve los resultados de las herramientas a su cliente MCP. Su cliente (Claude, GPT, Cursor) incluye esos resultados en el prompt del LLM. graph8 no envía datos directamente a los proveedores de modelos. Si tiene un requisito de residencia de datos, configure un MCP autoalojado mediante stdio para que la conexión permanezca dentro de su máquina.

### ¿Puedo limitar una clave de API a herramientas específicas?

No por ahora. Las claves de API llevan el conjunto completo de permisos del usuario u organización al que pertenecen. El alcance por herramienta está en el roadmap.

## Tiempos de espera y límites de velocidad

### ¿Cuál es el límite de velocidad?

5 solicitudes por segundo por organización para todas las superficies (REST, SDK, MCP). Las ráfagas por encima de ese límite devuelven HTTP 429. Consulte [Límites de velocidad](https://docs.graph8.com/developers/rate-limits/).

### ¿Por qué se agota el tiempo de espera en mi llamada a herramienta?

Las herramientas de larga duración (`g8_build_contact_list`, `g8_enrich_contacts`) pueden tardar entre 30 y 90 segundos. La mayoría de los clientes MCP aplican por defecto un tiempo de espera de 60 segundos en las respuestas de herramientas. Alternativas:

- Use la variante de lote más pequeño (por ejemplo, `g8_find_contacts` primero para previsualizar y luego `g8_build_contact_list` con un `limit` menor).
- En Claude Desktop, aumente el tiempo de espera en la configuración de la aplicación.
- Para agentes programáticos, incremente el tiempo de espera por herramienta en la configuración de su framework.

## Herramientas de previsualización

### ¿Existen herramientas de previsualización o ejecución en seco?

Sí. Úselas antes de herramientas que consuman créditos o envíen mensajes reales:

- `g8_find_contacts` previsualiza los resultados de búsqueda antes de que `g8_build_contact_list` los guarde.
- `g8_get_sequence_preview` previsualiza los pasos y canales de la secuencia antes del lanzamiento.
- `g8_lookup_person` y `g8_lookup_company` cuestan 2 créditos por búsqueda, que solo se cobran cuando se encuentra una coincidencia, pero no guardan datos. Ejecútelos primero si desea verificar la calidad de los datos antes de un enriquecimiento masivo.

El servidor MCP de graph8 aplica una regla de "confirmar antes de ejecutar" en cualquier herramienta que consuma créditos o envíe mensajes outbound. Su cliente debe solicitarle confirmación cada vez.

## Reporte de errores y solicitud de funcionalidades

- **Errores**: abra un issue en el repositorio correspondiente. Para errores del servidor use el repositorio del servidor MCP de graph8. Para errores del cliente use el repositorio del cliente.
- **Nuevas herramientas**: abra una discusión o contacte a su gestor de cuenta. Priorizamos las herramientas según el uso agregado.
- **Documentación**: este sitio acepta PRs. Edite cualquier archivo `.mdx` en `frontend/docs/src/content/docs/developers/`.

## Relacionados

- [Descripción general del servidor MCP](https://docs.graph8.com/developers/mcp/)
- [Referencia de herramientas MCP](https://docs.graph8.com/developers/mcp-tools/)
- [Precios](https://docs.graph8.com/developers/pricing/)
- [Límites de velocidad](https://docs.graph8.com/developers/rate-limits/)
- [Autenticación](https://docs.graph8.com/developers/authentication/)