Stexa Voice Mcp

Stexa Voice MCP — 示例与快速入门

语音电话作为 MCP 工具。 让你的 AI Agent 能够拨打真实的外呼电话、获取转录文本并查询通话状态——全部通过 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	字符串	✅	E.164 格式的电话号码（+79991234567）
scenario_id	字符串	—	自定义场景 ID（默认：租户默认场景）
vars	对象	—	用于模板替换的变量 {{name}}、{{date}}
wait_for_completion	布尔值	—	最长等待 90 秒并返回完整转录文本（默认：false）
max_duration_s	整数	—	通话最长时长，单位为秒，范围为 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	字符串	✅	来自 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	字符串	✅	来自 stexa_call_outbound
include_summary	布尔值	—	是否包含 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."
}

如果通话仍在进行中，则返回 status: "in_progress" 和 partial_transcript。

---

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) — 适用于自动化 Agent 注册

注册客户端：

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

在控制台中创建的 API 密钥默认包含以上三个权限范围。

---

速率限制

级别	限制
每个 IP（全局）	60 次请求 / 分钟
每个 API 密钥（全局）	120 次请求 / 分钟
每个密钥的 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 事件发生时由 Agent 发起通话
• 预约提醒 — Claude 在就诊前 24 小时通过语音提醒客户
• 通话后反馈 — 服务结束后通过语音通话收集 NPS
• CRM 中的通话转录文本 — 使用真实对话丰富潜在客户记录
• 美容院 / 诊所 / 汽车服务预约 — 语音机器人处理预约安排

---

链接

• 文档（英文）
• 文档（俄文）
• 控制台 — 创建 API 密钥
• 在线演示
• 支持

---

许可证

Stexa Voice MCP 是专有云服务（条款 · 隐私政策）。 此仓库中的示例代码遵循 MIT License。