# Stexa Voice MCP — Examples & Quickstart

[![Status](https://img.shields.io/badge/Status-Stable-green)](https://stexa.ru/mcp/v1/health)
[![Protocol](https://img.shields.io/badge/MCP-2024--11--05-blue)](https://spec.modelcontextprotocol.io)
[![Auth](https://img.shields.io/badge/Auth-OAuth%202.1-orange)](https://stexa.ru/.well-known/oauth-authorization-server)

**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](https://stexa.ru/en/voice-mcp) · [Get API Key](https://stexa.ru/cabinet/mcp-server) · [Live demo](https://stexa.ru/demo)

---

## What's in this repo

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

---

## Quick start (5 minutes)

### Step 1 — Get an API key

1. Register at [stexa.ru](https://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](#oauth-21-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`

```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):
```json
{
  "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):

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

---

#### Python

```bash
pip install httpx
```

```python
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`](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`](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):**
```json
{
  "call_id": "oc:42",
  "status": "queued",
  "estimated_start_in_s": 5
}
```

**Response (wait_for_completion=true):**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```bash
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)](https://stexa.ru/en/voice-mcp)
- [Документация (RU)](https://stexa.ru/voice-mcp)
- [Cabinet — create API key](https://stexa.ru/cabinet/mcp-server)
- [Live demo](https://stexa.ru/demo)
- [Support](mailto:support@stexa.ru)

---

## License

Stexa Voice MCP is a proprietary cloud service ([terms](https://stexa.ru/policy/terms) · [privacy](https://stexa.ru/policy/privacy)).
The example code in this repository is available under the **MIT License**.