nextiva-mcp

MCP-сервер для Nextiva (платформа контакт-центра, построенная на приобретённом продукте Thrio — хост API: login.thrio.com / *.thrio.io). Предоставляет пользователей, кампании, контакты, очереди и историю рабочих элементов из API данных и аналитики Thrio в виде MCP-инструментов.

Примечание: собственная интеграция MSPbots зарегистрирована под названием «Nextiva» (subjectCode=NEXTIVA); сам базовый API и вся документация ссылаются на «Thrio» — продукт контакт-центра, который приобрела Nextiva. Данный MCP покрывает ровно те 5 методов, которые настроены в самой MSPbots.

Обзор

• HTTP-сервис без состояния. Учётные данные никогда не сохраняются — каждый запрос передаёт собственные имя пользователя и пароль через заголовки, которые используются только в течение времени обработки этого одного запроса.

• Поддерживает одновременные запросы; изоляция учётных данных для каждого запроса реализуется через Python contextvars, а не через глобальный/общий клиентский экземпляр.

• Точки входа: POST /mcp (протокол MCP) и GET /health (проверка работоспособности).

• Порт по умолчанию: 8080 (настраивается через MCP_HTTP_PORT).

Related MCP server: five9-mcp

Аутентификация

Аутентификационный вызов Thrio возвращает и токен, и фактический адрес API для конкретного арендатора — Thrio развёрнут в нескольких региональных кластерах, поэтому единственного фиксированного узла data-plane не существует:

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

2. Затем каждый реальный вызов к данным/аналитике идёт на {location} (а не на login.thrio.com), а токен передаётся как есть в заголовке Authorization — без префикса Bearer .

Поскольку сохранять сессию не нужно, этот сервер выполняет новую аутентификацию при каждом вызове инструмента — между MCP-запросами ничего не кэшируется и не сохраняется.

Параметры авторизации в заголовках

Если отсутствует любой из заголовков, возвращается 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": []
}

Неверные имя пользователя или пароль проявляются как ошибка уровня инструмента на внутреннем этапе входа, а не как ошибка HTTP-уровня этого сервера.

Переменные окружения

Конечная точка MCP

• POST /mcp — протокол MCP (потоковый HTTP-транспорт, streamable HTTP transport)

• GET /health — проверка работоспособности, возвращает {"status": "ok"} (чисто локальная проверка, не обращается к API Nextiva/Thrio)

Список инструментов

Все 5 инструментов предназначены только для чтения (readOnlyHint=True, idempotentHint=True); инструментов записи/удаления нет.

Описание каждого параметра находится в схеме параметров соответствующего инструмента (видно через tools/list), а не в этой таблице; здесь приведён только краткий справочник, и имена параметров в таблице синхронизированы с кодом.

Успешные ответы — это JSON вендора, сериализованный компактно (без pretty-printing, ensure_utf8=False) и ограниченный ~20 000 символов — слишком большой ответ списком обрезается с маркерами truncated/original_count вместо возврата целиком. У этих endpoint нет задокументированного вендором параметра limit/размера страницы (пагинация — только сдвиг start, см. «Известные пробелы» ниже), поэтому ограничивать, кроме этого автоматического предела по символам, нечего.

Ошибки возвращаются в виде JSON-конверта (а не исключения/HTTP-ошибки), например:

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

code — одно из not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error; сопоставляется с HTTP-статусом кода API Thrio (см. error_envelope/NextivaError.to_envelope в api_client.py). Исходящие запросы используют таймаут подключения 5 секунд и таймаут ответа при чтении 30 секунд, а также до 3 повторных попыток с экспоненциальной задержкой записи при ответах 429/5xx (учитывая 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 tenant — all 5 tools were 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 over the last 7 days) — all with the real tenant cluster host dynamically resolved at the login step (https://mancitychamp.io).

Справочник по API

• Публичный, без необходимости входа: https://api.thrio.com/ (Postman-generated documentation covering Authentication, Objects/Data API, Analytics and much more)

Известные пробелы

• Область охвата — ровно 5 endpoints, сконфигурированных MSPbots, а не вся поверхность API вендора — в API Thrio также представлены действия Workitem, List Management, Dashboards, Recordings, Contact Consent, State DID, Chat, CRM, Client, Number Verification, WFM, TEAMS, Callback и другие (по навигации публичной документации); они не входят в область данного MCP.

• Пагинация представляет собой offset start, что подтверждено эмпирически (передача start=1 смещала окно результатов на одну и обновляла поле previous в ответе) — публичная документация вендора описывает это менее явно, чем реальная форма запроса/ответа, поэтому это было проверено на живом API, а не просто взято из текстовой документации.

• Описание в документации вендора этап «запроса сессии» (POST {location}/users/api/login) этим сервером НЕ используется — он кажется необходимым только для создания полной интерактивной сессии агента (например, для телефонии/ACD-состояния), но не для чтения данных/аналитических endpoints, которые использует MSPbots; они корректно работали только с токеном Authentication. Это подтверждено успешными вызовами всех 5 endpoints без этого этапа.