Guía de configuración del MCP

Conecta Claude Desktop, Claude Code, ChatGPT o cualquier agente compatible con MCP a SociaHive: HTTP, stdio, OAuth y CLI en un solo lugar.

Conecta Claude Desktop, Claude Code, ChatGPT o cualquier agente compatible con MCP a tu instancia de SociaHive para gestionar flujos, publicaciones y estadísticas con lenguaje natural. Los contactos viven en el panel: el agente no los expone como herramientas a propósito.

Conecta tu cliente

Primero, obtén una clave de API en Configuración → Claves de API de tu panel de SociaHive. Las claves nuevas incluyen por defecto el scope agent:execute. Después elige tu cliente:

En Claude (app de escritorio o claude.ai): Configuración → Conectores → Agregar conector personalizado. Pega:

https://www.sociahive.com/api/mcp

Haz clic en Conectar e inicia sesión en SociaHive. No necesitas clave de API: el conector usa tu inicio de sesión de SociaHive. Marca “Acceso de solo lectura” en la pantalla de inicio de sesión si solo quieres que Claude consulte.

ChatGPT también se conecta con una URL y un inicio de sesión; consulta la pestaña de ChatGPT.

Sin configuración local, sin Node.js, sin pasos de compilación.

Herramientas disponibles

El catálogo completo de herramientas (parámetros, scopes de clave de API necesarios y cuáles requieren confirmación) está en la referencia de herramientas, generada directamente desde el registro de herramientas para que no se desfase.

Cada herramienta se ejecuta como el usuario autenticado, así que se aplican automáticamente los límites y la facturación de tu plan. Llama a list_capabilities desde cualquier cliente MCP para ver el conjunto exacto que tu clave puede invocar: se filtra según tus scopes y tu plan.

A grandes rasgos:

Área	Ejemplos
Sesión	`whoami`, `list_capabilities`
Flujos: lectura	`list_flows`, `get_flow`, `list_flows_with_stats`, `search_flows`
Flujos: escritura	`create_flow`, `generate_flow`, `add_node`, `add_edge`, `activate_flow`
Publicaciones: lectura	`list_scheduled_posts`, `get_scheduler_calendar`, `get_post_analytics`
Publicaciones: escritura	`create_scheduled_post`, `schedule_post`, `publish_post_now`
Cuentas y multimedia	`list_accounts`, `get_capabilities`, `search_published_media`
Estadísticas	`get_flow_stats`, `get_analytics_overview`, `get_content_insights`
Destructivas	`delete_flow`, `delete_scheduled_post`, `disconnect_account`

Dos comportamientos que conviene conocer antes de empezar:

Las mutaciones del grafo rechazan los flujos activos. add_node / update_node / add_edge devuelven un state_error con una sugerencia duplicate_then_edit: duplica el flujo como borrador, edítalo y vuelve a activarlo.
No existe un “crear y publicar” en un solo paso. Usa create_scheduled_post para crear el borrador y luego publish_post_now (que pide confirmación). Se eliminó el camino combinado porque se saltaba la confirmación que protege contra publicaciones en vivo accidentales. El contenido ya publicado en la plataforma nunca se toca: el agente no elimina nada de Instagram, Facebook, etc.

Ejemplos de prompts

Pruébalos en Claude Desktop, Claude Code o cualquier cliente MCP después de conectarte:

“Muéstrame mis flujos de automatización de Instagram”
“Crea un flujo que envíe un código de descuento por DM a los nuevos seguidores”
“¿Cómo estuvo mi interacción en Instagram la semana pasada?”
“Programa una publicación para mañana a las 9 a.m.: ‘Lanzamiento de nuevo producto’”
“Duplica mi flujo de bienvenida y cámbiale el nombre a ‘Bienvenida de fiestas’”
“Agrega una espera de 5 minutos entre el mensaje de bienvenida y el descuento en el flujo X”
“Muéstrame las estadísticas de mi flujo de captación de leads”

Scopes de la clave de API

Las claves de API tienen uno o más scopes. El endpoint MCP requiere agent:execute, que se incluye por defecto en cada clave nueva.

Las operaciones irreversibles (delete_*, disconnect_account, publish_post_now) pasan por un paso de confirmación, sea cual sea el scope. La primera llamada devuelve un token de confirmación de un solo uso (vigencia de 5 minutos); la segunda debe devolverlo. Consulta el Flujo de confirmación más abajo.

Flujo de confirmación

Las herramientas destructivas devuelven un sobre pending_confirmation en la primera llamada. Los clientes (Claude Desktop, Claude Code, la CLI sociahive) lo gestionan de forma transparente: el LLM te muestra las entidades afectadas y te pregunta antes de volver a llamar con el token de confirmación.

Para los clientes programáticos, el contrato es:

La primera llamada devuelve { __mcp_envelope: 'pending_confirmation', confirmToken, summary, affectedEntities } (vigencia de 5 min).
Segunda llamada: los mismos argumentos más __confirmToken: <token>. El servidor valida el token, comprueba que no se haya usado antes y ejecuta la herramienta.

Solución de problemas

“Authentication failed” / 401

Envía la clave como Authorization: Bearer sk_... o como X-API-Key: sk_.... Sirve cualquiera de los dos encabezados.
Verifica que la clave tenga el scope agent:execute (se concede automáticamente en el primer uso; confírmalo en la interfaz de claves de API).

“Connection refused” con stdio local

Ejecuta npm run dev para iniciar el servidor local de Next.js.
Define SOCIAHIVE_API_URL=http://localhost:3000 (NO /api/v1: ahora la CLI agrega /api/mcp por su cuenta).

Las herramientas no aparecen

Reinicia Claude Desktop después de agregar la configuración.
Revisa los registros de Claude Desktop: Help > Show Logs.

Límite de frecuencia

Límites por herramienta: lecturas 120/min, escrituras 30/min, costosas (p. ej. generate_flow) 5/min, tope diario de 1,000.
Tope de sesiones simultáneas: 200 en el transporte HTTP. Cierra las sesiones inactivas o espera 5 min a que venza su TTL.

Tiempo de espera agotado en generate_flow

La herramienta devuelve de inmediato un borrador y la URL del editor. La generación con IA se transmite cuando abres el flujo en el panel. El costo se mide allí, no en esta llamada.

publish_post_now devuelve pending_confirmation

Es lo esperado: las operaciones destructivas requieren una segunda llamada con el __confirmToken. En la CLI, pasa --yes. Los clientes compatibles con MCP lo gestionan de forma nativa.

add_node / update_node / add_edge se rechazan con state_error

El flujo de destino está published. Duplícalo como borrador (duplicate_flow), edita la copia y vuelve a activarla.