Servidor MCP de Zentix

1 Qué es el servidor MCPWhat the MCP server is

MCP (Model Context Protocol) es el estándar abierto con el que Claude, ChatGPT, Cursor y otros asistentes conectan herramientas externas. El servidor MCP de Zentix expone tu cuenta como herramientas seguras: tu asistente puede consultar contactos, conversaciones y tratos del CRM, revisar escalaciones y seguimientos, leer la agenda y tus agentes IA, consultar métricas, crear enlaces de pago y agendar reuniones — siempre con tu permiso y con recibo verificable. MCP (Model Context Protocol) is the open standard Claude, ChatGPT, Cursor and other assistants use to connect external tools. The Zentix MCP server exposes your account as safe tools: your assistant can query CRM contacts, conversations and deals, review escalations and follow-ups, read your agenda and AI agents, pull metrics, create payment links and book meetings — always with your permission and a verifiable receipt.

• Multi-cliente: funciona con cualquier cliente MCP (Claude Desktop, ChatGPT connectors, Cursor, Hermes, agentes propios).Multi-client: works with any MCP client (Claude Desktop, ChatGPT connectors, Cursor, Hermes, custom agents).
• Dos modos: conexión remota (URL + credencial, cero instalación) o local (stdio, el paquete @zentix/mcp-server).Two modes: remote connection (URL + credential, zero install) or local (stdio, the @zentix/mcp-server package).
• Multi-tenant: cada usuario conecta su propia cuenta; el aislamiento por tenant es idéntico al del dashboard.Multi-tenant: each user connects their own account; tenant isolation is identical to the dashboard.
• Más que tools: expone prompts (playbooks de ventas y métricas) y recursos (documentación) además de las herramientas.More than tools: also exposes prompts (sales and metrics playbooks) and resources (documentation) beyond the tools.

2 Tools disponiblesAvailable tools

3 Credenciales: token o API keyCredentials: token or API key

El endpoint acepta dos tipos de credencial en Authorization: Bearer <credencial>: The endpoint accepts two credential types in Authorization: Bearer <credential>:

• Firebase ID token — el token de tu sesión (currentUser.getIdToken()). Vale ~1 hora; renuévalo con getIdToken(true). Ideal para uso interactivo.Firebase ID token — your session token (currentUser.getIdToken()). Valid ~1 hour; renew with getIdToken(true). Best for interactive use.
• API key de MCP (zmx_…) — clave de larga vida para agentes desatendidos (Hermes, automatizaciones). El servidor la resuelve a tu tenant y mintea el token por ti. Recomendada.MCP API key (zmx_…) — a long-lived key for unattended agents (Hermes, automations). The server resolves it to your tenant and mints the token for you. Recommended.

Crear una API keyCreating an API key

Autenticado con tu token de sesión (por ejemplo desde la consola del navegador en app.zentixchatbot.cloud): Authenticated with your session token (for example from the browser console on app.zentixchatbot.cloud):

Copiarconst token = await firebase.auth().currentUser.getIdToken();

// Crear la key (el valor completo se muestra UNA sola vez)
const res = await fetch('/api/mcp-keys', {
  method: 'POST',
  headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Mi agente' })
});
const { key } = await res.json();   // zmx_... → guárdala en tu gestor de secretos

// Listar y revocar
GET    /api/mcp-keys
DELETE /api/mcp-keys?keyId=<id>

4 Conexión remota (recomendada)Remote connection (recommended)

La conexión remota no requiere instalar nada: el cliente MCP llama a https://app.zentixchatbot.cloud/api/mcp y se autentica con tu credencial. The remote connection requires no install: the MCP client calls https://app.zentixchatbot.cloud/api/mcp and authenticates with your credential.

Claude Desktop / Claude Code

Copiar{
  "mcpServers": {
    "zentix": {
      "type": "http",
      "url": "https://app.zentixchatbot.cloud/api/mcp",
      "headers": { "Authorization": "Bearer <TU_CREDENCIAL>" }
    }
  }
}

Claude Code (CLI)

Copiarclaude mcp add --transport http zentix https://app.zentixchatbot.cloud/api/mcp \
  --header "Authorization: Bearer <TU_CREDENCIAL>"

