Preguntas frecuentes sobre MCP

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 o reporte un error en el repositorio de GitHub de la integración correspondiente.

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 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: 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.

¿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 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).

¿Por qué faltan algunas herramientas en mi cliente?

Tres causas probables:

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.
Su rol no otorga acceso. Verifíquelo con un administrador en Configuración -> Miembros.
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 (recomendado) o reemplace uvx con la ruta absoluta en su configuración:

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

Error tipográfico en el nombre de la herramienta. Los nombres distinguen entre mayúsculas y minúsculas y llevan el prefijo g8_.
La herramienta pertenece a un modo no cargado (consulte “¿Por qué faltan algunas herramientas?”).
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 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:

Revoque la sesión actual en Perfil -> Conexiones (OAuth) o reemplace su clave de API (stdio).
Cambie de organización en la interfaz web de la aplicación de graph8.
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.

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.

¿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, g8_scan_repo) 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 1 crédito 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/.