oitvoip-mcp

MCP-Server für Oitvoip (gehostete VoIP/UCaaS-Reseller-Plattform, basierend auf NetSapiens — API-Host-Muster ist {tenant-pbx-host}/ns-api/). Stellt die Domain-, Reseller-, Geräte-, Subscriber- und CDR-Methoden der ns-api von NetSapiens als MCP-Tools bereit.

Hinweis zur Benennung: Die eigene Integration von MSPbots ist als „Oitvoip" registriert (subjectCode=NS — kurz für NetSapiens); die zugrunde liegende API und die gesamte offizielle Dokumentation verwenden die Bezeichnungen „NetSapiens" / „ns-api". Dieser MCP deckt genau die 5 Methoden ab, die MSPbots selbst konfiguriert hat.

Überblick

• Zustandsloser HTTP-Dienst. Es werden niemals Anmeldedaten gespeichert — jede Anfrage übermittelt ihre eigenen Anmeldedaten über Header, die nur für die Lebensdauer dieser einzelnen Anfrage verwendet werden.

• Unterstützt parallele Anfragen; die Isolierung der Anmeldedaten pro Anfrage erfolgt über Pythons contextvars, nicht über eine globale/geteilte Client-Instanz.

• Einstiegspunkte: POST /mcp (MCP-Protokoll) und GET /health (Gesundheitsprüfung).

• Standardport: 8080 (konfigurierbar über MCP_HTTP_PORT).

Related MCP server: whmcs-mcp-server

Authentifizierung

NetSapiens verwendet das standardmäßige OAuth2-Password-Grant-Verfahren:

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

Das resultierende access_token ist 1 Stunde gültig, aber dieser Server authentifiziert sich bei jedem einzelnen Tool-Aufruf neu, anstatt es über MCP-Anfragen hinweg zwischenzuspeichern — es wird nichts zwischengespeichert oder persistiert. Jeder echte ns-api-Aufruf sendet dann Authorization: Bearer <access_token>.

Header-Parameter für die Autorisierung

Fehlt einer der Header, wird 401 zurückgegeben:

{
  "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": []
}

Eine ungültige Anmeldeinformation oder ein authentifiziertes, aber nicht ausreichend berechtigtes Subscriber-Konto erscheint als unauthorized-Fehler-Envelope auf Tool-Ebene (die Meldung enthält die eigene Detailangabe des Anbieters, z. B. Invalid Scope [APP001]), nicht als HTTP-Fehler dieses Servers — siehe „Bekannte Lücken".

Umgebungsvariablen

MCP-Endpunkt

• POST /mcp — MCP-Protokoll (streambarer HTTP-Transport)

• GET /health — Gesundheitsprüfung, gibt {"status": "ok"} zurück (reine lokale Prüfung, ruft die Anbieter-API nicht auf)

Tool-Liste

Die Antworten sind die JSON-Antworten des Anbieters (Array oder Objekt, je nach Methode), kompakt serialisiert (ohne Einrückung, ensure_ascii=False). Wenn eine Antwort ~20.000 Zeichen überschreiten würde, wird das größte Listenfeld gekürzt und das Ergebnis enthält truncated: true sowie die ursprüngliche Anzahl, anstatt einen unbegrenzten Datenblock zurückzugeben. Alle 5 Tools sind schreibgeschützt (readOnlyHint) — es gibt keine Schreib-/Lösch-Tools in diesem Dienst.

Im Fehlerfall geben die Tools einen strukturierten JSON-Fehler-Envelope zurück, anstatt eine Ausnahme auszulösen:

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

code ist einer der Werte not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error; retryable gibt an, ob der Agent bedenkenlos erneut versuchen darf (true für rate_limited und upstream_error).

Testbeispiel

# 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"}
    }
  }'

Live-verifiziert (2026-07-30) gegen einen echten Mandanten: Alle 5 Tools wurden über diesen laufenden Server End-to-End aufgerufen: oitvoip_get_subscribers lieferte echte Subscriber-/Nebenstellen-Datensätze; oitvoip_get_devices lieferte echte registrierte SIP-Geräte (Polycom-Endpunkte, Live-Registrierungsstatus); oitvoip_get_cdr2 lieferte echte Gesprächsdatensätze für den angegebenen Datumsbereich. oitvoip_get_domains und oitvoip_get_resellers erreichten die API korrekt und lieferten einen klaren, erwarteten 401 Invalid Scope [APP001]-Fehler auf Tool-Ebene — die bereitgestellten Test-Anmeldedaten sind ein Konto auf Subscriber-Ebene (scope: "Office Manager"), das auf dieser speziellen NetSapiens-Instanz keine Admin-Rechte für Domänen/Reseller besitzt; siehe „Bekannte Lücken".

API-Referenz

• Öffentlich, keine Anmeldung erforderlich: https://api.ucaasnetwork.com/ns-api/apidoc/ (vollständige ns-api-Referenz, einschließlich der OAuth2-, Domain-, Reseller-, Device-, Subscriber- und CDR-Objekte)

Bekannte Lücken

• Der Umfang entspricht exakt den 5 von MSPbots konfigurierten Endpunkten, nicht der vollständigen API-Oberfläche des Anbieters — ns-api deckt außerdem Callqueue, Agent, Phonenumber, Dialplan, Contacts, Presence, Call Queue Report/Stat, Echtzeit-Anrufsteuerung und mehr ab (gemäß der eigenen Objektliste der öffentlichen Dokumentation); diese fallen hier nicht in den Umfang.

• oitvoip_get_domains und oitvoip_get_resellers konnten nicht vollständig mit echten Daten live verifiziert werden — das bereitgestellte Testkonto authentifiziert sich erfolgreich (was beweist, dass der OAuth2-Ablauf und diese Implementierung korrekt sind), ist aber auf eine „Office Manager"-Rolle auf Subscriber-Ebene beschränkt, die NetSapiens für diese beiden Objekte auf Admin-Ebene mit 401 Invalid Scope [APP001] ablehnt. Dies ist eine bere