☎️ five9-mcp

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

Un servidor MCP de código abierto que conecta Claude, ChatGPT o cualquier cliente MCP al centro de contacto en la nube de Five9 y se ejecuta en Cloudflare Workers con cero dependencias.

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

Puedes pedirle a tu IA cosas como:

"¿Quién está en una llamada ahora mismo y qué profunda está la cola de ventas?" 📊 "Crea una campaña de vista previa para la lista de recuperación, añade el skill de ventas e iníciala." 🛠️ "Detén la campaña OUTBOUND_AGED y añade estos 3 leads a la lista de callback." 📞 "Gestiona el alta del nuevo agente: crea el usuario, asigna el skill de facturación en nivel 2." 🧑💼 "¿Está el 555-867-5309 en nuestro DNC? Compruébalo antes de que nadie intente llamar." 🚫 "Prepára el informe Call Log de ayer y resume las tasas de abandono." 📈 "Construye un IVR completo: opción 1 agenda, opción 2 facturación, fuera de horario al buzón de voz." 🧩

Bajo el capó, este servidor habla con los servicios web SOAP de Five9 Configuration (administración) y Statistics (supervisión), es decir, las APIs que aún conforman la superficie de administración de Five9, y los expone como herramientas JSON limpias sobre MCP HTTP streamable. Trabajos hechos a mano, un analizador XML de unas 60 líneas, sin paquetes npm. Todas las herramientas se han ejercido contra un dominio Five9 real.

✨ Interfaz web integrado

Despliégalo y tu Worker no solo ofrece 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, no se necesita IA.

Related MCP server: five9-mcp

🚀 Inicio rápido, sin necesidad de abrir el terminal

Necesitas una cuenta gratuita de Cloudflare y un usuario de Five9 con acceso API: crea un usuario de API dedicado de Five9.. para no reutilizar un login de administrador personal.

1 - Repositorio en Cloudflare (o un solo clic, en tu browser)

Entra en Cloudflare y ve haciendo clic: crea tu propia copia de este Worker (además del espacio de nombres KV que necesita) y te proporciona una URL configurable https://five9-mcp.you.workers.dev.

2 - Activa el asistente de configuración (en tu navegador)

Abre /setup en tu nuevo servidor. Introduce tu usuario, contraseña y región de Five9; el asistente verifica las credenciales en vivo con Five9 antes de guardarlas, y te entrega tu clave de acceso (edge).

3 - Conecta tu IA (el resumen de abajo), y pídele eso que "verifique la conexión y liste tus 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 de /setup, o omitirlo y gestionar las credenciales como secretos de Wrangler (los secretos tienen bueno más ganado que 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 se encuentran en wrangler.toml y funcionan para dominios de EE. UU.:

🔌 Conecta tu IA

Conecta Claude (web y de escritorio)

Los conectores personalizados están disponibles en los planes Free (un momento), 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 ferente.

3. Ponle como nombre Five9 y pega la URL de tu servidor incluyendo la URL del endpoint /mcp: https://<tu-worker>.workers.dev/mcp

4. Haz clic en Añadir, 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. In any chat, open the search & tools (＋) menu and make sure the Five9 connector is toggled on.

Team/Enterprise: un Owner añade primero el conector en Configuración de la organización → Connectadores; después los miembros hacen clic en Conectar en sus propios ajustes para autorizar.

Conecta ChatGPT

Los conectores MCP personalizados requieren Developer mode (Plus/Pro; en Business/Enterprise un administrador debe permitir los conectores personalizados).

1. En ChatGPT desde el navegador, abre Configuración → Apps y Connadores (a veces solo aparece como Conectores).

2. En Advanced settings, activa Developer mode.

3. En la página de conectores, haz clic en Crear.

4. Ponle el nombre Five9, establece la MCP server URL en 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 una conversación nueva, abre el menú ＋ / herramientas y activa el conector Five9 (los conectores de Developer Mode se activan por conversación). ChatGPT te pedirá que confirmes cada ejecución de una herramienta; eso es prudente para lo 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 original funciona directamente como bearer token, sin necesidad de flujo OAuth. Ejecuta /mcp dentro de Claude Code para verificarlo.

Cualquier otro cliente MCP

Todo lo que hable MCP HTTP streamable funciona: completa el flujo OAuth o envía la clave de acceso como bearer beta:

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 minimal (descubrimiento de metadatos, registro dinámico de clientes, PKCE S256, tokens de refresco) pensado para un despliegue de un solo operador:

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

• Todo no cuenta con estado: los IDs de cliente, los códigos de autorización y los tokens son blobs firmados con HMAC-SHA256 y relacionados con MCP_AUTH_TOKEN. Ni KV, ni Durable Objects.

• Las dos rutas de autorización funcionan si ve OAuth: tanto los tokens emitidos por OAuth como la clave sin tratar con bearer token.

