> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ouraicalling.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP endpoint

> Connect Claude, ChatGPT, or any MCP client to your account

The platform ships a built-in **MCP server** (Model Context Protocol, streamable HTTP). Connect an AI application — Claude, ChatGPT, Cursor, or your own agent — and it can manage assistants, start calls, read transcripts, and maintain campaigns on your behalf.

```text theme={null}
https://app.famulor.io/mcp
```

On a white-label domain, the endpoint, login, and consent screens all run under the tenant's branding. Access requires the **Connect AI / MCP** feature in your plan (`connect_ai_mcp`) — otherwise the endpoint answers `403`.

## Connecting clients

<Tabs>
  <Tab title="Claude">
    1. **Settings → Connectors → Add custom connector**
    2. Enter `https://app.famulor.io/mcp`
    3. Claude starts the OAuth flow automatically: sign in on your platform's login page and approve the consent screen.
    4. The tools appear in Claude.
  </Tab>

  <Tab title="ChatGPT">
    1. **Settings → Connectors → Create** (custom connector)
    2. MCP Server URL: `https://app.famulor.io/mcp`, Authentication: **OAuth**
    3. Sign in and approve — the tools are then available in ChatGPT.
  </Tab>

  <Tab title="Other clients">
    ```json theme={null}
    {
      "mcpServers": {
        "voice-ai": {
          "command": "npx",
          "args": ["mcp-remote", "https://app.famulor.io/mcp"]
        }
      }
    }
    ```

    Alternatively, skip OAuth and authenticate with an **API key** (`fam_...`, created under Settings) as a static Bearer token: `Authorization: Bearer fam_...`
  </Tab>
</Tabs>

### Connect from the dashboard

The fastest way to connect is the built-in **Connect AI** modal: open the **Tools** page of the dashboard and click **Use in ChatGPT & Claude**. The modal shows your account's MCP URL (your white-label domain if one is configured and verified), lets you copy it with one click, and offers ready-made starter prompts — build an assistant, fix an assistant, analyze the last call, mine the last 30 calls, or launch a campaign. **Open in Claude** / **Open in ChatGPT** hands the selected prompt straight to the AI app; you only complete the sign-in and consent step there.

## Authentication

The endpoint implements the full modern MCP auth stack — clients handle it automatically:

1. An unauthenticated request returns `401` with protected-resource metadata (RFC 9728).
2. The client discovers the authorization server (RFC 8414), registers itself via Dynamic Client Registration (RFC 7591), and runs **Authorization Code + PKCE**.
3. You sign in (white-label login) and approve the consent screen — once per application; the approval is remembered for 180 days.
4. The client receives an access token (`fam_at_...`, 1 h, with refresh token) and calls the endpoint.

## Available tools

Every operation of the [REST API v1](/api-reference/introduction) is also available as an MCP tool — same services, same validation (plan limits, model catalog, DNC list).

