nextiva-mcp

Nextiva（コンタクトセンター・プラットフォーム。買収した Thrio 製品をベースに構築 — APIホストは login.thrio.com / *.thrio.io）用のMCPサーバー。Thrioのデータ/アナリティクスAPIのユーザー、キャンペーン、コンタクト、キュー、ワークアイテム履歴をMCPツールとして公開します。

命名に関する注記：MSPbots自身の統合は「Nextiva」として登録されています（subjectCode=NEXTIVA）。基盤となるAPIとすべてのドキュメントは、Nextivaが買収したコンタクトセンター製品「Thrio」を参照しています。このMCPは、MSPbots自身が設定した5つのメソッドのみをカバーしています。

概要

• ステートレスなHTTPサービス。認証情報は一切永続化されません。各リクエストが独自のユーザー名/パスワードをヘッダーで提供し、その単一リクエストの間だけ使用されます。

• 並行リクエストをサポート。リクエストごとの認証情報の分離は、グローバル/共有クライアントインスタンスではなく、Pythonの contextvars によって行われます。

• エントリーポイント：POST /mcp（MCPプロトコル）と GET /health（ヘルスチェック）。

• デフォルトポート：8080（MCP_HTTP_PORT で設定可能）。

Related MCP server: five9-mcp

認証

Thrioの認証呼び出しは、トークンと、使用する実際のテナント別APIホストの両方を返します。Thrioは複数のリージョナルクラスターにデプロイされているため、固定された単一のデータプレーン・ホスト名は存在しません。

1. HTTP Basic認証（username:password）を使用した GET https://login.thrio.com/provider/token-with-authorities → {"location": "https://<tenant-cluster>.thrio.io", "token": "..."}。

2. 実際のデータ/アナリティクス呼び出しはすべて {location}（login.thrio.com ではなく）に対して行われ、トークンは Authorization ヘッダーにそのまま送信されます — Bearer プレフィックスは付けません。

保持するセッションがないため、このサーバーはツール呼び出しのたびに毎回新しく再認証します。MCPリクエスト間でキャッシュや永続化は一切行われません。

HEADER 認証パラメータの説明

どちらかのヘッダーが欠けている場合は 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トランスポート）

• GET /health — ヘルスチェック。{"status": "ok"} を返します（純粋なローカルプローブで、Nextiva/Thrio APIは呼び出しません）

ツール一覧

5つのツールはすべて読み取り専用です（readOnlyHint=True、idempotentHint=True）。書き込み/削除ツールはありません。

パラメータごとのドキュメントは、各ツールのパラメータスキーマ（tools/list で確認可能）にあり、このテーブルにはありません。このテーブルはクイックリファレンスのみで、ここでのパラメータ名はコードと同期されています。

成功レスポンスはベンダーのJSONをコンパクトにシリアライズしたものです（プリティプリントなし、ensure_ascii=False）。約20,000文字で上限が設定され、サイズ超過のリストレスポンスは完全な形ではなく truncated/original_count マーカー付きで切り詰められます。これらのエンドポイントには、ベンダーが文書化した limit/ページサイズパラメータはありません（ページングは start オフセットのみ。下記の既知のギャップを参照）。そのため、この自動的な文字数上限以外に制限するものはありません。

エラーは例外/HTTPエラーではなく、JSONエラーエンベロープとして返されます。例：

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

code は not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error のいずれかで、Thrio APIのHTTPステータスコードからマッピングされます（api_client.py の error_envelope/NextivaError.to_envelope を参照）。送信呼び出しは5秒の接続タイムアウト/30秒の読み取りタイムアウトを使用し、429/5xxレスポンスでは上限付き指数バックオフで最大3回再試行します（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": {}
    }
  }'

ライブ検証済み（2026-07-30）：実際のNextiva/Thrioテナントに対して、5つのツールすべてをこの実行中サーバーを通じてエンドツーエンドで呼び出しました。nextiva_get_users は101人の実ユーザーを返し、nextiva_get_campaigns は9つの実キャンペーン（例：「Nextiva - Transfers」）を返し、nextiva_get_contacts は99件の実コンタクトを返し、nextiva_get_queues は18の実キューを返し、nextiva_get_workitems_history は実際の集計値（例：直近7日間でインバウンド297件、アウトバウンド195件、コンタクト500件）を返しました。すべてログインステップでテナントの実際のクラスタホスト（https://mancity.thrio.io）が動的に解決されました。

APIリファレンス

• 公開、ログイン不要：https://api.thrio.com/（認証、オブジェクト/データAPI、アナリティクスなどをカバーするPostman生成ドキュメント）

既知のギャップ

• スコープはMSPbotsが設定した5つのエンドポイントのみで、ベンダーの全APIサーフェスではありません — ThrioのAPIは、ワークアイテムアクション、リスト管理、ダッシュボード、録音、コンタクト同意、ステートDID、チャット、CRM、クライアント、番号検証、WFM、TEAMS、コールバックなどもカバーしています（公開ドキュメントのナビゲーションによる）。これらはここではスコープ外です。

• ページングは start オフセットであり、経験的に確認済みです（start=1 を渡すと結果ウィンドウが1つずれ、レスポンスの previous フィールドもそれに応じて更新されました）。ベンダーの公開ドキュメントは、リクエスト/レスポンスの形状が実際に示すほど明示的にこれを説明していないため、ドキュメントだけから推測するのではなく、ライブAPIに対して検証しました。

• ベンダーのドキュメントに記載されている session/login ステップ（POST {location}/users/api/login）は、このサーバーでは使用されません — これは、完全なインタラクティブエージェントセッション（例：テレフォニー/ACD状態）を作成する場合にのみ必要と思われ、MSPbotsが使用する読み取り専用のデータ/アナリティクスエンドポイントには不要でした。認証トークンのみで正しく動作しました。このステップなしで5つのエンドポイントすべてを正常に呼び出して確認済みです。