Stexa Voice Mcp

Stexa Voice MCP — Examples & Quickstart

Voice telephony as an MCP tool. Give your AI agent the ability to make real outbound phone calls, get transcripts, and check call status — all via the Model Context Protocol.

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

→ EN Docs · Get API Key · Live demo

---

What's in this repo

Path	Description
examples/claude-desktop/	Config snippet for Claude Desktop
examples/cursor/	Cursor .cursor/mcp.json settings
examples/python/	Direct HTTP calls via Python + httpx
examples/n8n/	Ready-to-import n8n workflow

---

Quick start (5 minutes)

Step 1 — Get an API key

1. Register at stexa.ru
2. Open Cabinet → MCP Server → + Create key
3. Copy the key (format: stx_live_...)

OAuth 2.1 is also supported and recommended for production. See OAuth setup below.

---

Step 2 — Connect your MCP client

Claude Desktop

Add to your config file:

• 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"
      }
    }
  }
}

Restart Claude Desktop — Stexa tools appear in the tool picker automatically.

For OAuth (no static key needed):

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

Claude Desktop opens a browser window for the OAuth consent flow on first use.

---

Cursor

Create or edit .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "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"])

Full example: examples/python/connect_and_call.py

---

n8n

1. Open your n8n instance
2. Go to Workflows → Import from file
3. Upload examples/n8n/stexa_voice_workflow.json
4. Set your API key in the HTTP Request node headers
5. Activate and test via the Webhook trigger

---

Tools reference

stexa_call_outbound

Make an outbound voice call. The AI bot (Alina) dials the number and conducts a conversation.

Scope required: call:write

Argument	Type	Required	Description
phone	string	✅	Phone in E.164 format (+79991234567)
scenario_id	string	—	Custom scenario ID (default: tenant default)
vars	object	—	Variables for template substitution {{name}}, {{date}}
wait_for_completion	boolean	—	Block up to 90s, return full transcript (default: false)
max_duration_s	integer	—	Max call length in seconds, 30–600 (default: 300)

Response (async):

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

Response (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

Check the current status of a call initiated via stexa_call_outbound.

Scope required: call:read

Argument	Type	Required	Description
call_id	string	✅	From stexa_call_outbound (format oc:N)

Status lifecycle:

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

Response:

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

---

stexa_get_transcript

Get the conversation transcript of a completed (or in-progress) call.

Scope required: transcript:read

Argument	Type	Required	Description
call_id	string	✅	From stexa_call_outbound
include_summary	boolean	—	Include AI-generated summary (default: true)

Response:

{
  "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."
}

If the call is still in progress, returns status: "in_progress" with partial_transcript.

---

stexa_list_recent_calls

List recent calls with filters. Useful for context before making a new call ("has this client been called before?").

Scope required: call:read

Argument	Type	Description
phone	string	Filter by phone number
since	string	ISO-8601 timestamp (default: 7 days ago)
limit	integer	Number of results, 1–100 (default: 20)
origin	string	all / mcp / manual / scheduled

---

OAuth 2.1 setup

For production integrations where embedding a static API key is not acceptable:

Endpoint	URL
Authorization server metadata	https://stexa.ru/.well-known/oauth-authorization-server
Protected resource metadata	https://stexa.ru/.well-known/oauth-protected-resource
Dynamic client registration	https://stexa.ru/mcp/v1/oauth/register

Supported flows:

• Authorization Code + PKCE (RFC 7636) — for user-facing apps
• Dynamic Client Registration (RFC 7591) — for automated agent registration

Register a client:

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

Returns client_id and client_secret for the Authorization Code flow.

---

Authentication scopes

Scope	Grants access to
call:write	stexa_call_outbound
call:read	stexa_get_call_status, stexa_list_recent_calls
transcript:read	stexa_get_transcript

API keys created in the Cabinet include all three scopes by default.

---

Rate limits

Level	Limit
Per IP (global)	60 requests / minute
Per API key (global)	120 requests / minute
stexa_call_outbound per key	10 calls / minute

---

Server info

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)

---

Use cases

• AI-triggered outbound campaigns — agent fires calls when a CRM event occurs
• Appointment reminders — Claude reminds clients 24h before a visit (voice)
• Post-call feedback — collect NPS via a voice call after service
• Call transcripts in CRM — enrich lead records with real dialogue
• Beauty salon / clinic / auto-service booking — voice bot handles scheduling

---

Links

• Documentation (EN)
• Документация (RU)
• Cabinet — create API key
• Live demo
• Support

---

License

Stexa Voice MCP is a proprietary cloud service (terms · privacy). The example code in this repository is available under the MIT License.