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
}

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.
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.authorizationodertransport.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_idsein. 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 übercredential_idaus. - Zugangsdaten für stdio: Hinterlege die Werte in Umgebungsvariablen und führe deren Namen in
transport.env_varsauf. Code, der in der Umgebung läuft, kann diese Werte lesen. Selbst gehostete Sitzungen akzeptieren keine direkt intransport.envangegebenen 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
cwdden 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.