> ## 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-Endpunkt

> Verbinde Claude, ChatGPT oder einen beliebigen MCP-Client mit deinem Konto

Die Plattform bringt einen eingebauten **MCP-Server** mit (Model Context Protocol, streambares HTTP). Verbinde eine KI-Anwendung – Claude, ChatGPT, Cursor oder deinen eigenen Agenten – und sie kann in deinem Namen Assistenten verwalten, Anrufe starten, Transkripte lesen und Kampagnen pflegen.

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

Auf einer White-Label-Domain laufen Endpunkt, Login- und Zustimmungsbildschirme unter dem Branding des Tenants. Für den Zugriff brauchst du die Funktion **Connect AI / MCP** in deinem Plan (`connect_ai_mcp`) – sonst antwortet der Endpunkt mit `403`.

## Clients verbinden

<Tabs>
  <Tab title="Claude">
    1. **Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen**
    2. Gib `https://app.famulor.io/mcp` ein
    3. Claude startet den OAuth-Flow automatisch: Melde dich auf der Login-Seite deiner Plattform an und bestätige den Zustimmungsbildschirm.
    4. Die Tools erscheinen in Claude.
  </Tab>

  <Tab title="ChatGPT">
    1. **Einstellungen → Connectors → Erstellen** (benutzerdefinierter Connector)
    2. MCP-Server-URL: `https://app.famulor.io/mcp`, Authentifizierung: **OAuth**
    3. Melde dich an und bestätige – die Tools sind danach in ChatGPT verfügbar.
  </Tab>

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

    Alternativ kannst du OAuth überspringen und dich mit einem **API-Key** (`fam_...`, erstellt unter Einstellungen) als statischem Bearer-Token authentifizieren: `Authorization: Bearer fam_...`
  </Tab>
</Tabs>

### Über das Dashboard verbinden

Der schnellste Weg, eine Verbindung herzustellen, ist das eingebaute **Connect AI**-Modal: Öffne die **Tools**-Seite im Dashboard und klicke auf **In ChatGPT & Claude nutzen**. Das Modal zeigt dir die MCP-URL deines Kontos (deine White-Label-Domain, falls konfiguriert und verifiziert), lässt dich sie mit einem Klick kopieren und bietet vorgefertigte Start-Prompts: einen Assistenten bauen, einen Assistenten reparieren, den letzten Anruf analysieren, die letzten 30 Anrufe auswerten oder eine Kampagne starten. **In Claude öffnen** / **In ChatGPT öffnen** übergibt den gewählten Prompt direkt an die KI-App; du schließt dort nur noch Login und Zustimmung ab.

## Authentifizierung

Der Endpunkt implementiert den kompletten modernen MCP-Auth-Stack – Clients erledigen das automatisch:

1. Eine nicht authentifizierte Anfrage bekommt `401` mit Metadaten zur geschützten Ressource zurück (RFC 9728).
2. Der Client ermittelt den Autorisierungsserver (RFC 8414), registriert sich per Dynamic Client Registration (RFC 7591) und durchläuft **Authorization Code + PKCE**.
3. Du meldest dich an (White-Label-Login) und bestätigst den Zustimmungsbildschirm – einmal pro Anwendung; die Genehmigung bleibt 180 Tage gespeichert.
4. Der Client erhält ein Access Token (`fam_at_...`, 1 Stunde gültig, inkl. Refresh Token) und ruft damit den Endpunkt auf.

## Verfügbare Tools

Jede Operation der [REST API v1](/api-reference/introduction) steht auch als MCP-Tool zur Verfügung – gleiche Services, gleiche Validierung (Plan-Limits, Modellkatalog, DNC-Liste).

