Einen KI-Agenten mit dem MCP-Server verbinden

Ein externer KI-Client — ein eigener Chatbot, eine Voice-Plattform oder ein Assistent wie Claude oder ChatGPT mit MCP-Unterstützung — spricht mit der Umgebung über einen Endpunkt, der JSON-RPC 2.0 spricht. Davon gibt es inzwischen nicht mehr einen, sondern drei. Welchen Sie brauchen, ist die erste Entscheidung, die Sie treffen, denn ein Schlüssel öffnet genau einen davon.

Die drei Türen

Alle drei sprechen dasselbe Protokoll und teilen sich dieselbe Transportschicht. Sie unterscheiden sich darin, was dahinter liegt, und damit darin, wie viel Vertrauen sie verlangen.

Die Namen sagen genau das, was sie sagen: config ist Verwaltung — Dinge einstellen, die danach für alle gelten — und operations ist Ausführung. Einen Tisch zuweisen ist operations; festlegen, welche Tische es gibt, ist config.

Ein Schlüssel öffnet eine Tür

Ein KI-Agent authentifiziert sich mit einem Benutzerschlüssel der Form sk_<Lizenz>_<Benutzer>_<Geheimnis>. Beim Anlegen wählen Sie den Geltungsbereich, und der entscheidet, welche Tür der Schlüssel öffnet. Ein Buchungsschlüssel an /mcpconfig erhält einen 401 — und zwar vor der Anmeldung, sodass ein Schlüssel für die falsche Tür nie eine Sitzung bekommt.

Zwei Dinge überraschen dabei regelmäßig:

• Ein leerer Geltungsbereich bedeutet booking. Schlüssel aus der Zeit vor der Aufteilung wurden nicht stillschweigend eingeschränkt — das hätte funktionierende Integrationen zerstört — also akzeptiert die Buchungstür sowohl booking als auch leer.
• Die REST-API gehört zur Buchungsfamilie. Derselbe Geltungsbereich wird bei REST v1 und v2 geprüft. Ein an /mcp abgewiesener Schlüssel kommt also auch über REST nicht hinein.

Schlüssel verwalten Sie unter Konfiguration › System › API, wofür Sie das Recht menu_config_api benötigen. Der vollständige Schlüssel wird einmalig angezeigt und danach gehasht gespeichert — sichern Sie ihn sofort. Ein Schlüssel kann außerdem ein Ablaufdatum bekommen und widerrufen statt gelöscht werden, sodass hinterher noch nachvollziehbar ist, wofür er da war. Siehe Wie funktioniert ein API-Schlüssel?.

Neben einem Schlüssel kann sich ein Client auch über OAuth verbinden: Der Benutzer meldet sich dann in der Umgebung an und genehmigt den Client im Browser. Ab der Tür gibt es keinen Unterschied — beide benennen einen Benutzer einer Lizenz, mit denselben Rechten und derselben Prüfspur.

Was ein Agent darf: drei Schichten

Hineinkommen ist nicht dasselbe wie etwas zu dürfen. Hinter jeder Tür wird pro Tool dieselbe Kette geprüft, und zwar als UND:

1. Das Hauptrecht der Tür — tool_use, tool_config_use oder tool_operations_use. Ein Schalter, der die ganze Tür ein- oder ausschaltet.
2. Das Recht auf genau dieses Tool — zum Beispiel tool_config_object_update_apply. Plan und Apply sind getrennte Rechte, Sie können also jemandem zeigen lassen, was eine Änderung bewirken würde, ohne ihn diese Änderung machen zu lassen.
3. Das Fachrecht — dasselbe Recht, das die Maske verwendet, die dieselbe Handlung ausführt. Es kommen keine eigenen Rechte pro Endpunkt hinzu: Wer in den Masken keinen Kunden ändern darf, kann das über ein Tool auch nicht.

Die Rechte liegen pro Tür in einer eigenen Gruppe: MCP, MCP-Config und MCP-Operations. Siehe Berechtigungen für KI-Werkzeuge.

