nextiva-mcp

MCP server for Nextiva (contact center platform, built on the acquired Thrio product — API host is login.thrio.com / *.thrio.io). Exposes the Thrio data and analytics API's users, campaigns, contacts, queues, and work item history as MCP tools.

Naming note: MSPbots' own integration is registered as "Nextiva" (subjectCode=NEXTIVA); the underlying API and all documentation reference "Thrio", the contact-center product Nextiva acquired. This MCP covers exactly the 5 methods MSPbots itself has configured.

Overview

• Stateless HTTP service. No credentials are ever persisted — each request supplies its own username/password via headers, used only for the lifetime of that single request.

• Supports concurrent requests; per-request credential isolation is done via Python contextvars, not a global/shared client instance.

• Entry points: POST /mcp (MCP protocol) and GET /health (health check).

• Default port: 8080 (configurable via MCP_HTTP_PORT).

Related MCP server: five9-mcp

Authentication

Thrio's auth call returns both a token and the actual per-tenant API host to use — Thrio is deployed across multiple regional clusters, so there is no single fixed data-plane hostname:

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

2. Every real data/analytics call then goes to {location} (not login.thrio.com) with the token sent as-is in an Authorization header — no Bearer prefix.

Since there is no session to preserve, this server re-authenticates fresh on every single tool call — nothing is cached or persisted across MCP requests.

HEADER 授权参数说明

Missing either header returns 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": []
}

An invalid username/password surfaces as a tool-level error during the internal login step, not an HTTP-level error from this server.

Environment Variables

MCP Endpoint

• POST /mcp — MCP protocol (streamable HTTP transport)

• GET /health — health check, returns {"status": "ok"} (pure local probe, does not call the Nextiva/Thrio API)

Tool List

All 5 tools are read-only (readOnlyHint=True, idempotentHint=True); there are no write/delete tools.

Per-parameter documentation lives on each tool's parameter schema (visible via tools/list), not in this table — this table is a quick-reference only and parameter names here are kept in sync with the code.

Successful responses are the vendor's JSON, compactly serialized (no pretty-printing, ensure_ascii=False) and capped at ~20,000 characters — an oversized list response is truncated with truncated/original_count markers rather than returned in full. There is no vendor-documented limit/page-size parameter for these endpoints (pagination is a start offset only, see Known Gaps below), so there is nothing to clamp beyond this automatic character cap.

Errors are returned as a JSON error envelope (not an exception/HTTP error), e.g.:

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

code is one of not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error, mapped from the Thrio API's HTTP status code (see error_envelope/NextivaError.to_envelope in api_client.py). Outbound calls use a 5s connect / 30s read timeout, and retry up to 3 times with capped exponential backoff on 429/5xx responses (respecting Retry-After).

测试示例

# 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-verified (2026-07-30) against a real Nextiva/Thrio tenant, all 5 tools called end-to-end through this running server: nextiva_get_users returned 101 real users; nextiva_get_campaigns returned 9 real campaigns (e.g. "Nextiva - Transfers"); nextiva_get_contacts returned 99 real contacts; nextiva_get_queues returned 18 real queues; and nextiva_get_workitems_history returned real summary totals (e.g. 297 inbound, 195 outbound, 500 contacts in the last 7 days) — all with the login step resolving the tenant's real cluster host dynamically (https://mancity.thrio.io).

API Reference

• Public, no login required: https://api.thrio.com/ (Postman-generated documentation covering Authentication, Objects/Data API, Analytics, and more)

Known Gaps

• Scope is exactly MSPbots' 5 configured endpoints, not the vendor's full API surface — Thrio's API also covers Workitem actions, List Management, Dashboards, Recordings, Contact Consent, State DID, Chat, CRM, Client, Number Verification, WFM, TEAMS, Callbacks, and more (per the public docs' own navigation); those are out of scope here.

• Pagination is a start offset, confirmed empirically (passing start=1 shifted the result window by one and updated the response's previous field accordingly) — the vendor's public docs describe this less explicitly than the request/response shape actually demonstrates, so this was verified against the live API rather than assumed from the docs alone.

• The session/login step described in the vendor's docs (POST {location}/users/api/login) is NOT used by this server — it appeared necessary only for creating a full interactive agent session (e.g. for telephony/ACD state), not for the read-only data/analytics endpoints MSPbots uses, which worked correctly with just the Authentication token. Confirmed by successfully calling all 5 endpoints without it.