| Tool                                    | Scope              | Description                                                                                                                                                                                                                                            |
| --------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list_assistants` / `get_assistant`     | `assistants:read`  | List assistants / fetch one configuration                                                                                                                                                                                                              |
| `get_assistant_compliance_review`       | `assistants:read`  | Read the current compliance status, score, flags, reason and manual-review state                                                                                                                                                                       |
| `request_assistant_compliance_review`   | `assistants:write` | Submit the current blocked assistant snapshot for manual review with a reason                                                                                                                                                                          |
| `create_assistant` / `update_assistant` | `assistants:write` | Create / modify assistants (updates are auto-versioned). Default create is **Single prompt** (`flow_json` null). Pass `flow_json` for **Conversational flow**. Use `list_prompt_templates` then `system_prompt` / `first_message` to apply a template. |

In-app **[Milian Copilot](/assistants/milian-copilot)** uses the same services via your login session (`/api/milian/*`) — not this MCP endpoint.
\| `delete_assistant` | `assistants:write` | Permanently delete an assistant |
\| `list_tools` / `get_tool` | `assistants:read` | List reusable tools (HTTP API tools + external MCP servers) / fetch one (secrets masked as `•••`) |
\| `create_tool` / `update_tool` / `delete_tool` | `assistants:write` | Manage reusable tools (`type` `api`, `mcp`, or `builtin` — the latter wraps a [built-in tool](/assistants/built-in-tools) as a workspace tool; create/update require an admin credential because configs contain secrets) |
\| `get_assistant_tools` / `set_assistant_tools` | `assistants:read` / `assistants:write` | Read / REPLACE an assistant's tool assignments |
\| `get_voices` | `voices:read` or `assistants:read` | Browse the TTS voice library (provider, language, gender, accent, search) |
\| `get_models` | `assistants:read` | Browse the model catalog (`type` = `llm`, `stt`, `tts`, or `realtime`) — the models available for assistant configuration |
\| `get_languages` | `assistants:read` | List the supported assistant languages (ISO 639-1 codes + labels) for `primary_language` / `secondary_languages` |
\| `list_calls` / `get_call` | `calls:read` | Browse calls; `get_call` includes transcript, summary, and a temporary `recording_url` |
\| `list_history` / `get_email_history_item` | `calls:read` | Browse calls and grouped email conversations; every customer/assistant turn with the same stable thread ID forms one row and can be fetched chronologically |
\| `make_call` | `calls:write` | Start an outbound call (`assistant_id`, `to_number`, optional lead) |
\| `live_call_control` | `calls:write` | Active-call control: `listen_token`, `whisper`, `end_agent`, or `hangup` (requires plan feature `live_monitoring`) |
\| `list_campaigns` / `get_campaign` | `campaigns:read` or `calls:read` | Browse campaigns incl. dialer settings and lead counts |
\| `create_campaign` / `update_campaign` / `delete_campaign` | `campaigns:write` or `calls:write` | Manage campaigns (concurrency, retries, calling windows, and retry policies: `retry_on_voicemail`, `retry_until_goal` + `goal_variable`, `mark_complete_when_no_leads`) |
\| `start_campaign` / `stop_campaign` | `campaigns:write` or `calls:write` | Launch or pause the dialer |
\| `list_leads` | `leads:read` or `calls:read` | List a campaign's leads |
\| `add_lead` / `add_leads` / `delete_lead` | `leads:write` or `calls:write` | Manage leads (single or bulk up to 1000, E.164-normalized, DNC-checked) |
\| `list_crm_syncs` / `get_crm_sync` | `automations:read` or `calls:read` | Inspect inbound CRM syncs and their durable run history |
\| `discover_crm_sync` | `automations:read` or `calls:read` | Discover objects, fields, lists, views, and filters without exposing connection credentials |
\| `create_crm_sync` / `update_crm_sync` / `delete_crm_sync` | `automations:write` or `calls:write` | Manage CRM-to-Audience sync configuration and field mappings |
\| `run_crm_sync` | `automations:write` or `calls:write` | Queue a durable manual CRM sync run |
\| `get_consent_mode` / `set_consent_mode` | `settings:read` / `settings:write` (or `assistants:*`) | Read or change universal vs. per-channel marketing opt-out enforcement |
\| `list_suppression_entries` | `suppression:read` or `campaigns:read` | Browse active contact suppressions, optionally filtered by blocked channel |
\| `add_suppression_entry` / `remove_suppression_entry` | `suppression:write` or `campaigns:write` | Record an opt-out by contact ID, phone or email / restore consent with an audit event |
\| `list_phone_numbers` | `phone_numbers:read` or `calls:read` | Numbers on the account |
\| `search_phone_numbers` | `phone_numbers:read` or `calls:read` | Search purchasable marketplace numbers incl. pricing |
\| `buy_phone_number` / `release_phone_number` | `phone_numbers:write` or `calls:write` | Purchase / release numbers (full billing + compliance flow) |
\| `assign_phone_number` | `phone_numbers:write` or `calls:write` | Assign a number to an assistant, toggle directions |
\| `list_sip_trunks` / `get_sip_trunk` | `sip_trunks:read` or `calls:read` | Browse SIP trunks (credentials never returned) |
\| `create_sip_trunk` / `delete_sip_trunk` | `sip_trunks:write` or `calls:write` | Bring your own carrier (DID/Extension, calling format, SLA advanced) / remove a trunk — see [BYO SIP trunk](/telephony/sip-trunks) |
\| `list_knowledge_bases` / `get_knowledge_base` | `knowledge:read` or `assistants:read` | Browse knowledge bases |
\| `create_knowledge_base` / `delete_knowledge_base` | `knowledge:write` or `assistants:write` | Manage knowledge bases |
\| `add_document` | `knowledge:write` or `assistants:write` | Add a document (raw text or file URL) and index it for retrieval |
\| `get_balance` | `billing:read` or `calls:read` | Minutes/credits balance + plan summary |
\| `get_me` | none (any valid token) | Inspect the calling credential, plan limits, and feature toggles |
\| `list_account_sessions` / `sign_out_account_session` | `settings:read` / `settings:write` (or `assistants:*`) | List tracked browser/device sessions and revoke one by its opaque ID; tokens and IP addresses are not exposed |
\| `get_memory_settings` / `update_memory_settings` | `settings:read` / `settings:write` (or `assistants:*`) | Workspace defaults for caller memory (default on/off + staleness window) |
\| `get_retention_settings` / `update_retention_settings` | `settings:read` / `settings:write` (or `assistants:*`) | Read the plan default and manage per-channel retention overrides; `null` restores the plan default |
\| `get_outbound_limits` / `request_outbound_limit_increase` | `settings:read` / `settings:write` (or `assistants:*`) | Read the workspace-wide integrated outbound quota and submit a higher-limit request |
\| `get_assistant_variables` / `set_assistant_variables` | `assistants:read` / `assistants:write` | Read / REPLACE an assistant's [custom variable](/assistants/variables) definitions |
\| `list_integrations` / `get_integration` | `integrations:read` or `assistants:read` | Browse [calendar integrations](/assistants/calendar-booking) (Cal.com, Calendly, Google, Outlook, native; secrets masked) |
\| `create_integration` / `update_integration` / `delete_integration` | `integrations:write` or `assistants:write` | Manage calendar integrations (connection-tested before saving; admin credential required) |
\| `get_assistant_integrations` / `set_assistant_integrations` | `integrations:read/write` or `assistants:read/write` | Read / REPLACE an assistant's calendar integration assignments |
\| `get_booking_event_types` | `bookings:read` or `assistants:read` | List the booking engine's event types (slug, duration, weekly availability) |
\| `create_booking_event_type` / `update_booking_event_type` / `delete_booking_event_type` | `bookings:write` or `assistants:write` | Manage event types of the built-in booking engine |
\| `list_bookings` / `get_booking` | `bookings:read` or `calls:read` | Browse bookings (filter by event type, status, time range) |
\| `cancel_booking` | `bookings:write` or `calls:write` | Cancel a booking (sends the `METHOD:CANCEL` ICS update) |
\| `get_usage_summary` | `calls:read` | Monthly call-minute usage |
\| `list_dashboards` / `get_dashboard` | `dashboards:read` or `calls:read` | Browse custom analytics dashboards |
\| `create_dashboard` / `update_dashboard` / `delete_dashboard` | `dashboards:write` or `calls:write` | Manage custom dashboards; `show_default_sections=false` creates a blank canvas and `hidden_default_sections` removes individual built-in cards (requires the `custom_dashboards` plan feature) |
\| `get_dashboard_analytics` | `dashboards:read` or `calls:read` | KPIs, comparison deltas, time series, breakdowns, campaign progress and gated module summaries |
\| `list_dashboard_widgets` | `dashboards:read` or `calls:read` | Read widgets, filters, visualization settings and grid layout |
\| `create_dashboard_widget` / `update_dashboard_widget` / `remove_dashboard_widget` | `dashboards:write` or `calls:write` | Build the dashboard canvas; remove detaches but keeps the reusable widget |

Each tool accepts either its fine-grained v1 scope **or** the legacy umbrella scope (`calls:*` for campaigns/leads/numbers/SIP/billing/dashboards, `assistants:*` for voices/knowledge) — OAuth tokens issued with the four standard scopes keep working for everything. Keys/tokens without scope restrictions have full access; `:write` implies `:read`.

## Errors

| Status | Meaning                                                       |
| ------ | ------------------------------------------------------------- |
| `401`  | No/invalid token — the client should (re)start the OAuth flow |
| `403`  | Plan lacks `connect_ai_mcp`                                   |
| `405`  | The endpoint is stateless — use `POST` only                   |

<Tip>
  The same capabilities are available as a classic [REST API](/api-reference/introduction) — pick whichever fits your integration.
</Tip>