☎️ five9-mcp

Tu centro de contacto Five9, en manos de tu IA.

Un servidor MCP de código abierto que conecta Claude, ChatGPT o cualquier cliente MCP con el centro de contacto en la nube Five9 — ejecutándose en Cloudflare Workers con cero dependencias.

Inicio rápido · Conectar Claude · Conectar ChatGPT · Herramientas · Arquitectura

Pregúntale a tu IA cosas como:

"¿Quién está en una llamada ahora mismo, y qué tan profunda es la cola de ventas?" 📊 "Crea una campaña de vista previa para la lista de recuperación, adjunta la habilidad de ventas e iníciala." 🛠️ "Detén la campaña OUTBOUND_AGED y añade estos 3 clientes potenciales a la lista de devolución de llamadas." 📞 "Integra al nuevo agente: crea el usuario, asigna la habilidad de facturación en nivel 2." 🧑💼 "¿Está el 555-867-5309 en nuestra lista DNC? Compruébalo antes de que alguien lo marque." 🚫 "Extrae el informe de registro de llamadas de ayer y resume las tasas de abandono." 📈 "Créame un IVR completo: opción 1 programación, opción 2 facturación, fuera de horario va al buzón de voz." 🧩

Bajo el capó, este servidor habla con los Servicios Web SOAP de Configuración (administración) y Estadísticas (supervisor) de Five9 — las API que aún gestionan la superficie administrativa de Five9 — y los expone como herramientas JSON limpias a través de MCP streamable HTTP. Envelopes hechos a mano, un analizador XML de ~60 líneas, sin paquetes npm. Cada herramienta ha sido probada contra un dominio Five9 real.

✨ Interfaz web integrada

Despliégalo y tu Worker sirve más que una API:

La consola es la forma más rápida de verificar credenciales, explorar lo que devuelve cada herramienta o depurar una campaña — sin necesidad de IA.

Related MCP server: five9-mcp

🚀 Inicio rápido — sin necesidad de terminal

Necesitas una cuenta gratuita de Cloudflare y un usuario de Five9 con acceso a la API — crea un usuario de API de Five9 dedicado con permisos limitados a lo que quieras que haga la IA, no reutilices un inicio de sesión de administrador personal.

1 — Despliega en Cloudflare (un clic, en tu navegador)

Inicia sesión en Cloudflare y haz clic — crea tu propia copia de este Worker (además del espacio de nombres KV que necesita) y te da una URL como https://five9-mcp.you.workers.dev.

2 — Ejecuta el asistente de configuración (en tu navegador)

Abre /setup en tu nuevo servidor. Introduce tu nombre de usuario, contraseña y región de Five9 — el asistente los verifica en vivo contra Five9 antes de guardarlos, y luego te entrega tu clave de acceso (se muestra una sola vez — guárdala en un gestor de contraseñas).

3 — Conecta tu IA (tutoriales abajo), y luego pídele que "compruebe la conexión y liste mis campañas." 🎉

git clone https://github.com/ryanshatz/five9-mcp
cd five9-mcp
npx wrangler deploy   # provisions the CONFIG KV namespace on first deploy

Luego usa el asistente /setup, o sáltatelo y gestiona las credenciales como secretos de Wrangler (los secretos anulan al asistente):

npx wrangler secret put FIVE9_USERNAME   # e.g. apiuser@yourdomain
npx wrangler secret put FIVE9_PASSWORD
npx wrangler secret put MCP_AUTH_TOKEN   # a long random string — this is the key to your server

Los valores predeterminados están en wrangler.toml y funcionan para dominios de EE. UU.:

🔌 Conecta tu IA

Conectar Claude (web y escritorio)

Los conectores personalizados están disponibles en los planes Free (un conector), Pro, Max, Team y Enterprise.

1. En claude.ai o en la aplicación de escritorio de Claude, abre Configuración → Conectores.

2. Haz clic en Añadir conector personalizado.

3. Nómbralo Five9 y pega la URL de tu servidor incluyendo la ruta /mcp: https://<tu-worker>.workers.dev/mcp

4. Haz clic en Añadir y luego en Conectar. Claude descubre automáticamente el OAuth integrado de este servidor y abre su página de autorización.