| Tool                                    | Scope              | Beschreibung                                                                                                                                                                                                                                                                                                   |
| --------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_assistants` / `get_assistant`     | `assistants:read`  | Assistenten auflisten / eine Konfiguration abrufen                                                                                                                                                                                                                                                             |
| `get_assistant_compliance_review`       | `assistants:read`  | Aktuellen Compliance-Status, Score, Hinweise, Begründung und manuellen Prüfstatus lesen                                                                                                                                                                                                                        |
| `request_assistant_compliance_review`   | `assistants:write` | Den aktuellen gesperrten Assistant-Snapshot mit Begründung zur manuellen Prüfung einreichen                                                                                                                                                                                                                    |
| `create_assistant` / `update_assistant` | `assistants:write` | Assistenten erstellen/bearbeiten (Updates werden automatisch versioniert). Standardmäßig entsteht ein **Single Prompt** (`flow_json` ist `null`). Übergib `flow_json` für einen **Conversational Flow**. Nutze `list_prompt_templates` und dann `system_prompt` / `first_message`, um eine Vorlage anzuwenden. |

In-App **[Milian Copilot](/assistants/milian-copilot)** nutzt dieselben Services über deine Login-Session (`/api/milian/*`) – nicht diesen MCP-Endpunkt.
\| `delete_assistant` | `assistants:write` | Einen Assistenten dauerhaft löschen |
\| `list_tools` / `get_tool` | `assistants:read` | Wiederverwendbare Tools auflisten (HTTP-API-Tools + externe MCP-Server) / eines abrufen (Secrets maskiert als `•••`) |
\| `create_tool` / `update_tool` / `delete_tool` | `assistants:write` | Wiederverwendbare Tools verwalten (`type` `api`, `mcp` oder `builtin` – Letzteres bettet ein [integriertes Tool](/assistants/built-in-tools) als Workspace-Tool ein; Erstellen/Bearbeiten braucht einen Admin-Zugang, da die Konfiguration Secrets enthält) |
\| `get_assistant_tools` / `set_assistant_tools` | `assistants:read` / `assistants:write` | Tool-Zuweisungen eines Assistenten lesen / ERSETZEN |
\| `get_voices` | `voices:read` oder `assistants:read` | Die TTS-Sprachbibliothek durchsuchen (Anbieter, Sprache, Geschlecht, Akzent, Suche) |
\| `get_models` | `assistants:read` | Den Modellkatalog durchsuchen (`type` = `llm`, `stt`, `tts` oder `realtime`) – die Modelle, die für die Assistenten-Konfiguration verfügbar sind |
\| `get_languages` | `assistants:read` | Die unterstützten Assistenten-Sprachen auflisten (ISO-639-1-Codes + Labels) für `primary_language` / `secondary_languages` |
\| `list_calls` / `get_call` | `calls:read` | Anrufe durchsuchen; `get_call` enthält Transkript, Zusammenfassung und eine temporäre `recording_url` |
\| `list_history` / `get_email_history_item` | `calls:read` | Anrufe und gruppierte E-Mail-Konversationen durchsuchen; jede Kunden-/Assistenten-Nachricht mit derselben stabilen Thread-ID bildet eine Zeile und lässt sich chronologisch abrufen |
\| `make_call` | `calls:write` | Einen ausgehenden Anruf starten (`assistant_id`, `to_number`, optionaler Lead) |
\| `live_call_control` | `calls:write` | Steuerung während eines aktiven Anrufs: `listen_token`, `whisper`, `end_agent` oder `hangup` (braucht die Plan-Funktion `live_monitoring`) |
\| `list_campaigns` / `get_campaign` | `campaigns:read` oder `calls:read` | Kampagnen durchsuchen, inkl. Dialer-Einstellungen und Lead-Anzahl |
\| `create_campaign` / `update_campaign` / `delete_campaign` | `campaigns:write` oder `calls:write` | Kampagnen verwalten (Parallelität, Wiederholungen, Anruffenster und Retry-Regeln: `retry_on_voicemail`, `retry_until_goal` + `goal_variable`, `mark_complete_when_no_leads`) |
\| `start_campaign` / `stop_campaign` | `campaigns:write` oder `calls:write` | Den Dialer starten oder pausieren |
\| `list_leads` | `leads:read` oder `calls:read` | Die Leads einer Kampagne auflisten |
\| `add_lead` / `add_leads` / `delete_lead` | `leads:write` oder `calls:write` | Leads verwalten (einzeln oder als Bulk bis zu 1000, E.164-normalisiert, DNC-geprüft) |
\| `list_crm_syncs` / `get_crm_sync` | `automations:read` oder `calls:read` | Inbound-CRM-Syncs und ihre dauerhafte Laufhistorie einsehen |
\| `discover_crm_sync` | `automations:read` oder `calls:read` | Objekte, Felder, Listen, Ansichten und Filter ermitteln, ohne Verbindungs-Credentials offenzulegen |
\| `create_crm_sync` / `update_crm_sync` / `delete_crm_sync` | `automations:write` oder `calls:write` | CRM-zu-Audience-Syncs und Feldzuordnungen verwalten |
\| `run_crm_sync` | `automations:write` oder `calls:write` | Einen dauerhaften manuellen CRM-Sync-Lauf einreihen |
\| `get_consent_mode` / `set_consent_mode` | `settings:read` / `settings:write` (oder `assistants:*`) | Universelle bzw. kanalbezogene Marketing-Opt-outs lesen oder konfigurieren |
\| `list_suppression_entries` | `suppression:read` oder `campaigns:read` | Aktive Kontakt-Suppressions durchsuchen, optional nach blockiertem Kanal gefiltert |
\| `add_suppression_entry` / `remove_suppression_entry` | `suppression:write` oder `campaigns:write` | Opt-out per Kontakt-ID, Telefon oder E-Mail erfassen / Consent mit Audit-Event wiederherstellen |
\| `list_phone_numbers` | `phone_numbers:read` oder `calls:read` | Nummern des Kontos |
\| `search_phone_numbers` | `phone_numbers:read` oder `calls:read` | Käufliche Nummern im Marketplace durchsuchen, inkl. Preisen |
\| `buy_phone_number` / `release_phone_number` | `phone_numbers:write` oder `calls:write` | Nummern kaufen / freigeben (vollständiger Abrechnungs- und Compliance-Ablauf) |
\| `assign_phone_number` | `phone_numbers:write` oder `calls:write` | Einem Assistenten eine Nummer zuweisen, Anrufrichtungen umschalten |
\| `list_sip_trunks` / `get_sip_trunk` | `sip_trunks:read` oder `calls:read` | SIP-Trunks durchsuchen (Zugangsdaten werden nie zurückgegeben) |
\| `create_sip_trunk` / `delete_sip_trunk` | `sip_trunks:write` oder `calls:write` | Eigenen Carrier anbinden (DID/Nebenstelle, Anrufformat, erweiterte SLA) / einen Trunk entfernen – siehe [BYO-SIP-Trunk](/telephony/sip-trunks) |
\| `list_knowledge_bases` / `get_knowledge_base` | `knowledge:read` oder `assistants:read` | Wissensdatenbanken durchsuchen |
\| `create_knowledge_base` / `delete_knowledge_base` | `knowledge:write` oder `assistants:write` | Wissensdatenbanken verwalten |
\| `add_document` | `knowledge:write` oder `assistants:write` | Ein Dokument hinzufügen (Rohtext oder Datei-URL) und für die Suche indexieren |
\| `get_balance` | `billing:read` oder `calls:read` | Minuten-/Credits-Guthaben + Plan-Übersicht |
\| `get_me` | keiner (jedes gültige Token) | Das aufrufende Credential, Plan-Limits und Feature-Toggles einsehen |
\| `get_memory_settings` / `update_memory_settings` | `settings:read` / `settings:write` (oder `assistants:*`) | Workspace-Standardwerte für das Anrufer-Gedächtnis (Standard ein/aus + Zeitfenster bis zur Veralterung) |
\| `get_retention_settings` / `update_retention_settings` | `settings:read` / `settings:write` (oder `assistants:*`) | Planstandard lesen und kanalbezogene Aufbewahrungsfristen verwalten; `null` stellt den Planstandard wieder her |
\| `get_outbound_limits` / `request_outbound_limit_increase` | `settings:read` / `settings:write` (oder `assistants:*`) | Das workspaceweite Limit für integrierte Outbound-Anrufe lesen und eine Erhöhung beantragen |
\| `get_assistant_variables` / `set_assistant_variables` | `assistants:read` / `assistants:write` | Die [Custom-Variable](/assistants/variables)-Definitionen eines Assistenten lesen / ERSETZEN |
\| `list_integrations` / `get_integration` | `integrations:read` oder `assistants:read` | [Kalender-Integrationen](/assistants/calendar-booking) durchsuchen (Cal.com, Calendly, Google, Outlook, nativ; Secrets maskiert) |
\| `create_integration` / `update_integration` / `delete_integration` | `integrations:write` oder `assistants:write` | Kalender-Integrationen verwalten (Verbindung wird vor dem Speichern getestet; Admin-Zugang erforderlich) |
\| `get_assistant_integrations` / `set_assistant_integrations` | `integrations:read/write` oder `assistants:read/write` | Kalender-Integrations-Zuweisungen eines Assistenten lesen / ERSETZEN |
\| `get_booking_event_types` | `bookings:read` oder `assistants:read` | Die Event-Types der Buchungs-Engine auflisten (Slug, Dauer, wöchentliche Verfügbarkeit) |
\| `create_booking_event_type` / `update_booking_event_type` / `delete_booking_event_type` | `bookings:write` oder `assistants:write` | Event-Types der integrierten Buchungs-Engine verwalten |
\| `list_bookings` / `get_booking` | `bookings:read` oder `calls:read` | Buchungen durchsuchen (Filter nach Event-Type, Status, Zeitraum) |
\| `cancel_booking` | `bookings:write` oder `calls:write` | Eine Buchung stornieren (sendet das ICS-Update `METHOD:CANCEL`) |
\| `get_usage_summary` | `calls:read` | Monatliche Gesprächsminuten |
\| `list_dashboards` / `get_dashboard` | `dashboards:read` oder `calls:read` | Individuelle Analyse-Dashboards durchsuchen |
\| `create_dashboard` / `update_dashboard` / `delete_dashboard` | `dashboards:write` oder `calls:write` | Individuelle Dashboards verwalten; `show_default_sections=false` erstellt eine leere Canvas, `hidden_default_sections` entfernt einzelne Standard-Karten (braucht die Plan-Funktion `custom_dashboards`) |
\| `get_dashboard_analytics` | `dashboards:read` oder `calls:read` | KPIs, Vergleichs-Deltas, Zeitreihen, Aufschlüsselungen, Kampagnen-Fortschritt und Zusammenfassungen gesperrter Module |
\| `list_dashboard_widgets` | `dashboards:read` oder `calls:read` | Widgets, Filter, Visualisierungseinstellungen und Grid-Layout lesen |
\| `create_dashboard_widget` / `update_dashboard_widget` / `remove_dashboard_widget` | `dashboards:write` oder `calls:write` | Die Dashboard-Canvas gestalten; Remove löst nur die Zuordnung, das wiederverwendbare Widget bleibt erhalten |

Jedes Tool akzeptiert entweder seinen fein-granularen v1-Scope **oder** den alten Sammel-Scope (`calls:*` für Kampagnen/Leads/Nummern/SIP/Abrechnung/Dashboards, `assistants:*` für Voices/Wissensdatenbank) – OAuth-Tokens, die mit den vier Standard-Scopes ausgestellt wurden, funktionieren weiterhin für alles. Keys/Tokens ohne Scope-Einschränkung haben vollen Zugriff; `:write` schließt `:read` automatisch mit ein.

## Fehler

| Status | Bedeutung                                                              |
| ------ | ---------------------------------------------------------------------- |
| `401`  | Kein/ungültiges Token – der Client sollte den OAuth-Flow (neu) starten |
| `403`  | Dem Plan fehlt `connect_ai_mcp`                                        |
| `405`  | Der Endpunkt ist zustandslos – nutze nur `POST`                        |

<Tip>
  Dieselben Funktionen stehen auch als klassische [REST API](/api-reference/introduction) zur Verfügung – wähle, was am besten zu deiner Integration passt.
</Tip>