oitvoip-mcp

Oitvoip（ホスティング型 VoIP/UCaaS リセラープラットフォーム、NetSapiens 上に構築 — API ホストパターンは {tenant-pbx-host}/ns-api/）向けの MCP サーバー。NetSapiens ns-api のドメイン、リセラー、デバイス、サブスクライバー、CDR メソッドを MCP ツールとして公開します。

命名についての注記: MSPbots 自身の統合は "Oitvoip" として登録されています（subjectCode=NS — NetSapiens の略称）。基盤となる API と公式ドキュメントはすべて "NetSapiens" / "ns-api" を参照しています。この MCP は、MSPbots 自体が設定したまさにその 5 つのメソッドをカバーします。

概要

• ステートレスな HTTP サービス。認証情報は一切永続化されません。各リクエストはヘッダー経由で自身の認証情報を提供し、その単一リクエストの存続期間中のみ使用されます。

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

• エントリポイント: POST /mcp（MCP プロトコル）および GET /health（ヘルスチェック）。

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

Related MCP server: whmcs-mcp-server

認証

NetSapiens は標準の OAuth2 パスワードグラント を使用します:

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

結果の access_token の有効期限は 1 時間ですが、このサーバーは MCP リクエスト間でキャッシュするのではなく、ツール呼び出しのたびに毎回新しく再認証します。キャッシュや永続化は一切行われません。実際の ns-api 呼び出しはすべて Authorization: Bearer <access_token> を送信します。

ヘッダー認証パラメータの説明

ヘッダーが 1 つでも欠けていると 401 を返します:

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

無効な認証情報、または認証済みだが権限スコープが不足しているサブスクライバーアカウントは、このサーバーからの HTTP レベルのエラーではなく、ツールレベルの unauthorized エラーエンベロープとして表面化します（メッセージにはベンダー自身の詳細、例: Invalid Scope [APP001] が含まれます）— 既知の制限事項を参照してください。

環境変数

MCP エンドポイント

• POST /mcp — MCP プロトコル（ストリーミング可能な HTTP トランスポート）

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

ツール一覧

レスポンスはベンダーの JSON（メソッドに応じて配列またはオブジェクト）で、コンパクトにシリアライズされます（インデントなし、ensure_ascii=False）。レスポンスが約 20,000 文字を超える場合は、最大のリストフィールドが切り詰められ、結果には truncated: true と元の件数が含まれます。無制限のブロブを返すことはありません。5 つのツールはすべて読み取り専用（readOnlyHint）です。このサービスに書き込み/削除ツールはありません。

エラー時、ツールは例外を発生させる代わりに構造化された JSON エラーエンベロープを返します:

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

code は not_configured / unauthorized / not_found / invalid_argument / rate_limited / upstream_error のいずれかです。retryable はエージェントが安全に再試行できるかどうかを示します（rate_limited と upstream_error では true）。

テスト例

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

ライブ検証済み（2026-07-30）: 実際のテナントに対して、この稼働中のサーバーを介して 5 つのツールすべてをエンドツーエンドで呼び出しました。oitvoip_get_subscribers は実際のサブスクライバー/内線レコードを返し、oitvoip_get_devices は実際に登録された SIP デバイス（Polycom エンドポイント、ライブ登録状態）を返し、oitvoip_get_cdr2 は指定された日付範囲の実際の通話詳細記録を返しました。oitvoip_get_domains と oitvoip_get_resellers は API に正しく到達し、クリーンで期待どおりの 401 Invalid Scope [APP001] ツールレベルのエラーを表面化しました。提供されたテスト認証情報はサブスクライバーレベルのアカウント（scope: "Office Manager"）であり、この特定の NetSapiens デプロイメントではドメイン/リセラーの管理権限を持ちません。既知の制限事項を参照してください。

API リファレンス

• 公開、ログイン不要: https://api.ucaasnetwork.com/ns-api/apidoc/（OAuth2、Domain、Reseller、Device、Subscriber、CDR オブジェクトを含む完全な ns-api リファレンス）

既知の制限事項

• スコープは MSPbots が設定した 5 つのエンドポイントのみであり、ベンダーの完全な API サーフェスではない — ns-api は Callqueue、Agent、Phonenumber、Dialplan、Contacts、Presence、Call Queue Report/Stat、リアルタイム Call 制御などもカバーしています（公開ドキュメント自身のオブジェクトリストによる）。これらはここではスコープ外です。

• oitvoip_get_domains と oitvoip_get_resellers は実データで完全にはライブ検証できなかった — 提供されたテストアカウントは認証に成功します（OAuth2 フローとこの実装が正しいことを証明します）が、サブスクライバーレベルの "Office Manager" ロールにスコープされており、NetSapiens はこれら 2 つの管理レベルオブジェクトに対して 401 Invalid Scope [APP001] で拒否します。これは特定のテストアカウントの認証情報権限の制限であり、このサーバーのバグではありません。oitvoip_get_subscribers、oitvoip_get_devices、oitvoip_get_cdr2 は、まったく同じログインからのまったく同じアクセストークンを使用して、実データで成功しました。

• CDR の日付範囲フィールド（start_date/end_date）は未検証の文字列 — YYYY-MM-DD HH:MM:SS 形式のままベンダーにそのまま渡され、MSPbots 自身の保存済み使用法と一致します。クライアント側での日付解析は実行されません。