5. En la pantalla 🔐 five9-mcp, pega tu MCP_AUTH_TOKEN como clave de acceso y haz clic en Autorizar.

6. En cualquier chat, abre el menú de búsqueda y herramientas (＋) y asegúrate de que el conector de Five9 esté activado.

Team/Enterprise: un propietario primero añade el conector en Configuración de la organización → Conectores; luego los miembros hacen clic en Conectar en su propia configuración para autorizarlo.

Conectar ChatGPT

Los conectores MCP personalizados requieren el modo Desarrollador (Plus/Pro; en Business/Enterprise un administrador debe permitir conectores personalizados).

1. En ChatGPT en la web, abre Configuración → Apps y conectores (a veces etiquetado solo como Conectores).

2. En Configuración avanzada, activa el modo Desarrollador.

3. Vuelve a la página de Conectores y haz clic en Crear.

4. Nómbralo Five9, establece la URL del servidor MCP como https://<tu-worker>.workers.dev/mcp y elige autenticación OAuth.

5. Acepta el aviso de confianza y guarda. ChatGPT abre la página de autorización de este servidor — pega tu MCP_AUTH_TOKEN y haz clic en Autorizar.

6. En un chat nuevo, abre el menú de herramientas ＋ / y activa el conector Five9 (los conectores del modo Desarrollador se activan por conversación). ChatGPT te pide que confirmes cada llamada de herramienta — algo sensato para cualquier cosa que pueda iniciar un marcador. 😄

Conectar Claude Code

claude mcp add --transport http five9 https://<your-worker>.workers.dev/mcp \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>"

La clave de acceso sin procesar funciona directamente como token de portador — sin el baile de OAuth. Ejecuta /mcp dentro de Claude Code para verificar.

Cualquier otro cliente MCP

Cualquier cosa que hable HTTP streamable de MCP funciona — completa el flujo OAuth o envía la clave de acceso como token de portador:

curl -X POST https://<your-worker>.workers.dev/mcp \
  -H "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"check_connection","arguments":{}}}'

src/oauth.js implementa un servidor de autorización OAuth 2.1 mínimo (descubrimiento de metadatos, registro dinámico de clientes, PKCE S256, tokens de actualización) diseñado para un despliegue de operador único:

• El "inicio de sesión" en la pantalla de consentimiento es la clave de acceso del servidor (MCP_AUTH_TOKEN).

• Todo es sin estado — los ID de cliente, códigos de autorización y tokens son blobs firmados con HMAC-SHA256 y cifrados con MCP_AUTH_TOKEN. Sin KV, sin Durable Objects.

• Ambas rutas de autenticación funcionan simultáneamente: tokens emitidos por OAuth y la clave sin procesar como credencial de portador.

• Revoca todo de una vez rotando el secreto: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 La caja de herramientas

77 herramientas. 🟢 = lectura (siempre segura) · ✏️ = escritura (cambia tu dominio — el servidor indica a las IA que confirmen contigo primero)

69 herramientas SOAP (usuario/contraseña) + 8 herramientas REST de OAuth New Platform (Consumer Key/Secret — consulta API de OAuth New Platform).

El truco estrella: describe un flujo de llamada en un párrafo y la IA lo diseña, te muestra un diagrama Mermaid en el chat y despliega un script IVR funcional. El modelo nunca improvisa el XML de IVR de Five9: rellena una especificación de flujo JSON restringida (reproducción / menú / horario comercial / transferencia por habilidad / buzón de voz / colgar), un validador de grafos comprueba cada rama y referencia, y un código determinista genera XML con forma de diseñador (cableado de módulos, codificación de mensajes y orden de campos, todo derivado de scripts exportados reales).

Flujo recomendado: validar → renderizar (¡muestra al humano!) → generar mensajes → construir → adjuntar a una campaña entrante. generate_prompt_audio se ejecuta en Cloudflare Workers AI de serie: sin cuenta TTS externa, sin clave de API, fracciones de céntimo por mensaje facturadas a la cuenta de Cloudflare en la que ya desplegaste. ElevenLabs/OpenAI también funcionan si configuras sus claves secretas, y los mensajes {tts} (la voz robótica integrada de Five9) no necesitan nada en absoluto.