Öffentliche Tools gibt es nur an der Buchungstür — Tools, die ein Website-Besucher ohne angemeldeten Benutzer erreichen kann. An der Konfigurations- und der Betriebstür ist nichts öffentlich, und jeder Aufruf ohne Anmeldung wird abgewiesen, Lesezugriffe eingeschlossen.

Stufen: dieselbe Zahl, drei Bedeutungen

Jedes Tool trägt eine Stufe. Diese Zahl bedeutet pro Tür etwas anderes, und das ist Absicht — sie beschreibt jeweils den Schutz, der zu dieser Tür gehört.

An der Konfigurationstür gilt zusätzlich etwas, was die anderen beiden nicht haben: zwei Schlösser, die beide offen stehen müssen, bevor überhaupt geschrieben wird. Eines setzt der Anbieter für die ganze Umgebung, das andere der Lizenznehmer selbst. Ist eines zu, wird jeder Schreibaufruf abgewiesen — und jeder Lesezugriff ebenso, denn sonst würde die Tür, die Sie nicht öffnen können, trotzdem in allen Einzelheiten beschreiben, was dahinter steht.

Verbinden in fünf Schritten

1. Den Agenten einschalten

Ohne aktiven Agenten passiert nichts, in keinem Kanal. Unter Konfiguration › KI › Agent-Einstellungen schalten Sie Agent aktiv ein. Dort wählen Sie auch den Agent-Modus: Reservierungen oder Veranstaltungen. Diese Wahl entscheidet, welche Tools die Buchungstür anbietet, treffen Sie sie also bewusst — beides einzuschalten führt zu falschen Toolentscheidungen. Siehe Agent-Einstellungen.

2. Einen Schlüssel mit dem richtigen Geltungsbereich anlegen

Wählen Sie den Geltungsbereich, der laut Tabelle oben zur Tür gehört. Wenn Sie einen Client wollen, der sowohl bucht als auch einrichtet, sind das zwei Schlüssel — und genau so ist es gedacht, denn es sind zwei Vertrauensstufen.

3. Den Client verbinden

Der Endpunkt ist die Adresse Ihrer eigenen Umgebung mit dem angehängten Pfad:

https://ihre-umgebung.example.com/mcp
https://ihre-umgebung.example.com/mcpconfig
https://ihre-umgebung.example.com/mcpoperations

Wie Sie diese URL eintragen, ist je Client verschieden, und genau daran scheitert es in der Praxis: viele Clients haben überhaupt kein Feld für einen Header. Es gibt drei Wege, und der erste ist für die meisten der richtige.

Weg 1: im Browser anmelden, ohne Schlüssel

Ein Client wie Claude Desktop fragt beim Anlegen eines eigenen Connectors nur nach einer URL — unter Advanced settings steht höchstens eine optionale OAuth Client ID samt Secret und nirgends ein freies Headerfeld. Das ist auch nicht nötig: Die Umgebung veröffentlicht die Standard-OAuth-Dokumente und meldet den Client selbst an. Sie fügen die URL ein, ein Browserfenster öffnet sich, Sie melden sich mit Ihrem eigenen Konto an und sehen auf einem Zustimmungsbildschirm, worum der Client bittet. Danach ist er verbunden.

Auf diesem Weg kommt kein Schlüssel vor. Es gibt also auch nichts aufzubewahren, weiterzugeben oder zu verlieren. Die Rechte sind die Ihres Kontos, und die Tür ergibt sich aus der eingetragenen URL.

Zwei Dinge sollten Sie vorher wissen:

• Der Client verbindet sich von der Infrastruktur des Anbieters aus, nicht von Ihrem Rechner. Die Umgebung muss also aus dem Internet erreichbar sein. Eine lokale Testumgebung oder eine Umgebung hinter einem IP-Filter funktioniert so nicht.
• Ein Support-Konto kann das nicht. Ein solches Konto hat keine eigene Lizenz, sondern wird jeweils zu einer; ein Token macht das Gegenteil und legt einen Benutzer für Tage fest. Der Zustimmungsbildschirm weist das deshalb ab und verweist Sie auf die Maske, in der Sie zuerst zu dem Benutzer wechseln, zu dem diese Verbindung gehört.

