Stexa Voice Mcp

Stexa Voice MCP — 使用例とクイックスタート

MCP ツールとしての音声通話機能。 AI エージェントが、実際に電話をかけ、文字起こしを取得し、通話状況を確認できるようにします。すべて Model Context Protocol 経由で行えます。

stexa_call_outbound("+79991234567")  →  AI bot dials, speaks, records
stexa_get_transcript("oc:42")        →  [{"role": "bot", "text": "..."}, ...]

→ 英語ドキュメント · API キーを取得 · ライブデモ

---

このリポジトリの内容

パス	説明
examples/claude-desktop/	Claude Desktop 用の設定スニペット
examples/cursor/	Cursor の .cursor/mcp.json 設定
examples/python/	Python と httpx による直接 HTTP 呼び出し
examples/n8n/	すぐにインポートできる n8n ワークフロー

---

クイックスタート（5 分）

ステップ 1 — API キーを取得する

1. stexa.ru で登録します
2. Cabinet → MCP Server → + Create key を開きます
3. キーをコピーします（形式：stx_live_...）

OAuth 2.1 にも対応しており、本番環境での使用を推奨します。以下のOAuth の設定を参照してください。

---

ステップ 2 — MCP クライアントを接続する

Claude Desktop

設定ファイルに追加します：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stexa-voice": {
      "url": "https://stexa.ru/mcp/v1/jsonrpc",
      "headers": {
        "Authorization": "Bearer stx_live_YOUR_KEY"
      }
    }
  }
}

Claude Desktop を再起動すると、Stexa のツールがツール選択メニューに自動的に表示されます。

OAuth を使用する場合（静的キーは不要）：

{
  "mcpServers": {
    "stexa-voice": {
      "url": "https://stexa.ru/mcp/v1/jsonrpc",
      "auth": "oauth2"
    }
  }
}

初回使用時に Claude Desktop がブラウザーウィンドウを開き、OAuth の同意フローを開始します。

---

Cursor

プロジェクトのルートにある .cursor/mcp.json（またはグローバル設定の ~/.cursor/mcp.json）を作成または編集します：

{
  "mcpServers": {
    "stexa-voice": {
      "url": "https://stexa.ru/mcp/v1/jsonrpc",
      "headers": {
        "Authorization": "Bearer stx_live_YOUR_KEY"
      }
    }
  }
}

---

Python

pip install httpx

from examples.python.connect_and_call import StexaMCPClient

client = StexaMCPClient(api_key="stx_live_YOUR_KEY")

# Async call — returns immediately, poll for status
result = client.call_outbound("+79991234567")
call_id = result["call_id"]   # "oc:42"

# Or synchronous call — blocks up to 90s, returns transcript
result = client.call_outbound("+79991234567", wait=True)
print(result["transcript"])

完全な例： examples/python/connect_and_call.py

---

n8n

1. n8n のインスタンスを開きます
2. Workflows → Import from file に移動します
3. examples/n8n/stexa_voice_workflow.json をアップロードします
4. HTTP Request ノードのヘッダーに API キーを設定します
5. ワークフローを有効化し、Webhook トリガーでテストします

---

ツールリファレンス

stexa_call_outbound

音声で発信します。AI ボット（Alina）が番号に電話をかけ、会話を行います。

必要なスコープ： call:write

引数	型	必須	説明
phone	string	✅	E.164 形式の電話番号（+79991234567）
scenario_id	string	—	カスタムシナリオ ID（デフォルト：テナントのデフォルト）
vars	object	—	テンプレート置換用の変数 {{name}}、{{date}}
wait_for_completion	boolean	—	最大 90 秒待機し、文字起こし全文を返します（デフォルト：false）
max_duration_s	integer	—	通話の最大時間（秒）、30～600（デフォルト：300）

レスポンス（非同期）：

{
  "call_id": "oc:42",
  "status": "queued",
  "estimated_start_in_s": 5
}

レスポンス（wait_for_completion=true）：

{
  "call_id": "oc:42",
  "status": "completed",
  "duration_s": 87,
  "transcript": [
    {"role": "bot", "text": "Hello, this is Alina from Stexa. May I speak with..."},
    {"role": "client", "text": "Yes, speaking."}
  ],
  "summary": "Client confirmed the appointment for Tuesday at 3 PM."
}

---