Cursor (.cursor/mcp.json)

Copiar{
  "mcpServers": {
    "zentix": {
      "url": "https://app.zentixchatbot.cloud/api/mcp",
      "headers": { "Authorization": "Bearer <TU_CREDENCIAL>" }
    }
  }
}

Prueba rápida con curlQuick test with curl

Copiarcurl -s https://app.zentixchatbot.cloud/api/mcp \
  -H "Authorization: Bearer $ZENTIX_CREDENTIAL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

5 Conexión local (stdio)Local connection (stdio)

Para uso interno o instalación offline, el paquete @zentix/mcp-server corre en tu máquina sobre stdio. Empaqueta el tarball desde el repositorio (la publicación en npm es un paso aparte), instálalo global y registra el comando zentix-mcp. For internal or offline use, the @zentix/mcp-server package runs on your machine over stdio. Pack the tarball from the repository (npm publishing is a separate step), install it globally and register the zentix-mcp command.

Copiargit clone https://github.com/jgazcagtz/zentix_1.0 && cd zentix_1.0
npm pack ./mcp                        # → zentix-mcp-server-0.4.0.tgz
npm install -g ./zentix-mcp-server-0.4.0.tgz

Copiar{
  "mcpServers": {
    "zentix": {
      "command": "zentix-mcp",
      "env": {
        "ZENTIX_ID_TOKEN": "<TU_FIREBASE_ID_TOKEN>",
        "ZENTIX_MCP_ALLOW_WRITES": "0"
      }
    }
  }
}

6 Escrituras y reciboWrites and receipts

Las únicas herramientas de escritura son zentix_agenda_meeting_create y zentix_payment_link_create, deliberadamente acotadas: su action está fijado en código (el modelo nunca puede llegar a actualizar, cancelar o eliminar), exigen un requestId — tu clave de idempotencia — y devuelven el recibo de la API. Reintentar con la misma clave devuelve el mismo resultado, sin duplicados. The only write tools are zentix_agenda_meeting_create and zentix_payment_link_create, deliberately narrow: their action is hardcoded (the model can never reach update, cancel or delete), they require a requestId — your idempotency key — and they return the API receipt. Retrying with the same key returns the same result, no duplicates.

• Interruptor: las tools de escritura solo responden si el servidor corre con ZENTIX_MCP_ALLOW_WRITES=1; si no, fallan con writes_disabled antes de cualquier llamada de red.Switch: write tools only respond when the server runs with ZENTIX_MCP_ALLOW_WRITES=1; otherwise they fail with writes_disabled before any network call.
• Recibo: la respuesta incluye el objeto creado tal cual la devolvió la API — revísalo antes de considerar la acción hecha.Receipt: the response includes the created object exactly as the API returned it — review it before treating the action as done.
• Enlaces de pago: lee primero zentix_payment_links_read para obtener expectedConfigVersion; el importe va en amountCents (150000 = 1500.00).Payment links: read zentix_payment_links_read first to get expectedConfigVersion; amounts go in amountCents (150000 = 1500.00).

7 Prompts y recursosPrompts and resources

Además de tools, el servidor expone prompts (playbooks listos para usar en tu asistente) y recursos (documentación legible por el modelo): Beyond tools, the server exposes prompts (ready-made playbooks for your assistant) and resources (model-readable documentation):

• zentix_pipeline_review — revisa el pipeline por etapas y propone acciones.reviews the pipeline stage by stage and proposes actions.
• zentix_prepare_sales_call — briefing pre-llamada de un contacto (historial, seguimientos, puntos de conversación).pre-call briefing for a contact (history, follow-ups, talking points).
• zentix_metrics_brief — briefing de métricas para un rango de fechas.metrics briefing for a date range.
• zentix://docs/tools y zentix://docs/security — referencia de tools y modelo de seguridad como recursos MCP.tool reference and security model as MCP resources.

8 Modelo de seguridadSecurity model

9 Solución de problemasTroubleshooting

Documentación relacionadaRelated documentation

• Documentación de APIAPI documentation — los endpoints detrás de cada toolthe endpoints behind each tool
• Base de conocimientoKnowledge base — guías de productoproduct guides
• ContactoContact — soporte de integraciónintegration support