Den vollständigen Index der Dokumentation findest du in llms.txt. Die Markdown-Version einer Dokumentationsseite erhältst du, indem du .md an die URL der Seite anhängst.
Hauptnavigation
Design

MCP-Verbindungen

Stelle von OpenAI oder von deiner Umgebung aus eine Verbindung zu MCP-Servern her.

Ein MCP-Server stellt Tool-Definitionen bereit und führt Tool-Aufrufe aus. Die Agents API ermittelt die verfügbaren Tools, ruft den Server auf und gibt die Ergebnisse an den Agenten zurück. Deine Anwendung muss sich nicht um jeden einzelnen Aufruf kümmern.

Wähle den Ausgangspunkt der Verbindung danach aus, von wo aus der Server erreichbar ist.

Verbindung Ausgangspunkt der Verbindung Umgebung erforderlich
HTTP mit connection_origin: "service" (Standard) OpenAI Nein
HTTP mit connection_origin: "environment" Umgebung deiner Sitzung Ja
stdio Prozess in der Umgebung deiner Sitzung Ja

Verbindung von OpenAI aus herstellen

Füge einen MCP-Server mit HTTP-Transport zu agent.tools hinzu. Der Server muss von OpenAI aus erreichbar sein. Das funktioniert mit und ohne Sitzungsumgebung.

Der MCP-Server für die OpenAI-Dokumentation erlaubt beispielsweise anonymen Zugriff.

{
  "type": "mcp",
  "server_label": "openai_docs",
  "transport": {
    "type": "http",
    "server_url": "https://developers.openai.com/mcp"
  },
  "connection_origin": "service",
  "required": true
}
Der Dienst der Agents API stellt eine Verbindung zu einem entfernten MCP-Server her, sendet Aufrufe und empfängt Ergebnisse. Ein optional eingebundener Vault liefert die zur Server-URL passenden Zugangsdaten.

Verbindung von deiner Umgebung aus herstellen

Der Executor stellt die MCP-Verbindung von der Sitzungsumgebung aus her. Nutze diese Verbindungsart für Server in einem privaten Netzwerk oder für Software, die in dieser Umgebung installiert ist.

Setze environment.type für die Sitzung auf self_hosted oder openai_hosted. Wenn du die Umgebung selbst hostest, verbinde den Executor, bevor der Agent seine Tools nutzt.

Verbindung über HTTP herstellen

Verwende HTTP für einen Server, der bereits läuft. Füge den folgenden Eintrag zu agent.tools hinzu und ersetze die URL durch eine Adresse, die von deiner Umgebung aus erreichbar ist.

{
  "type": "mcp",
  "server_label": "internal_search",
  "transport": {
    "type": "http",
    "server_url": "https://mcp.internal.example.com/search"
  },
  "connection_origin": "environment",
  "required": true
}

Eine URL mit localhost verweist hier auf die Sitzungsumgebung. Lässt du connection_origin weg, stellt OpenAI die Verbindung her.

Server über stdio starten

Mit stdio kann der Executor einen Serverprozess starten. Installiere zuerst den Server und seine Abhängigkeiten in der Umgebung.

Installiere für dieses Beispiel zur Abfrage von Kundendaten das MCP SDK.

python3 -m venv /workspace/mcp-demo
/workspace/mcp-demo/bin/python -m pip install 'mcp==1.26.0'

Speichere das Serverskript unter /workspace/lookup_mcp.py.

MCP-Server zur Abfrage von Kundendaten ausführen
import sys

from mcp.server.fastmcp import FastMCP

server = FastMCP("customer-lookup", host="127.0.0.1", port=8765, stateless_http=True)


@server.tool()
def get_customer(customer_id: str) -> dict:
    """Look up a customer in the example data."""
    customers = {"123": {"name": "Example Customer", "plan": "pro"}}
    return {"customer": customers.get(customer_id)}


if __name__ == "__main__":
    transport = sys.argv[1] if len(sys.argv) > 1 else "streamable-http"
    server.run(transport=transport)

Füge den Server zu agent.tools hinzu. Das Argument stdio legt fest, welchen Transport das Skript verwendet.

{
  "type": "mcp",
  "server_label": "customer_lookup",
  "transport": {
    "type": "stdio",
    "command": "/workspace/mcp-demo/bin/python",
    "args": ["/workspace/lookup_mcp.py", "stdio"],
    "cwd": "/workspace"
  },
  "required": true
}

Für stdio musst du command und einen absoluten Pfad für cwd angeben. args ist optional. Lass connection_origin weg.

