nextiva-mcp

Servidor MCP para Nextiva (plataforma de contact center, construida sobre el producto adquirido Thrio — el host de la API es login.thrio.com / *.thrio.io). Expone como herramientas MCP los usuarios, campañas, contactos, colas e historial de elementos de trabajo de la API de datos y análisis de Thrio.

Nota sobre la nomenclatura: la integración de MSPbots está registrada como "Nextiva" (subjectCode=NEXTIVA); la API subyacente y toda la documentación hacen referencia a "Thrio", el producto de contact center que Nextiva adquirió. Este MCP cubre exactamente los 5 métodos que el propio MSPbots tiene configurados.

Resumen

• Servicio HTTP sin estado. Las credenciales nunca se persisten: cada solicitud aporta su propio nombre de usuario/contraseña mediante cabeceras, que se usan solo durante la vida de esa única solicitud.

• Admite solicitudes concurrentes; el aislamiento de credenciales por solicitud se realiza mediante contextvars de Python, no con una instancia de cliente global/compartida.

• Puntos de entrada: POST /mcp (protocolo MCP) y GET /health (comprobación de salud).

• Puerto por defecto: 8080 (configurable mediante MCP_HTTP_PORT).

Related MCP server: five9-mcp

Autenticación

La llamada de autenticación de Thrio devuelve tanto un token como el host real de la API específico del inquilino (tenant) que se debe usar — Thrio está desplegado en varios clústeres regionales, por lo que no existe un único nombre de host fijo del plano de datos:

1. GET https://login.thrio.com/provider/token-with-authorities con autenticación básica HTTP (username:password) → {"location": "https://<tenant-cluster>.thrio.io", "token": "..."}.

2. Cada llamada real de datos/análisis va entonces a {location} (no a login.thrio.com) con el token enviado tal cual en una cabecera Authorization — sin prefijo Bearer .

Dado que no hay ninguna sesión que conservar, este servidor se reautentica desde cero en cada llamada de herramienta — no se almacena en caché ni se persiste nada entre solicitudes MCP.

Parámetros de autorización de la cabecera

Si falta cualquiera de las dos cabeceras, se devuelve 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Nextiva-Username and X-Nextiva-Password headers",
  "required_headers": ["X-Nextiva-Username", "X-Nextiva-Password"],
  "optional_headers": []
}

Un nombre de usuario/contraseña no válido se manifiesta como un error a nivel de herramienta durante el paso de inicio de sesión interno, no como un error a nivel HTTP de este servidor.

Variables de entorno

Endpoint MCP

• POST /mcp — protocolo MCP (transporte HTTP transmisible)

• GET /health — comprobación de salud, devuelve {"status": "ok"} (verificación puramente local, no llama a la API de Nextiva/Thrio)

Lista de herramientas

Las 5 herramientas son de solo lectura (readOnlyHint=True, idempotentHint=True); no hay herramientas de escritura/eliminación.

La documentación por parámetro reside en el esquema de parámetros de cada herramienta (visible mediante tools/list), no en esta tabla — esta tabla es solo una referencia rápida y los nombres de los parámetros que aparecen aquí se mantienen sincronizados con el código.

Las respuestas correctas son el JSON del proveedor, serializado de forma compacta (sin pretty-printing, ensure_ascii=False) y limitado a ~20.000 caracteres — una respuesta de lista demasiado grande se trunca con los marcadores truncated/original_count en lugar de devolverse completa. No hay un parámetro limit/page-size documentado por el proveedor para estos endpoints (la paginación es solo un desplazamiento start; consulte Limitaciones conocidas más abajo), por lo que no hay nada que limitar más allá de este tope automático de caracteres.

Los errores se devuelven como un sobre de error JSON (envelope) (no como una excepción/error HTTP), por ejemplo:

{"error": {"code": "upstream_error", "message": "...", "retryable": true}}

code es uno de not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, asignado a partir del código de estado HTTP de la API de Thrio (consulte error_envelope/NextivaError.to_envelope en api_client.py). Las llamadas salientes usan un timeout de conexión de 5 s y un timeout de lectura de 30 s, y reintentan hasta 3 veces con backoff exponencial acotado en respuestas 429/5xx (respetando Retry-After).

Ejemplo de prueba

# Health check
curl -s http://localhost:8080/health

# Call a tool via the MCP protocol (streamable HTTP) — requires an
# initialize handshake first per the MCP spec; abbreviated example below
# shows the tool-call request body only:
curl -s -X POST http://localhost:8080/mcp \
  -H "X-Nextiva-Username: admin@example.com" \
  -H "X-Nextiva-Password: <your-password>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "mcp-session-id: <session-id-from-initialize>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "nextiva_get_users",
      "arguments": {}
    }
  }'

Verificado en vivo (2026-07-30) contra un tenant real de Nextiva/Thrio; las 5 herramientas se ejecutaron de extremo a extremo a través de este servidor en ejecución: nextiva_get_users devolvió 101 usuarios reales; nextiva_get_campaigns devolvió 9 campañas reales (por ejemplo, "Nextiva - Transfers"); nextiva_get_contacts devolvió 99 contactos reales; nextiva_get_queues devolvió 18 colas reales; y nextiva_get_workitems_history devolvió totales resumidos reales (por ejemplo, 297 entrantes, 195 salientes, 500 contactos en los últimos 7 días) — todo con el paso de inicio de sesión resolviendo dinámicamente el host real del clúster del tenant (https://mancity.thrio.io).

Referencia de la API

• Pública, sin necesidad de iniciar sesión: https://api.thrio.com/ (documentación generada con Postman que cubre Authentication, Objects/Data API, Analytics y más)

Limitaciones conocidas

• El alcance es exactamente los 5 endpoints configurados por MSPbots, no la superficie completa de la API del proveedor — la API de Thrio también cubre Workitem actions, List Management, Dashboards, Recordings, Contact Consent, State DID, Chat, CRM, Client, Number Verification, WFM, TEAMS, Callbacks y más (según la propia navegación de la documentación pública); todo eso queda fuera del alcance aquí.

• La paginación es un desplazamiento start, confirmado empíricamente (pasar start=1 desplazó la ventana de resultados en uno y actualizó el campo previous de la respuesta en consecuencia) — la documentación pública del proveedor describe esto de forma menos explícita de lo que realmente demuestra la forma de la solicitud/respuesta, por lo que se verificó contra la API en vivo en lugar de asumirlo solo a partir de la documentación.

• El paso session/login descrito en la documentación del proveedor (POST {location}/users/api/login) NO lo usa este servidor — parecía necesario únicamente para crear una sesión interactiva completa de agente (por ejemplo, para el estado de telefonía/ACD), no para los endpoints de datos/análisis de solo lectura que usa MSPbots, que funcionaron correctamente con solo el token de autenticación. Confirmado al llamar correctamente a los 5 endpoints sin él.