stexa_get_call_status

stexa_call_outbound で開始した通話の現在の状況を確認します。

必要なスコープ： call:read

引数	型	必須	説明
call_id	string	✅	stexa_call_outbound の戻り値（形式：oc:N）

ステータスの推移：

queued → ringing → talking → completed
                            → failed (no_answer / busy / error)

レスポンス：

{
  "call_id": "oc:42",
  "status": "talking",
  "phone": "+7953****5875",
  "started_at": "2026-05-25T10:30:00+00:00",
  "duration_s": 34
}

---

stexa_get_transcript

完了済み（または進行中）の通話の会話記録を取得します。

必要なスコープ： transcript:read

引数	型	必須	説明
call_id	string	✅	stexa_call_outbound の戻り値
include_summary	boolean	—	AI 生成の要約を含めます（デフォルト：true）

レスポンス：

{
  "call_id": "oc:42",
  "status": "completed",
  "duration_s": 87,
  "transcript": [
    {"role": "bot", "text": "Hello, this is Alina..."},
    {"role": "client", "text": "Yes, I remember. Tuesday at 3 PM works."}
  ],
  "summary": "Client confirmed appointment, expressed satisfaction."
}

通話がまだ進行中の場合は、partial_transcript とともに status: "in_progress" を返します。

---

stexa_list_recent_calls

フィルターを指定して最近の通話を一覧表示します。新しい通話を発信する前に、「このクライアントに以前発信したことがあるか」を確認する場合に便利です。

必要なスコープ： call:read

引数	型	説明
phone	string	電話番号で絞り込みます
since	string	ISO-8601 タイムスタンプ（デフォルト：7日前）
limit	integer	結果の件数、1～100（デフォルト：20）
origin	string	all / mcp / manual / scheduled

---

OAuth 2.1 の設定

静的 API キーを埋め込めない本番環境の連携の場合：

エンドポイント	URL
認可サーバーのメタデータ	https://stexa.ru/.well-known/oauth-authorization-server
保護されたリソースのメタデータ	https://stexa.ru/.well-known/oauth-protected-resource
動的クライアント登録	https://stexa.ru/mcp/v1/oauth/register

サポートされているフロー：

• Authorization Code + PKCE（RFC 7636）— ユーザー向けアプリ用
• 動的クライアント登録（RFC 7591）— エージェントの自動登録用

クライアントの登録：

curl -X POST https://stexa.ru/mcp/v1/oauth/register \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "My AI Agent",
    "redirect_uris": ["https://my-agent.example.com/callback"],
    "scope": "call:write call:read transcript:read"
  }'

Authorization Code フローで使用する client_id と client_secret が返されます。

---

認証スコープ

スコープ	アクセス権
call:write	stexa_call_outbound
call:read	stexa_get_call_status, stexa_list_recent_calls
transcript:read	stexa_get_transcript

Cabinet で作成した API キーには、デフォルトで3つすべてのスコープが含まれます。

---

レート制限

レベル	上限
IP ごと（全体）	60 リクエスト / 分
API キーごと（全体）	120 リクエスト / 分
API キーごとの stexa_call_outbound	10 通話 / 分

---

サーバー情報

Endpoint:         POST https://stexa.ru/mcp/v1/jsonrpc
Health:           GET  https://stexa.ru/mcp/v1/health
Protocol version: 2024-11-05
Transport:        HTTP (JSON-RPC 2.0)
Discovery:        GET  https://stexa.ru/mcp/v1/jsonrpc (tools/list, no auth)

---

ユースケース

• AI が起点となる発信キャンペーン — CRM イベントが発生すると、エージェントが通話を発信します
• 予約リマインダー — Claude が訪問の24時間前にクライアントへ音声でリマインドします
• 通話後のフィードバック — サービス後に音声通話で NPS を収集します
• CRM への通話記録 — 実際の会話内容でリード情報を充実させます
• 美容サロン／クリニック／自動車サービスの予約 — 音声ボットが予約を処理します

---

リンク

• ドキュメント（英語）
• ドキュメント（ロシア語）
• Cabinet — API キーを作成
• ライブデモ
• サポート

---

ライセンス

Stexa Voice MCP はプロプライエタリなクラウドサービスです（利用規約 · プライバシー）。 このリポジトリのサンプルコードは MIT License の下で利用できます。