Wixzel Voice

wixzel-voice-mcp

AI エージェント向け Wixzel Voice。 Model Context Protocol サーバーです。Claude Code、claude.ai、Claude Desktop、Cursor、その他あらゆる MCP クライアントから、Wixzel Voice API を使って音声エージェントの作成、通信事業者への接続、通話の発信、キャンペーンの実行、費用の確認ができます。

Wixzel Voice：AI 音声エージェント向け API。API キー 1 つ、残高 1 つ、すべての音声エンジンに対応。

API 操作ごとに 1 つのツールがあり、全部で 56 個です。それぞれに注釈が付いており、クライアントは読み取り専用か、削除を行うか、料金が発生する、または実際に電話を鳴らすものかを判断できます。一般的なワークフローをまとめた 3 つのプロンプト（quickstart、diagnose_call、spend_report）も用意されています。

0.3.0 までは wixzel-phone-mcp として公開されており、その間、製品名は一時的に Wixzel Phone でした。これらのリリースも引き続き動作します。api.phone.wixzel.com と mcp.phone.wixzel.com は引き続きサービスを提供しています。

実行方法は 2 通りあります。

	場所	認証
ホスト型、https://mcp.voice.wixzel.com/mcp	Wixzel のサーバー	クライアントからの OAuth サインイン、またはベアラーキー
ローカル、npx -y wixzel-voice-mcp	お使いのマシン、stdio	環境変数の WIXZEL_API_KEY

コンソールの AI クライアント ページ（voice.wixzel.com/connect）では、以下の各コマンドにキーを入力した状態で生成できます。

Claude Code

# hosted: sign in with your Wixzel account when Claude Code asks (/mcp → Authenticate)
claude mcp add --transport http wixzel-voice https://mcp.voice.wixzel.com/mcp

# local: a scoped key from the console
claude mcp add wixzel-voice -e WIXZEL_API_KEY=wv_live_... -- npx -y wixzel-voice-mcp

または .mcp.json をコミットすると、すべての共同作業者が利用できます。

{
  "mcpServers": {
    "wixzel-voice": {
      "command": "npx",
      "args": ["-y", "wixzel-voice-mcp"],
      "env": { "WIXZEL_API_KEY": "${WIXZEL_API_KEY}" }
    }
  }
}

次に、以下を実行します。

/mcp__wixzel-voice__quickstart

claude.ai と Claude Desktop

Settings → Connectors → Add custom connector → https://mcp.voice.wixzel.com/mcp → Connect の順に進みます。コンソールにサインインして、クライアントに許可する操作を選択すると、専用のスコープ付きキーが発行されます。コンソールの AI クライアントページから、いつでも接続を解除できます。

Cursor、Windsurf、VS Code など

上記の .mcp.json と同じ形式です。コマンドは npx、引数は ["-y", "wixzel-voice-mcp"]、環境変数は WIXZEL_API_KEY です。HTTP 接続には対応していても OAuth に対応していないクライアントは、キーを Authorization: Bearer wv_live_... として送信します。

エージェントにできること

分類	ツール
エンジン	list_engines
エージェント	list_agents get_agent create_agent update_agent delete_agent
通話	place_call list_calls get_call get_call_transcript hangup_call delete_call
発信者	list_callers get_caller update_caller
ミーティング	connect_meeting_integration get_meeting_integration delete_meeting_integration join_meeting list_meetings get_meeting leave_meeting
SIP トランク	list_sip_trunks get_sip_trunk create_sip_trunk update_sip_trunk delete_sip_trunk check_sip_trunk_status test_sip_trunk get_sip_trunk_logs
電話番号	list_phone_numbers get_phone_number create_phone_number update_phone_number delete_phone_number
見込み客	list_leads get_lead create_lead update_lead delete_lead import_leads
キャンペーン	list_campaigns get_campaign create_campaign start_campaign pause_campaign delete_campaign
ナレッジベース	list_knowledge_bases get_knowledge_base create_knowledge_base import_knowledge_base import_knowledge_file update_knowledge_base delete_knowledge_base list_knowledge_files add_knowledge_file get_knowledge_file delete_knowledge_file
MCP サーバー	list_mcp_servers get_mcp_server create_mcp_server update_mcp_server delete_mcp_server refresh_mcp_server connect_mcp_server_oauth
ツール	list_tools get_tool create_tool update_tool delete_tool test_tool
音声	list_voices get_voice preview_voice create_voice_clone update_voice delete_voice
予約	list_appointments get_appointment create_appointment update_appointment delete_appointment
請求と使用量	get_balance list_ledger_entries create_topup get_usage_summary list_usage_events
API キー	list_api_keys create_api_key rotate_api_key revoke_api_key

