nextiva-mcp

MCP-Server für Nextiva (Contact-Center-Plattform, basierend auf dem übernommenen Thrio-Produkt — API-Host ist login.thrio.com / *.thrio.io). Stellt die Benutzer, Kampagnen, Kontakte, Warteschlangen und Arbeitspunktverläufe der Thrio-Daten- und Analyse-API als MCP-Tools bereit.

Hinweis zur Benennung: Die eigene Integration von MSPbots ist als „Nextiva" registriert (subjectCode=NEXTIVA); die zugrunde liegende API und die gesamte Dokumentation beziehen sich auf „Thrio", das Contact-Center-Produkt, das Nextiva übernommen hat. Dieser MCP deckt genau die 5 Methoden ab, die MSPbots selbst konfiguriert hat.

Übersicht

• Zustandsloser HTTP-Dienst. Es werden niemals Anmeldeinformationen gespeichert — jede Anfrage liefert ihren eigenen Benutzernamen/Passwort über Header, die nur für die Lebensdauer dieser einzelnen Anfrage verwendet werden.

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

• Einstiegspunkte: POST /mcp (MCP-Protokoll) und GET /health (Health-Check).

• Standardport: 8080 (konfigurierbar über MCP_HTTP_PORT).

Related MCP server: five9-mcp

Authentifizierung

Der Authentifizierungsaufruf von Thrio gibt sowohl ein Token als auch den tatsächlichen API-Host pro Mandant zurück — Thrio ist über mehrere regionale Cluster verteilt, daher gibt es keinen festen Data-Plane-Hostnamen:

1. GET https://login.thrio.com/provider/token-with-authorities mit HTTP Basic Auth (username:password) → {"location": "https://<tenant-cluster>.thrio.io", "token": "..."}.

2. Jeder echte Daten-/Analyseaufruf geht dann an {location} (nicht login.thrio.com) mit dem Token unverändert in einem Authorization-Header — ohne Bearer -Präfix.

Da keine Sitzung erhalten bleibt, authentifiziert sich dieser Server bei jedem einzelnen Tool-Aufruf neu — nichts wird über MCP-Anfragen hinweg zwischengespeichert oder gespeichert.

HEADER-Autorisierungsparameter

Fehlt einer der beiden Header, wird 401 zurückgegeben:

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

Ein ungültiger Benutzername/Passwort erscheint als Fehler auf Tool-Ebene während des internen Anmeldeschritts, nicht als HTTP-Fehler von diesem Server.

Umgebungsvariablen

MCP-Endpunkt

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

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

Tool-Liste

Alle 5 Tools sind schreibgeschützt (readOnlyHint=True, idempotentHint=True); es gibt keine Schreib-/Lösch-Tools.

Die Dokumentation der einzelnen Parameter befindet sich im Parameterschema jedes Tools (einsehbar über tools/list), nicht in dieser Tabelle — diese Tabelle dient nur als Schnellreferenz, und die Parameternamen hier werden mit dem Code synchron gehalten.

Erfolgreiche Antworten sind das JSON des Anbieters, kompakt serialisiert (keine hübsche Formatierung, ensure_ascii=False) und auf ~20.000 Zeichen begrenzt — eine zu große Listenantwort wird mit truncated/original_count-Markierungen abgeschnitten, anstatt vollständig zurückgegeben zu werden. Es gibt keinen vom Anbieter dokumentierten limit/Seitengrößen-Parameter für diese Endpunkte (Paginierung ist nur ein start-Offset, siehe „Bekannte Lücken" unten), daher gibt es nichts zu begrenzen, außer dieser automatischen Zeichenbegrenzung.

Fehler werden als JSON-Fehlerumschlag zurückgegeben (kein Ausnahme-/HTTP-Fehler), z. B.:

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

code ist einer von not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, abgeleitet aus dem HTTP-Statuscode der Thrio-API (siehe error_envelope/NextivaError.to_envelope in api_client.py). Ausgehende Aufrufe verwenden ein 5s-Connect-/30s-Read-Timeout und wiederholen bis zu 3 Mal mit begrenztem exponentiellem Backoff bei 429/5xx-Antworten (unter Beachtung von Retry-After).

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

Live-verifiziert (2026-07-30) gegen einen echten Nextiva/Thrio-Mandanten, alle 5 Tools Ende-zu-Ende über diesen laufenden Server aufgerufen: nextiva_get_users lieferte 101 echte Benutzer; nextiva_get_campaigns lieferte 9 echte Kampagnen (z. B. „Nextiva - Transfers"); nextiva_get_contacts lieferte 99 echte Kontakte; nextiva_get_queues lieferte 18 echte Warteschlangen; und nextiva_get_workitems_history lieferte echte Zusammenfassungswerte (z. B. 297 eingehend, 195 ausgehend, 500 Kontakte in den letzten 7 Tagen) — alle mit dem Anmeldeschritt, der den echten Cluster-Host des Mandanten dynamisch auflöst (https://mancity.thrio.io).

API-Referenz

• Öffentlich, keine Anmeldung erforderlich: https://api.thrio.com/ (Postman-generierte Dokumentation, die Authentifizierung, Objekte/Daten-API, Analysen und mehr abdeckt)

Bekannte Lücken

• Der Umfang entspricht genau den 5 konfigurierten Endpunkten von MSPbots, nicht der vollständigen API-Oberfläche des Anbieters — die Thrio-API deckt auch Workitem-Aktionen, Listenverwaltung, Dashboards, Aufzeichnungen, Kontakteinwilligung, State DID, Chat, CRM, Client, Nummernprüfung, WFM, TEAMS, Rückrufe und mehr ab (laut eigener Navigation der öffentlichen Dokumentation); diese sind hier nicht enthalten.

• Paginierung ist ein start-Offset, empirisch bestätigt (das Übergeben von start=1 verschob das Ergebnisfenster um eins und aktualisierte das previous-Feld der Antwort entsprechend) — die öffentliche Dokumentation des Anbieters beschreibt dies weniger explizit, als die tatsächliche Anfrage-/Antwortstruktur zeigt, daher wurde dies gegen die Live-API verifiziert und nicht nur aus der Dokumentation angenommen.

• Der in der Dokumentation des Anbieters beschriebene session/login-Schritt (POST {location}/users/api/login) wird von diesem Server NICHT verwendet — er schien nur für die Erstellung einer vollständigen interaktiven Agentensitzung (z. B. für Telefonie/ACD-Zustand) erforderlich zu sein, nicht für die schreibgeschützten Daten-/Analyse-Endpunkte, die MSPbots verwendet und die mit nur dem Authentifizierungstoken korrekt funktionierten. Bestätigt durch erfolgreiches Aufrufen aller 5 Endpunkte ohne diesen Schritt.