oitvoip-mcp

Servidor MCP para Oitvoip (plataforma de reventa de VoIP/UCaaS alojada, construida sobre NetSapiens — el patrón de host de API es {tenant-pbx-host}/ns-api/). Expone los métodos de dominio, revendedor, dispositivo, suscriptor y CDR de la API ns-api de NetSapiens como herramientas MCP.

Nota de nomenclatura: la integración propia de MSPbots está registrada como "Oitvoip" (subjectCode=NS, abreviatura de NetSapiens); la API subyacente y toda la documentación oficial hacen referencia a "NetSapiens" / "ns-api". Este MCP cubre exactamente los 5 métodos que el propio MSPbots tiene configurados.

Descripción general

• Servicio HTTP sin estado. Nunca se guardan credenciales: cada solicitud aporta sus propias credenciales 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 estado).

• Puerto predeterminado: 8080 (configurable mediante MCP_HTTP_PORT).

Related MCP server: whmcs-mcp-server

Autenticación

NetSapiens utiliza una concesión de contraseña OAuth2 estándar:

POST https://{site}/ns-api/oauth2/token/
  grant_type=password&client_id=...&client_secret=...&username=...&password=...
-> {"access_token": "...", "expires_in": 3600, "token_type": "Bearer", ...}

El access_token resultante es válido durante 1 hora, pero este servidor se vuelve a autenticar en cada llamada de herramienta en lugar de almacenarlo en caché entre solicitudes MCP; no se guarda ni persiste nada. Cada llamada real a ns-api envía entonces Authorization: Bearer <access_token>.

Parámetros de autorización de cabecera

Si falta alguna cabecera, se devuelve 401:

{
  "error": "Missing credentials",
  "message": "This server requires the X-Oitvoip-Site, X-Oitvoip-Client-Id, X-Oitvoip-Client-Secret, X-Oitvoip-Username, X-Oitvoip-Password headers",
  "required_headers": ["X-Oitvoip-Site", "X-Oitvoip-Client-Id", "X-Oitvoip-Client-Secret", "X-Oitvoip-Username", "X-Oitvoip-Password"],
  "optional_headers": []
}

Una credencial no válida o una cuenta de suscriptor autenticada pero sin el ámbito suficiente se manifiesta como un sobre de error unauthorized a nivel de herramienta (el mensaje incluye el detalle del propio proveedor, p. ej. Invalid Scope [APP001]), no como un error a nivel HTTP de este servidor; consulte Limitaciones conocidas.

Variables de entorno

Punto de conexión MCP

• POST /mcp — protocolo MCP (transporte HTTP de transmisión)

• GET /health — comprobación de estado, devuelve {"status": "ok"} (sonda local pura, no llama a la API del proveedor)

Lista de herramientas

Las respuestas son el JSON del proveedor (matriz u objeto según el método), serializado de forma compacta (sin sangría, ensure_ascii=False). Si una respuesta superara los ~20 000 caracteres, el campo de lista más grande se trunca y el resultado incluye truncated: true junto con el recuento original, en lugar de devolver un bloque ilimitado. Las 5 herramientas son de solo lectura (readOnlyHint); no hay herramientas de escritura/eliminación en este servicio.

Ante un error, las herramientas devuelven un sobre de error JSON estructurado en lugar de lanzar una excepción:

{"error": {"code": "unauthorized", "message": "...", "retryable": false}}

code es uno de not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error; retryable indica si el agente puede reintentar de forma segura (verdadero para rate_limited y upstream_error).

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-Oitvoip-Site: pbx.example.com" \
  -H "X-Oitvoip-Client-Id: 58900.mspbot" \
  -H "X-Oitvoip-Client-Secret: <your-client-secret>" \
  -H "X-Oitvoip-Username: 1000@example" \
  -H "X-Oitvoip-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": "oitvoip_get_subscribers",
      "arguments": {"domain": "example.58900.service"}
    }
  }'

Verificado en vivo (2026-07-30) contra un arrendatario real, con las 5 herramientas llamadas de extremo a extremo a través de este servidor en ejecución: oitvoip_get_subscribers devolvió registros reales de suscriptores/extensiones; oitvoip_get_devices devolvió dispositivos SIP registrados reales (terminales Polycom, estado de registro en vivo); oitvoip_get_cdr2 devolvió registros de detalle de llamadas reales para el rango de fechas dado. oitvoip_get_domains y oitvoip_get_resellers alcanzaron correctamente la API y mostraron un error de herramienta limpio y esperado 401 Invalid Scope [APP001]; las credenciales de prueba proporcionadas son de una cuenta a nivel de suscriptor (scope: "Office Manager"), que no tiene privilegios administrativos de dominio/revendedor en esta implementación concreta de NetSapiens; consulte Limitaciones conocidas.

Referencia de API

• Pública, sin necesidad de inicio de sesión: https://api.ucaasnetwork.com/ns-api/apidoc/ (referencia completa de ns-api, incluidos los objetos OAuth2, Domain, Reseller, Device, Subscriber y CDR)

Limitaciones conocidas

• El alcance es exactamente los 5 puntos de conexión configurados por MSPbots, no toda la superficie de API del proveedor — ns-api también cubre Callqueue, Agent, Phonenumber, Dialplan, Contacts, Presence, Call Queue Report/Stat, control de llamadas en tiempo real y más (según la propia lista de objetos de la documentación pública); esos quedan fuera del alcance aquí.

• oitvoip_get_domains y oitvoip_get_resellers no pudieron verificarse completamente en vivo con datos reales — la cuenta de prueba proporcionada se autentica correctamente (lo que demuestra que el flujo OAuth2 y esta implementación son correctos), pero tiene un ámbito de rol "Office Manager" a nivel de suscriptor, que NetSapiens rechaza para estos dos objetos de nivel administrativo con 401 Invalid Scope [APP001]. Esto es una limitación de privilegios de credenciales de la cuenta de prueba específica, no un error de este servidor — oitvoip_get_subscribers, oitvoip_get_devices y oitvoip_get_cdr2 tuvieron éxito con datos reales usando exactamente el mismo token de acceso del mismo inicio de sesión.

• Los campos de rango de fechas de CDR (start_date/end_date) son cadenas sin validar — se pasan al proveedor tal cual en formato YYYY-MM-DD HH:MM:SS, coincidiendo con el uso almacenado por el propio MSPbots; no se realiza ningún análisis de fechas en el lado del cliente.