• Revocar todo de una vez es tan simple como rotar el secreto: npx wrangler secret put MCP_AUTH_TOKEN.

🧰 La caja de herramientas

77 herramientas. 🟢 = lectura (toda buena) · ✏️ = escritura (cambia tu dominio; el servidor y las IA que lo comprueban antes de ejecutarse)

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

El truco más importante: 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 instantión. El modelo no se inventa el XML IVR de Five9: rellena una especificación JSON restringida (reproducción / menú / horario / transferencia de habilidad / buzón de voz / colgar), un verificador de grafos comprueba cada rama y referencia, y un código determinista genera el XML con forma de la interfaz de Five5 (los emparejamientos de módulos, la codificación de prompts y el orden de campos se derivan de scripts exportados reales).

Flujo recomendado: validar → mostrarlo (¡enséñaselo!) → generar las prompts → construir → adjuntar al de campaña entrante. generate_prompt_audio funciona directamente en Cloudflare Workers AI: no es externo en Voice, no requiere clave de API, y una fracción de céntimo por prompt se supone que tienes en tu cuenta Cloudflare ya existente. ElevenLabs/OpenAI también funcionan si les pones sus claves secret, y los {tts} (la voz robótica incorporada en Five) no necesitan nada.

I'm making the same messy again. Need to stop.

Better approach: Since the instruction is to translate, not necessarily to make perfect formatting, I can output the exact same line count with the raw pipe columns and use the exact original row text for the tool col. The only necessary is to translate the descriptions.

Thus I'll write the final answer directly with copy-pasted pattern, only replacing text between the pipes. I'll not bother with the alignment. I'm going to write row by row.

Let me type intentionally:

I'll write the full output as if in a monospaced block. Let's go.

Final:

• API Access Control Consumer Key y Consumer Secret, generados en la Admin Console → API Access Control de Five9 (una funcionalidad de disponibilidad controlada). Para generar uno hacen falta 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 se excluyen de la migración hasta que se eliminen esos roles).

• Configúralos como variables env/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 de token. Lo que cada credencial puede alcanzar lo determina 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 (asociada a un Apigee API Product), y esa familia decide a 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 seleccionar una.

Nota: La guía de inicio de Five9 indica el endpoint del token como /v1/auth/token, pero el endpoint real es /oauth2/v1/token (el que utiliza este cliente).

🎨 Personalización del contexto del operador

src/about.js contiene el texto que se entrega a los asistentes de IA conectados mediante el 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., confirma antes de realizar acciones de escritura). Edítalo para describir tu propio despliegue — se incluye el contexto original del operador como ejemplo.

🏗️ Arquitectura

Sin paso de compilación ni dependencias — módulos de JavaScript puro 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 almacenan estado: cada llamada MCP abre un intercambio SOAP nuevo con Five9 con 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 se generan con JAXB y validan el orden de los elementos secundarios contra la secuencia del WSDL. Si extiendas este servidor, descarga el WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, autenticación HTTP Basic) y respeta exactamente el orden de <xs:sequence> — incluyendo los tipos base como basicImportSettings, cuyos elementos aparecen 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ó inmediatamente; consulta get_import_result para saber el resultado.

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

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

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

• getPrompts no devuelve ids de prompt (solo nombre y tipo). Las referencias a prompts de archivo dentro de XML de IVR se aceptan con id 0 junto con el nombre del prompt y se normalizan en el servidor; el script enviado viaja de ida y vuelta con el domainId añadido por el servidor.

🛡️ Seguridad

• Las credenciales de Five9 viven únicamente en tu cuenta de Cloudflare — como secretos de Worker o, en la ruta del asistente, en un espacio de nombres Workers KV, cifrados en reposo. Ninguna herramienta las devuelve nunca, y los secretos de Wrangler siempre tienen prioridad sobre KV.

• El asistente de configuración está disponible 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 variables de entorno rechazan los cambios del asistente por completo.

• Completa siempre la configuración (o define MCP_AUTH_TOKEN). Un servidor sin configurar y sin unpreguntes de acceso queda abierto — cualquiera que ello elija URL puede manejar tu centro de contacto.

• Las herramientas de escritura (✏️ más arriba) modifcan los datos de tu dominio. Limita el rol del usuario de la API de Five a lo que realmente quieras que haga una IA — los permisos de Five9 son la verdadera barrera de seguridad.

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

• La consola guarda tu clave de acceso solo en el localStorage del 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 (ignored 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, pegue dev-local-token, y ejecuta herramientas contra tu dominio — o haz una quick smoke from CLI with the above curl.

🤝 Contribuciones

¡PRs son bienvenidos! La Config API de Five9 tiene ~180 operaciones and este servicio wraps 69 de las más útiles — el patrón de five9.js + tools.js es fácil de extender (read the SOAP notes first and you get a fight with the WSDL). Por favor, mantén la restricción de cero dependencies.

📄 Licencia

MIT · creado por Ryan Shatzkamer