プロンプト：quickstart（通信事業者への接続、番号の登録、エージェントの作成、最初の通話の発信）、diagnose_call（通話 X が失敗した理由）、spend_report（今月の費用とその内訳）。

リソース：wixzel://guide（サーバーが指示としても送信する運用ガイド）と、wixzel://connection（ベース URL とキーがライブかテストかを示す情報。キー自体は含まれません）。

エージェントが誤りを起こさないための仕組み

• 費用が発生する操作を明示します。 place_call、start_campaign、create_topup、create_voice_clone には openWorldHint: true の注釈が付いており、その説明では事前にユーザーの確認を求めるようモデルに指示しています。注釈に基づいて制御するクライアントでは、実行前に確認を求めます。
• 冪等性を自動で確保します。 費用が発生する 2 つの処理には Idempotency-Key が必要です。サーバーは呼び出しごとにキーを生成し、意図的な再試行用に明示的な idempotency_key も受け付けるため、ネットワークのタイムアウトによって通話が 2 回行われることはありません。
• エラーに対処方法を示します。 すべての失敗で、API の機械可読な code、request_id、および対処方法を示すヒントが返されます。不足しているスコープや残高不足、カーソルの破損などを確認できます。
• レート制限の影響を吸収します。 429 は、モデルに返される前に Retry-After に従って最大 2 回再試行されます。これらのリクエストに料金はかかりません。
• スコープでアクセスを制御します。 利用できる機能はキーによって決まります。admin スコープはなく、キーから、そのキーよりも広い権限を持つキーを作成することはできません。
• シークレットを保護します。 SIP パスワードは書き込み専用です。API キーのシークレットが表示されるのはツールの結果内の 1 回だけで、それ以外の場所には表示されません。このサーバーが使用するキーは、どのツールやリソースからも公開されません。

ホストモードを自分で実行する

npx wixzel-voice-mcp --http 3939

変数	用途
MCP_PORT	ポートです。デフォルトは3939です。--http <port> で上書きできます。
MCP_BIND	インターフェースです。デフォルトは 127.0.0.1 です。より広い範囲にバインドするのではなく、前段で TLS を終端してください。
MCP_PUBLIC_URL	クライアントが使用する URL です。例：https://mcp.voice.wixzel.com/mcp。OAuth リソースとして通知されます。
WIXZEL_API_BASE_URL	API です。OAuth 認可サーバーも兼ねています。デフォルトは https://api.voice.wixzel.com です。
WIXZEL_API_VERSION	任意の Wixzel-Version 日付指定です。
WIXZEL_API_KEY	Stdio モードでは API キーです。HTTP モードでは、Bearer がないリクエストに対するフォールバックとして使用されます。ただし、MCP_PUBLIC_URL がループバックアドレスの場合に限り受け付けられます。

各リクエストの Bearer は、そのリクエスト専用の使い捨て MCP サーバーの API キーになります。リクエスト間で共有されるものはありません。Bearer のないリクエストには WWW-Authenticate: Bearer resource_metadata="…" を含む 401 が返され、/.well-known/oauth-protected-resource は API を認可サーバーとして示します。これにより、コネクターは独自にサインイン方法を検出できます。GET /healthz は稼働状態を報告します。

開発

ソースは wixzel-voice-sdks にミラーされています。API も含むプライベートモノレポで開発されているため、エンドポイントの変更とそのツールの変更を同時に反映できます。

npm install                # at the repo root
npm test -w apps/mcp       # offline: a fake API behind in-memory and HTTP transports, plus a spec-coverage check
npm run build -w apps/mcp
npm run inspect -w apps/mcp   # MCP Inspector against the built server

ツールのスキーマは zod で手書きされています。仕様カバレッジテストでは、API の OpenAPI ドキュメント（docs/openapi.json）と双方向に比較します。そのため、API にエンドポイントが追加されると、ここで対応するツールが追加されるまでビルドに失敗します。

アプリケーションコード向けではありません

このサーバーは AI エージェント向けです。アプリケーションコードでは、SDK を使用してください。 npm の wixzel-voice と pub.dev の wixzel_voice を利用できます。

ライセンス

MIT。Wixzel Voice 自体はホスト型サービスです。利用規約については voice.wixzel.com をご覧ください。