☎️ 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 al centro de contacto en la nube Five9 — funcionando 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 llamada ahora mismo, y qué tan profunda es la cola de ventas?" 📊 "Crea una campaña de previsualización para la lista de recuperación, asigna la habilidad de ventas e iníciala." 🛠️ "Detén la campaña OUTBOUND_AGED y agrega estos 3 leads a la lista de devolución de llamada." 📞 "Integra al nuevo agente: crea el usuario, asigna la habilidad de facturación en nivel 2." 🧑💼 "¿Está 555-867-5309 en nuestro DNC? Verifica antes de que alguien lo marque." 🚫 "Obtén el informe de registro de llamadas de ayer y resume las tasas de abandono." 📈 "Créame un IVR completo: opción 1 para programación, opción 2 para facturación, fuera de horario va al buzón de voz." 🧩

Internamente, este servidor habla con los Servicios Web SOAP de Configuración (administración) y Estadísticas (supervisor) de Five9 — las APIs que aún manejan la superficie administrativa de Five9 — y los expone como herramientas JSON limpias a través de HTTP MCP transmisible. Envoltorios 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 el alcance de lo que quieras que la IA haga, 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 (más el 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. Ingresa tu nombre de usuario, contraseña y región de Five9 — el asistente los verifica en vivo contra Five9 antes de guardar, luego te entrega tu clave de acceso (se muestra una vez — guárdala en un gestor de contraseñas).

3 — Conecta tu IA (tutoriales abajo), luego pídele que "verifique 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 saltalo 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 planes Free (un conector), Pro, Max, Team y Enterprise.

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

2. Haz clic en Agregar 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 Agregar, 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 agrega el conector en Configuración de la organización → Conectores; luego los miembros hacen clic en Conectar en su propia configuración para autorizar.

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 → Aplicaciones y conectores (a veces etiquetado solo como Conectores).

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

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

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

5. Acepta el mensaje 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 nuevo chat, abre el menú ＋ / herramientas y activa el conector Five9 (los conectores del modo Desarrollador se habilitan por conversación). ChatGPT te pide confirmar 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 en bruto funciona directamente como un token de portador — sin baile OAuth. Ejecuta /mcp dentro de Claude Code para verificar.

Cualquier otro cliente MCP

Cualquier cosa que hable HTTP transmisible 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 un solo operador:

• 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 IDs de cliente, códigos de autorización y tokens son blobs firmados con HMAC-SHA256 claveados por MCP_AUTH_TOKEN. Sin KV, sin Durable Objects.

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

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

🧰 El taller de herramientas

77 herramientas. 🟢 = lectura (siempre seguro) · ✏️ = escritura (cambia tu dominio — el servidor le dice a las IAs que confirmen contigo primero)

69 herramientas SOAP (usuario/contraseña) + 8 herramientas REST de la Nueva Plataforma OAuth (Consumer Key/Secret — ver APIs de la Nueva Plataforma OAuth).

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: completa una especificación de flujo JSON restringida (reproducir / menú / horario laboral / transferencia de habilidad / buzón de voz / colgar), un validador de grafos verifica cada rama y referencia, y un código determinista emite XML con forma de diseñador (cableado de módulos, codificación de mensajes y orden de campos derivados de scripts exportados reales).

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

Estas herramientas utilizan las modernas APIs REST OAuth 2.0 de la "Nueva Plataforma" 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 — consulte APIs OAuth de la Nueva Plataforma.

🔐 APIs OAuth de la Nueva Plataforma

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

• Una Clave de Consumidor y un Secreto de Consumidor de Control de Acceso a la API, generados en el Admin Console → API Access Control de Five9 (una función de disponibilidad controlada). Generar una requiere 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 dichos roles).

• Configúralas como variables de entorno o secretos (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. El alcance de cada credencial está determinado por su familia de API + ámbitos — all-apis-access no concede literalmente todos los servicios, y el acceso de escritura es por servicio.

Varias credenciales / familias. Cada credencial del Control de Acceso a la API pertenece a una familia (asignada 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 automáticamente la credencial data-tables; rest_call y rest_check_connection aceptan un argumento credential para elegir una.

Nota: La documentación de inicio 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 IAs 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 (por ejemplo, "confirmar antes de acciones de escritura"). Edítalo para describir tu propio despliegue — se incluye el contexto del operador original como ejemplo.

🏗️ Arquitectura

Sin paso de compilación, sin dependencias — módulos JS planos 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 solicitudes son sin estado: cada llamada MCP abre un intercambio SOAP nuevo con autenticación HTTP Basic. La API de Statistics requiere además una llamada setSessionParameters, que get_realtime_stats realiza por invocación.

• Los endpoints de Five9 son generados por JAXB y validan el orden de los elementos hijos contra la secuencia del WSDL. Si extiendes este servidor, descarga el WSDL (https://api.five9.com/wsadmin/v13/AdminWebService?wsdl, autenticación HTTP Basic) y respeta el orden de <xs:sequence> exactamente — incluyendo tipos base como basicImportSettings, cuyos elementos van antes de 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 obtener el resultado.

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

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

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

• getPrompts devuelve sin ids 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 hace el viaje de ida y vuelta con el domainId añadido por el servidor.

🛡️ Seguridad

• Las credenciales de Five9 residen solo en tu cuenta de Cloudflare — como secretos de Worker, o (ruta del asistente) en un espacio de nombres Workers KV, cifrados en reposo. Ninguna herramienta los devuelve, y los secretos de Wrangler siempre anulan los de KV.

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

• Completa siempre la configuración (o establece MCP_AUTH_TOKEN). Un servidor no configurado sin clave de acceso funciona abierto — cualquiera que encuentre la URL puede controlar tu centro de contacto.

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

• manage_dnc remove y delete_list merecen precaución adicional; las instrucciones de about indican a las IAs 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 de tu propio Worker.

💻 Desarrollo

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

Coloca los secretos locales en .dev.vars (en gitignore):

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 herramientas contra tu dominio — o haz pruebas rápidas desde la CLI con el fragmento de curl de arriba.

🤝 Contribuciones

¡Las PRs son bienvenidas! La API de Configuración 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 SOAP y ahorrate una pelea con el WSDL). Por favor, mantén la restricción de cero dependencias.

📄 Licencia

MIT · construido por Ryan Shatzkamer