Estas herramientas usan las APIs REST OAuth 2.0 de la "Nueva Plataforma" modernas de Five9, no las APIs SOAP que usan las herramientas anteriores. Requieren una credencial de Control de Acceso a la API (Consumer Key/Secret), no el nombre de usuario/contraseña SOAP — ver APIs OAuth de la Nueva Plataforma.

🔐 APIs OAuth de la Nueva Plataforma

Junto a las herramientas SOAP, el servidor puede llamar a las APIs REST OAuth 2.0 de la Nueva Plataforma más recientes de Five9 (p. ej. Círculos, interacciones, prompts, metadatos de dominio). Estas usan una credencial diferente del nombre de usuario/contraseña SOAP:

• Un Consumer Key y un Consumer Secret de API Access Control, generados en la Admin Console → API Access Control de Five9 (una función de disponibilidad controlada). Para generar uno se necesita el permiso security → applications → Create applications, y la cuenta debe estar migrada a Five9 Identity Service (los usuarios con roles heredados de API/Agent/Supervisor quedan excluidos de la migración hasta que se eliminen esos roles).

• Configúralos como variables de entorno/secreto (todas independientes de las credenciales SOAP):

FIVE9_CONSUMER_KEY=...           # "All APIs access" family credential (default)
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109           # your Admin Console domain id
FIVE9_REST_REGION=US             # US | US-ALPHA | CA | EU | IN | UK
# or pin the base URL directly: FIVE9_REST_BASE_URL=https://api.prod.us.five9.net

# Optional second credential for the "Data Tables access" family (its own key):
FIVE9_DT_CONSUMER_KEY=...
FIVE9_DT_CONSUMER_SECRET=...

Luego ejecuta rest_check_connection para confirmar el flujo del token. Lo que cada credencial puede alcanzar está determinado por su familia de API + scopes — all-apis-access no concede literalmente todos los servicios, y el acceso de escritura es por servicio.

Múltiples credenciales / familias. Cada credencial de API Access Control pertenece a una familia (asignada a un API Product de Apigee), y esa familia decide qué servicios puede llamar la clave. El servidor admite credenciales con nombre: default (procedente de FIVE9_CONSUMER_KEY/SECRET) y data-tables (procedente de FIVE9_DT_CONSUMER_KEY/SECRET). Las herramientas de Data Tables usan la credencial data-tables automáticamente; rest_call y rest_check_connection aceptan un argumento credential para elegir una.

Nota: la documentación de introducción de Five9 indica el endpoint de token como /v1/auth/token, pero el endpoint real es /oauth2/v1/token (el que usa este cliente).

🎨 Personalización del contexto del operador

src/about.js contiene el texto que se sirve a las IA conectadas a través del campo instructions de MCP y la herramienta about: quién opera el servidor, por qué existe y cómo debe comportarse la IA (p. ej., «confirm before write actions»). Edítalo para describir tu propia implementación — se distribuye con el contexto del operador original como ejemplo.

🏗️ Arquitectura

Sin paso de compilación ni dependencias: módulos JS simples en src/:

src/
├── index.js   # router, CORS, MCP JSON-RPC handler, /setup endpoint
├── five9.js   # SOAP client: envelope builder, ~60-line XML parser, one method per Five9 op
├── tools.js   # MCP tool definitions (JSON Schema) + dispatch
├── oauth.js   # stateless OAuth 2.1 server (single-operator model)
├── config.js  # config resolution: Wrangler secrets > KV (setup wizard)
├── ui.js      # landing page, setup wizard, interactive console
└── about.js   # operator context — edit this for your deployment

Las peticiones no tienen estado: cada llamada MCP abre una nueva conversación SOAP con Five9 usando autenticación HTTP Basic. La API de Statistics además requiere una llamada setSessionParameters, que get_realtime_stats realiza en cada invocación.

• Los endpoints de Five9 los genera JAXB y validan el orden de los elementos hijo contra la secuencia del WSDL. Si extendiende este servidor, extrae el WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, autenticación HTTP Basic) y respeta el orden de <xs:sequence> exactamente — incluidos los tipos base como basicImportSettings, cuyos elementos van antes que los de la extensión.

