MCP-Werkzeug: entfernte MCP-Server direkt aus API-Anfragen aufrufen

Ergänzen Sie im Array tools einer Anfrage an POST /v1/responses einen Eintrag mit type: "mcp". Geben Sie ihm ein server_label, das den Server in der Ausgabe benennt, und die server_url eines entfernten MCP-Servers mit Streamable-HTTP-Transport. Eine optionale server_description hilft dem Modell zu entscheiden, wann der Server nützlich ist.

Bei der Ausführung holt die API die Werkzeugliste des Servers und stellt sie dem Modell zur Verfügung. Entscheidet sich das Modell für ein Werkzeug, ruft die API den Server auf, gibt das Ergebnis an das Modell zurück und macht weiter, bis eine Antwort vorliegt. Die Aufrufe erfolgen von unserer Infrastruktur in der EU aus.

Die meisten Server brauchen Zugangsdaten. Übergeben Sie sie in headers, etwa als Header Authorization mit einem Token für den Dienst. Header werden nur für den Aufruf genutzt und nicht in der Antwort zurückgegeben. Verwenden Sie trotzdem ein Token mit möglichst engen Rechten.

allowed_tools begrenzt, welche Werkzeuge des Servers das Modell sieht. Das hält den Prompt klein und das Verhalten vorhersehbar. require_approval legt fest, ob ein Aufruf Ihre Bestätigung braucht: never führt Aufrufe automatisch aus, always hält jeden an, und ein Objekt mit Listen always und never regelt es pro Werkzeug. Freigaben empfehlen sich für Werkzeuge, die Daten ändern, etwa Tickets anlegen oder Nachrichten senden.

Das Array output zeigt den Ablauf in Reihenfolge. Ein Element mcp_list_tools hält fest, welche Werkzeuge der Server angeboten hat. Jeder Aufruf erscheint als Element mcp_call mit server_label, Werkzeugname in name, den JSON-arguments und dem output des Servers oder einem error. Das abschließende Element message enthält die Antwort, in den SDKs auch als output_text.

Ist eine Freigabe nötig, enthält die Antwort stattdessen ein Element mcp_approval_request. Zum Fortsetzen senden Sie eine neue Anfrage mit previous_response_id und einem Eingabeelement vom Typ mcp_approval_response, das auf die id der Anfrage verweist und approve auf true oder false setzt.

Ist der Server nicht erreichbar, lehnt er die Zugangsdaten ab oder liefert er eine ungültige Werkzeugliste, scheitert die Anfrage mit einem Fehler, der das server_label nennt, oder das Element mcp_call trägt den Fehler, damit das Modell ihn erklären kann. Prüfen Sie, ob die URL öffentlich per HTTPS erreichbar und das Token gültig ist.

Das Modell sieht alles, was der Server zurückgibt. Binden Sie daher nur vertrauenswürdige Server ein, denn Werkzeugausgaben können Anweisungen enthalten, die das Modell lenken sollen. Lange Werkzeuglisten und große Ergebnisse kosten Eingabe-Tokens, filtern Sie mit allowed_tools. Daten an einen fremden MCP-Server verarbeitet dieser Dienst nach eigenen Bedingungen; prüfen Sie, wo er läuft.