Weg 2: ein Client, der Header beherrscht

Kann Ihr Client einen Header mitsenden, geht der Schlüssel als Authorization: Bearer <Schlüssel> oder als X-API-KEY mit; sind beide vorhanden, gewinnt Authorization. Auf der Kommandozeile von Claude Code zum Beispiel:

claude mcp add --transport http ireserve-config \
  https://ihre-umgebung.example.com/mcpconfig \
  --header "Authorization: Bearer sk_..."

Der Schlüssel landet dann in der Konfiguration des Clients auf Ihrem eigenen Rechner. Genau dorthin gehört er: in eine Einstellung, nicht in ein Gespräch.

Weg 3: ein Client, der nur lokale Server kennt

Manche Clients können ausschließlich ein lokales Programm starten und keine Adresse direkt ansprechen. Dazwischen setzen Sie eine kleine Brücke, die die Verbindung weiterreicht und den Header ergänzt; mcp-remote ist dafür das übliche Werkzeug. Tragen Sie in der Konfiguration des Clients den Befehl mit der URL und dem Header dahinter ein und halten Sie den Schlüssel in einer Umgebungsvariablen statt in der Datei selbst. Wählen Sie eine aktuelle Version — ältere enthielten eine schwere Sicherheitslücke.

4. Prüfen, was zurückkommt

Welche Tools verfügbar sind, fragen Sie mit der Standard-MCP-Methode tools/list ab; ausgeführt wird eines mit tools/call. Das ist das Protokoll, nichts Eigenes — ein Client, der MCP spricht, regelt das selbst.

Die Liste ist keine feste Liste. Sie hängt von der Tür ab, von Ihren Rechten, vom Agent-Modus und davon, welche Teile eingerichtet sind. Fehlt ein Tool, das Sie erwartet haben, ist das fast immer ein Recht oder eine Einstellung und kein Fehler. Bekommen Sie eine leere Liste, obwohl der Schlüssel funktioniert, schauen Sie zuerst auf das Hauptrecht dieser Tür.

5. Ohne Ihren Client testen

Bevor Sie in Ihrer eigenen Integration suchen: Die Tool-Konsole unter Konfiguration › KI › Tool-Konsole führt ein einzelnes Tool direkt aus, über genau denselben Weg wie der Endpunkt. Sie sehen das rohe Ergebnis und die zugehörige Zeile aus der Prüfspur. Funktioniert es dort und bei Ihnen nicht, liegt das Problem an Ihrer Verbindung oder Ihrem Schlüssel. Siehe Die Werkzeug-Konsole verwenden.

Achtung: Schreibende Tools tun dort echte Dinge. Eine Testbuchung ist eine echte Buchung.

Wenn etwas schiefgeht

Jeder abgewiesene Aufruf schreibt eine Zeile in das Sicherheitsprotokoll, mit dem Grund und mit der betroffenen Tür. Die Antwort enthält einen Verweis auf diese Zeile, sodass eine Meldung "er sagt unauthorized" direkt zu ihrem eigenen Protokolleintrag führt. Die häufigsten Ursachen, der Reihe nach: Der Header kommt nicht an, es wurde der lizenzweite API-Schlüssel statt eines Benutzerschlüssels verwendet, oder der Schlüssel wurde für eine andere Tür angelegt.

Das Widget ist etwas anderes

Das eigene Chat-Widget hat keinen angemeldeten Benutzer und läuft deshalb auf einer festen Liste von Besucher-Tools an der Buchungstür. Es braucht keinen Schlüssel mit Geltungsbereich — siehe Das KI-Widget zu deiner Website hinzufügen.