• addToListCsv requiere cleanListBeforeUpdate, crmAddMode, crmUpdateMode y listAddMode aunque el WSDL marque la mayoría como minOccurs="0".

• Las importaciones de listas/CRM son asíncronas: la llamada devuelve un identificador de importación inmediatamente; consulta get_import_result para comprobar el resultado.

• Los valores de los registros de contacto vuelven envueltos (<values><data>…</data></values>); varias respuestas devuelven un solo objeto cuando se esperaría un array de un elemento. toArray() en five9.js normaliza esto.

• El orden de los criterios de tiempo de los informes es <end> antes de <start> (orden alfabético de JAXB).

• La xmlDefinition del IVR es el formato que persiste el diseñador visual: los módulos se conectan por GUID (ascendants / singleDescendant / branches), el texto TTS en línea se almacena como documentos gzip+base64 speakElement, y las comprobaciones de horario comercial comparan las variables del sistema __DAY__ (SUN=1..SAT=7) y __TIME__ (minutos desde la medianoche). ivr.js encapsula todo esto.

• getPrompts no devuelve ids de prompt (solo nombre + tipo). Las referencias a prompts de archivo dentro del XML de IVR se aceptan con id 0 y el nombre de lprompt y se normalizan en el servidor; el script que se envía regresa con el domainId agregado por el servidor.

🛡️ Seguridad

• Las credenciales de Five9 viven solo en tu cuenta de Cloudflare — como secretos de Worker o (en la ruta del asistente) en un namespace de Workers KV, cifradas en reposo. Ninguna herramienta las devuelve, y los secretos de Wrangler los protegen quitar stabilizan por encima de KV.

• El asistente de configuración está abierto solo en un servidor nuevo y sin configurar — ejecútalo justo después de desplegarlo. Una vez configurado, cualquier cambio requiere la clave de acceso actual, y los servidores gestionados por entorno rechazan cualquier cambio del asistente.

• Configuración completa (o establece MCP_AUTH_TOKEN). Un servidor no configurado y sin clave de acceso queda abierto: cualquiera que encuentre la URL puede manejar tu centro de contactos.

• Las herramientas de escritura (✏️ abajo) generan tu dominio. Limita el rol del usuario de la API Five9 a lo que deseas que la IA realmente pueda hacer; los permisos de Five9 son la verdadera barrera de seguridad.

• manage_dnc remove y delete_list requieren precaución adicional; las instrucciones de about indican a la IA que confirme antes de usarlas.

• La consola almacena tu clave de acceso solo en el localStorage del navegador, y las llamadas son same-origin a tu propio Worker.

💻 Desarrollo

npm run dev      # wrangler dev on http://localhost:8787
npm run deploy   # wrangler deploy

Pon los coloros locales en .dev.vars (ignorado por git):

FIVE9_USERNAME=apiuser@yourdomain
FIVE9_PASSWORD=...
MCP_AUTH_TOKEN=dev-local-token

# Optional — external AI voice providers for generate_prompt_audio.
# The default (Workers AI / Deepgram Aura) needs no key at all.
ELEVENLABS_API_KEY=...
OPENAI_API_KEY=...

# Optional — OAuth New Platform REST tools (separate credential; see below)
FIVE9_CONSUMER_KEY=...
FIVE9_CONSUMER_SECRET=...
FIVE9_DOMAIN_ID=131109
FIVE9_REST_REGION=US
FIVE9_DT_CONSUMER_KEY=...        # optional: "Data Tables access" family
FIVE9_DT_CONSUMER_SECRET=...

Luego abre http://localhost:8787/console, pega dev-local-token y ejecuta las herramientas contra tu dominio — o haz una prueba rápida desde la CLI con el fragmento de curl de arriba.

🤝 Contribuciones

¡Las PR son bienvenidas! La API de Config de Five9 tiene ~180 operaciones y este servidor cubre 69 de las más útiles; el patrón en five9.js y tools.js es fácil de extender (lee primero las notas sobre SOAP y te evitarás luchar con el WSDL). Por favor mantén la restricción de cero dependencias.

📄 Licencia

MIT · creado por Ryan Shatzkamer