☎️ 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, que se ejecuta en Cloudflare Workers con cero dependencias.

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

Pídele a tu IA cosas como:

"¿Quién está en una llamada ahora mismo y cuánta cola hay en ventas?" 📊 "Crea una campaña de previsualización para la lista de reactivació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." 📞 "Incorpora al nuevo agente: crea el usuario, asigna la habilidad de facturación en nivel 2." 🧑💼 "¿Está 555-867-5309 en nuestra lista DNC? Compruébalo antes de que alguien marque ese número." 🚫 "Extrae el informe de registro de llamadas de ayer y resume las tasas de abandono." 📈 "Constrúyeme un IVR completo: opción 1, programación; opción 2, facturación; fuera de horario, al buzón de voz." 🧩

En el fondo, este servidor habla con los SOAP Web Services de Configuration (administración) y Statistics (supervisión) de Five9 — las API que aún sustentan la superficie administrativa de Five9 — y los expone como herramientas JSON limpias a través de MCP streamable HTTP. Sobres SOAP hechos a mano, un analizador XML de ~60 líneas, sin paquetes npm. Cada herramienta se ha probado contra un dominio Five9 real.

✨ Interfaz web integrada

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

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

🚀 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 ve haciendo clic: se creará tu propia copia de este Worker (junto con el espacio de nombres KV que necesita) y te dará 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 las verifica en vivo contra Five9 antes de guardarlas y te entrega tu clave de acceso (se muestra una sola vez; guárdala en un gestor de contraseñas).

3 — Conecta tu IA (tutoriales a continuación) y 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 puedes usar el asistente /setup u omitirlo y gestionar las credenciales como secretos de Wrangler (los secretos tienen prioridad sobre el 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

Conecta 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. Ponle el nombre Five9 y pega la URL de tu servidor incluyendo la ruta /mcp: https://<your-worker>.workers.dev/mcp

4. Haz clic en Añadir y luego en Conectar. Claude detecta 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ú Buscar y herramientas (＋) y asegúrate de que el conector de Five9 está activado.

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

Conecta ChatGPT

Los conectores MCP personalizados requieren el modo de 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 de desarrollador.

3. De vuelta en la página de Conectores, haz clic en Crear.

4. Ponle el nombre Five9, establece la URL del servidor MCP en https://<your-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ú ＋ / herramientas y activa el conector Five9 (los conectores del modo de desarrollador se activan por conversación). ChatGPT te pedirá que confirmes cada llamada a herramienta, algo sensato para cualquier cosa que pueda iniciar un marcador. 😄

Conecta 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 en bruto funciona directamente como bearer token, sin el baile de OAuth. Ejecuta /mcp dentro de Claude Code para verificarlo.

Cualquier otro cliente MCP

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

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 refresco) diseñado para un despliegue de un solo operador:

• El «login» en la pantalla de consentimiento es la clave de acceso del servidor (MCP_AUTH_TOKEN).

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

• Ambas vías de autenticación funcionan a la vez: tokens emitidos por OAuth y la clave en bruto como credencial bearer.

• 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 primero confirmen contigo)

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

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 e implementa un script IVR funcional. El modelo nunca improvisa el XML de IVR de Five9: rellena una especificación de flujo JSON restringida (play / menu / business-hours / skill transfer / voicemail / hangup), un validador de grafo comprueba cada rama y referencia, y un código determinista genera XML con la forma del diseñador (el cableado de módulos, la codificación de prompts y el orden de campos se derivan de scripts exportados reales).

Flujo recomendado: valida → renderiza (¡muéstraselo al humano!) → genera prompts → construye → adjúntalo 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 prompt facturadas a la cuenta de Cloudflare en la que ya lo has desplegado. ElevenLabs/OpenAI también funcionan si configuras sus secretos de clave, y los prompts {tts} (la voz de robot integrada de Five9) no necesitan nada en absoluto.

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

🔐 OAuth New Platform APIs

Además de las herramientas SOAP, el servidor puede llamar a las APIs REST OAuth 2.0 de la New Platform de Five9 (p. ej. Circles, interacciones, prompts, metadatos del dominio). Estas usan una credencial diferente del 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). Generarlos requiere el permiso security → applications → Create applications, y la cuenta debe estar migrada a Five9 Identity Service (los usuarios con roles heredados de API/Agente/Supervisor quedan excluidos de la migración hasta que se eliminen esos roles).

• Configúralos como variables de entorno/secreto (todas separadas 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 otorga 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 (mapeada a un Apigee API Product), y esa familia decide qué servicios puede llamar la clave. El servidor admite credenciales con nombre: default (de FIVE9_CONSUMER_KEY/SECRET) y data-tables (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: El documento de inicio rápido de Five9 indica el endpoint del token como /v1/auth/token, pero el endpoint real es /oauth2/v1/token (el que usa este cliente).

🎨 Personalizar el 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 de la herramienta about: quién opera el servidor, por qué existe y cómo debe comportarse la IA (p. ej., "confirmar antes de las acciones de escritura"). Edítalo para describir tu propio despliegue — se incluye 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 un intercambio SOAP nuevo con Five9 mediante autenticación HTTP Basic. La API de Statistics requiere además una llamada a setSessionParameters, que get_realtime_stats realiza en cada invocación.

• Los endpoints de Five9 están generados por JAXB y validan el orden de los elementos hijo contra el WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, autenticación HTTP Basic) y se ajustan exactamente al orden de <xs:sequence> — 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 marca la mayoría de ellos como minOccurs="0".

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

• Los valores de los registros de contacto se devuelven envueltos (<values><data>…</data></values>); varias respuestas devuelven un objeto único donde cabría esperar 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).

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

• getPrompts no devuelve ningún id de prompt (solo nombre + tipo). Las referencias a prompts de archivo dentro del XML de IVR se aceptan con id 0 + el nombre del prompt y se normalizan en el servidor; el script enviado regresa con el domainId añadido por el servidor.

🛡️ Seguridad

• Las credenciales de Five9 residen únicamente en tu cuenta de Cloudflare — como secretos de Worker o (ruta del asistente) en un namespace de Workers KV, cifrados en reposo. Ninguna herramienta las devuelve jamás, y los secretos de Wrangler siempre tienen prioridad sobre KV.

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

• Completa siempre la configuración (o establece MCP_AUTH_TOKEN). Un servidor sin configurar y sin clave de acceso queda abierto — cualquiera que encuentre la URL puede operar tu centro de contacto.

• Las herramientas de escritura (✏️ arriba) modifican tu dominio. Ajusta el rol del usuario de la API de Five9 a lo que realmente quieras que haga una IA — los permisos de Five9 son la verdadera frontera de seguridad.

• manage_dnc remove y delete_list merecen una precaución extra; las instrucciones de about indican a las IA que confirmen antes de usarlas.

• La consola almacena tu clave de acceso solo en el localStorage de tu navegador, y las llamadas van al mismo origen hacia tu propio Worker.

💻 Desarrollo

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

Pon los secretos 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

¡Se aceptan PRs! La API Config de Five9 tiene ~180 operaciones y este servidor envuelve 69 de las más útiles — el patrón en five9.js + tools.js es fácil de extender (lee primero las notas de SOAP y ahórrate una pelea con el WSDL). Por favor, mantén la restricción de cero dependencias.

📄 Licencia

MIT · creado por Ryan Shatzkamer