MCP-Endpunkt

API-Referenz für den FlowCaptain MCP-Endpunkt (Model Context Protocol) zur automatischen Tool-Erkennung.

MCP-Endpunkt

FlowCaptain stellt einen MCP-Endpunkt (Model Context Protocol) bereit, der Voice-Bot-Plattformen und KI-Agenten ermöglicht, alle Termin-Tools automatisch zu erkennen und zu nutzen.

Endpunkt

POST /mcp?calendarId=YOUR_CALENDAR_ID

calendarId ist ein erforderlicher Query-Parameter, der angibt, für welchen Kalender die Tools arbeiten. Ohne ihn gibt die API einen 400-Fehler zurück. Deine Kalender-ID findest du in jedem Beispiel vorausgefüllt unter Dashboard → Kalender → API → Integrations-Anleitung.

Nur POST wird unterstützt — GET- und DELETE-Anfragen an /mcp erhalten einen 405-Fehler. Der Endpunkt ist zustandslos: Jede Anfrage steht für sich, es gibt keine MCP-Sessions.

Headers

Authorization: Bearer sk_live_dein_api_schluessel
Accept: application/json, text/event-stream
Content-Type: application/json

Der Accept-Header muss sowohl application/json als auch text/event-stream enthalten. Voice-Bot-Plattformen wie Retell und VAPI senden dies automatisch.

So funktioniert es

MCP ist ein Protokoll, das die dynamische Erkennung von KI-Tools ermöglicht. Anstatt jeden Endpunkt manuell zu konfigurieren, verbindet sich dein Voice Bot einmal mit dem MCP-Endpunkt und sieht automatisch alle verfügbaren Tools:

Die Plattform sendet eine initialize-Anfrage zur Erkennung der Fähigkeiten
Dann sendet sie eine tools/list-Anfrage, um alle verfügbaren Tools zu erhalten
Wenn der Voice Bot Verfügbarkeit prüfen oder einen Termin buchen muss, sendet er eine tools/call-Anfrage

Verfügbare Tools

Tool-Name	Beschreibung
get_calendar_status	Auslastung, Öffnungsstatus und nächste freie Zeit des Kalenders
list_services	Buchbare Leistungen mit Dauer und Typ auflisten
list_appointments	Termine eines Anrufers abfragen
check_availability	Verfügbare Zeitfenster mit natürlicher Sprache prüfen
book_appointment	Termin mit Anruferdaten buchen
cancel_appointment	Bestehenden Termin stornieren
reschedule_appointment	Termin auf neue Zeit umbuchen
request_callback	Rückruf anfordern, wenn der Bot das Anliegen nicht lösen kann

Die Tool-Parameter entsprechen den REST-Endpunkten: check_availability erwartet die natürlichsprachliche Anfrage im Parameter checkAvail; book_appointment erwartet bookAppointment (ISO-8601-Zeitstempel) und callerName sowie optional callerPhone, callerIdNumber, reason, serviceName und language.

Testen mit curl

curl -X POST "https://api.flowcaptain.com/mcp?calendarId=YOUR_CALENDAR_ID" \
  -H "Authorization: Bearer sk_live_dein_api_schluessel" \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "1.0" }
    }
  }'

Wann MCP vs. REST verwenden

Beide bieten den gleichen Funktionsumfang. MCP erkennt alle Tools automatisch über einen einzigen Endpunkt, während REST separate Endpunkte pro Aktion verwendet. Wir empfehlen MCP, wann immer deine Plattform es unterstützt — die Einrichtung ist schneller und neue Tools stehen automatisch zur Verfügung, ohne deine Integration anzupassen.