WorkForceAI MCP Server

Esta es la "caja de herramientas interna del bot": un pequeño servidor independiente que permite a un bot de chat/voz consultar y actualizar elementos en la plataforma WorkForceAI (agentes, campañas, números de teléfono, registros de llamadas, estadísticas) llamando al mismo backend que usa la aplicación principal.

Es completamente independiente del repositorio healthai-frontend — nada de esto se envía allí. Habla un protocolo estándar llamado MCP (Model Context Protocol), que es lo que permite a una IA (Claude, el agente de ElevenLabs, etc.) descubrir "estas son las cosas que puedo hacer" y llamarlas durante una conversación.

No necesitas comprender el funcionamiento interno de MCP para ejecutar esto: solo sigue los pasos siguientes.

Lo que puede hacer ahora mismo

Solo lectura (herramientas seguras de consulta):

• list_voice_agents — lista tus agentes de voz de CallFlow

• list_campaigns — lista campañas, u obtén los detalles completos de una campaña

• list_phone_numbers — lista los números de Twilio aprovisionados

• get_call_logs — registros/transcripciones de llamadas recientes

• get_dashboard_stats — estadísticas de volumen/uso de llamadas

• get_current_account — la cuenta con la que el bot ha iniciado sesión

Una herramienta de acción (modifica datos reales):

• update_campaign — actualiza el prompt del sistema, saludo, nombre, objetivo, etc. de una campaña. Requiere un campaignId; solo se modifican los campos que pases.

Todo esto está limitado a la cuenta cuyo inicio de sesión pongas en .env — el bot ve exactamente lo que esa cuenta puede ver en la plataforma, y nada más.

Related MCP server: dSIPRouter MCP Server

Configuración inicial

1. Instalar dependencias

Abre una terminal en esta carpeta (E:\aiconnecthub\workforceai-mcp) y ejecuta:

npm install

(Node.js ya está instalado en esta máquina; no hay nada más que instalar.)

2. Configura tu archivo .env

Aquí ya existe un archivo .env con tu inicio de sesión completado, que apunta al backend real de WorkForceAI (https://workforceai.zapto.org). Si alguna vez necesitas cambiar la cuenta con la que el bot inicia sesión, edita .env directamente:

BACKEND_BASE_URL=https://workforceai.zapto.org
BOT_ACCOUNT_EMAIL=your-login-email
BOT_ACCOUNT_PASSWORD=your-login-password
MCP_PORT=8787

Nunca compartas este archivo ni lo confirmes en ningún repositorio — contiene una contraseña real. .gitignore ya lo excluye, así que incluso si conviertes esta carpeta en un repositorio git más adelante, .env no se confirmará por accidente.

3. Iniciar el servidor

npm start

Deberías ver:

workforceai-mcp listening on http://localhost:8787
  MCP endpoint: http://localhost:8787/mcp
  Health check: http://localhost:8787/health

Déjalo ejecutándose en su propia ventana de terminal mientras pruebas o usas el bot. Pulsa Ctrl+C para detenerlo.

4. Verificar que funciona

Comprobación rápida (sin herramientas adicionales): abre http://localhost:8787/health en un navegador; debería mostrar {"ok":true}.

Comprobación completa (ver las herramientas reales y probar una): usa el MCP Inspector oficial, una herramienta basada en navegador para interactuar manualmente con un servidor MCP. En una segunda terminal (deja el servidor ejecutándose en la primera):

npx @modelcontextprotocol/inspector

Esto abre una pestaña del navegador. En ella:

1. Establece Tipo de transporte en Streamable HTTP

2. Establece URL en http://localhost:8787/mcp

3. Haz clic en Conectar

4. Ve a la pestaña Herramientas, haz clic en una herramienta como list_voice_agents, haz clic en Ejecutar — deberías ver tus agentes reales devueltos como JSON.

Si eso funciona, el servidor está completamente verificado y listo para conectarse a un bot.

Cómo funciona la autenticación (para que no te lleves sorpresas)

Hoy no existe un sistema separado de "clave de API para bots" en el backend: el bot inicia sesión con un correo electrónico/contraseña normales, exactamente igual que el formulario de inicio de sesión del sitio web, y recibe un token JWT que adjunta a cada solicitud. Mantiene ese token en memoria (no en disco) y vuelve a iniciar sesión automáticamente si el token expira o si una solicitud devuelve no autorizada. Esto refleja lo que hace utils/apiClient.js en la aplicación frontend, pero sin navegador.

Debido a esto, el bot solo ve/cambia lo que ese inicio de sesión puede ver — sus propios agentes, campañas, números y registros de llamadas. No puede ver ni tocar las cuentas de otros usuarios.

Estructura del proyecto

workforceai-mcp/
├── .env              ← your real credentials (gitignored, never share)
├── .env.example       ← template, safe to share
├── src/
│   ├── config.js      ← reads .env
│   ├── backendClient.js ← logs in, attaches auth token, retries on expiry
│   ├── tools.js        ← the actual tool definitions (add new ones here)
│   └── server.js       ← the MCP server itself (Express + Streamable HTTP)
└── README.md          ← this file

Para añadir una nueva herramienta más adelante: añade una entrada al array tools en src/tools.js siguiendo el patrón existente (nombre, descripción, campos de entrada, manejador que llama a http.get/post/put contra el backend), reinicia el servidor y listo.

Lo que aún NO está hecho (siguiente fase)

Este servidor actualmente solo se ejecuta en tu propia máquina (localhost) — no es accesible desde internet. Para conectarlo a un agente de voz de ElevenLabs, los servidores de ElevenLabs necesitan poder alcanzar este endpoint MCP a través de internet, lo que implica:

• exponerlo temporalmente mediante un túnel (p. ej. ngrok), o

• desplegarlo en algún lugar donde permanezca en ejecución (un servidor/VPS/servicio de hosting pequeño y siempre activo)

Eso, junto con la configuración real del agente de ElevenLabs, es intencionadamente un paso siguiente separado — no forma parte de esta versión.