Sende dem Agenten eine Nachricht mit der Bitte, die Kundendaten zur ID 123 abzurufen. Das Tool gibt Example Customer mit dem Plan pro zurück.

Bei von OpenAI gehosteten MCP-Servern mit stdio kannst du die Netzwerkrichtlinie weglassen oder auf enabled setzen. Diese Verbindungen unterstützen die Netzwerkrichtlinien disabled und restricted nicht.

Authentifizierung hinzufügen

Wenn der Server anonymen Zugriff erlaubt, lass die Authentifizierungsfelder und vault_ids weg. Wähle andernfalls aus, woher die Zugangsdaten für deine Verbindung stammen.

  • HTTP-Zugangsdaten für eine einzelne Sitzung: Setze beim Erstellen der Sitzung transport.authorization oder transport.headers. Die Agents API verschlüsselt diese Werte und lässt sie in der zurückgegebenen Sitzungsressource weg.
  • Wiederverwendbare HTTP-Zugangsdaten: Speichere die MCP-Zugangsdaten in einem Vault und binde ihn über vault_ids ein. Die MCP-Authentifizierung über einen Vault ist nur für Verbindungen von OpenAI aus verfügbar. Die Auswahl der Zugangsdaten richtet sich nach der Server-URL. Passen mehrere Einträge, wähle den gewünschten über credential_id aus.
  • Zugangsdaten für stdio: Hinterlege die Werte in Umgebungsvariablen und führe deren Namen in transport.env_vars auf. Code, der in der Umgebung läuft, kann diese Werte lesen. Selbst gehostete Sitzungen akzeptieren keine direkt in transport.env angegebenen Werte.

Der HTTP-Transport kann beispielsweise ein Bearer-Token und einen weiteren Header enthalten.

{
  "type": "http",
  "server_url": "https://mcp.example.com/mcp",
  "authorization": "Bearer YOUR_MCP_ACCESS_TOKEN",
  "headers": { "X-Tenant-ID": "tenant_123" }
}

Verwende für Authorization nur eine Quelle. Gib den Wert entweder direkt in der Konfiguration an oder verwende einen passenden Eintrag aus dem Vault. Bei der Authentifizierung über einen Vault kannst du weitere Header angeben. HTTP-Verbindungen aus der Sitzungsumgebung verwenden keine Zugangsdaten aus einem Vault. Gib die Zugangsdaten direkt in der Konfiguration an oder nutze einen vertrauenswürdigen Proxy.

Halte geheime Werte aus wiederverwendbaren Agentendefinitionen, Plugin-Archiven und Logs heraus. Damit vom Agenten generierter Code nicht auf Zugangsdaten zugreifen kann, verwende einen vertrauenswürdigen Proxy oder Server, der die Zugangsdaten außerhalb der Umgebung bereitstellt.

Tool-Zugriff und Serverstart steuern

Lege mit allowed_tools fest, welche Tools der Agent finden und aufrufen darf. Setze required: true, damit der aktuelle Durchlauf fehlschlägt, wenn der Server nicht initialisiert werden kann. Standardmäßig ist die Initialisierung optional.

Alle Felder für die MCP-Konfiguration findest du in der API-Referenz zum Erstellen einer Sitzung.

Verbindungsprobleme beheben

Wenn die Initialisierung eines erforderlichen Servers fehlschlägt, prüfe den Fehler in agent.session.turn.failed. Prüfe bei stdio-Servern auch die Logs des MCP-Prozesses.

  • Netzwerkzugriff: Prüfe die URL und connection_origin. Prüfe bei Verbindungen aus der Umgebung, ob der Executor verbunden ist und den Server über sein Netzwerk erreichen kann.
  • Zugangsdaten: Prüfe das Token oder die Header. Wenn du einen Vault verwendest, prüfe, ob die Zugangsdaten zur Server-URL passen.
  • Ausführbare Datei und Abhängigkeiten: Prüfe, ob sich der konfigurierte Befehl in der Umgebung ausführen lässt.
  • Arbeitsverzeichnis: Gib bei einer Inline-Konfiguration für stdio unter cwd den absoluten Pfad zu einem vorhandenen Verzeichnis an.

Weiterführende Anleitungen

  • Plugins bündeln MCP-Konfigurationen und Skills, sodass du sie in mehreren Sitzungen verwenden kannst.
  • Die Anleitung zur Tool-Suche erklärt, wie die automatische Erkennung von MCP-Tools bei unterstützten Modellen und Anbietern funktioniert.