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

Authentifizierung

Authentifizierungsverfahren für MCP-Server von Plugins.

Nutzende authentifizieren

Viele MCP-Server für Plugins lassen sich anonym und ohne Schreibzugriff nutzen. Sobald ein Server jedoch kundenspezifische Daten bereitstellt oder Schreibaktionen ermöglicht, sollte er die Nutzenden authentifizieren.

Veröffentlichte Plugins können sowohl in ChatGPT als auch in Codex ausgeführt werden. Für beide Produkte gelten dieselben MCP-Vorgaben zur Autorisierung. Wo sich Callbacks, Metadatendokumente oder die Oberfläche zum Verknüpfen eines Kontos unterscheiden, geht dieser Leitfaden auf die Besonderheiten des ChatGPT-Clients ein.

Du kannst deinen eigenen Autorisierungsserver einbinden, wenn du eine Verbindung zu einer bestehenden serverseitigen Anwendung herstellen oder Daten zwischen Nutzenden teilen möchtest.

Eigene Authentifizierung mit OAuth 2.1

Für einen MCP-Server mit Authentifizierung musst du einen OAuth-2.1-Ablauf implementieren, der der MCP-Spezifikation zur Autorisierung entspricht.

Komponenten

  • Ressourcenserver: Dein MCP-Server stellt Tools bereit und prüft bei jeder Anfrage das Zugriffstoken.
  • Autorisierungsserver: Dein Identitätsanbieter oder deine eigene Implementierung stellt Token aus und veröffentlicht Discovery-Metadaten.
  • Client: Der OpenAI-Host, etwa ChatGPT oder Codex, handelt im Auftrag der Person, die ihn nutzt. Unterstützte Clients verwenden Client ID Metadata Documents (CIMD), dynamische Clientregistrierung (DCR), vordefinierte OAuth-Clients und PKCE.

Anforderungen der MCP-Spezifikation zur Autorisierung

  • Stelle die Metadaten der geschützten Ressource auf deinem MCP-Server bereit.
  • Veröffentliche die OAuth-Metadaten auf deinem Autorisierungsserver.
  • Gib den Parameter resource im gesamten OAuth-Ablauf weiter.
  • Lege fest, wie der OpenAI-Host seinen OAuth-Client identifiziert oder registriert. Zur Wahl stehen CIMD, DCR und ein vordefinierter OAuth-Client.
  • Veröffentliche die Authentifizierungsmethoden, die dein Autorisierungsserver am Token-Endpunkt akzeptiert.

Die folgenden Abschnitte erklären, wie du die Vorgaben umsetzt.

Metadaten der geschützten Ressource auf deinem MCP-Server bereitstellen

  • Du brauchst einen HTTPS-Endpunkt wie GET https://your-mcp.example.com/.well-known/oauth-protected-resource. Alternativ kannst du dieselbe URL im Header WWW-Authenticate von Antworten mit dem Status 401 Unauthorized angeben. So weiß ChatGPT, wo es deine Metadaten abrufen kann.
  • Der Endpunkt gibt ein JSON-Dokument zurück, das den Ressourcenserver und die verfügbaren Autorisierungsserver beschreibt:
{
  "resource": "https://your-mcp.example.com",
  "authorization_servers": ["https://auth.yourcompany.com"],
  "scopes_supported": ["files:read", "files:write"],
  "resource_documentation": "https://yourcompany.com/docs/mcp"
}
  • Beachte beim Ausfüllen insbesondere diese Felder:
    • resource: die kanonische HTTPS-Kennung deines MCP-Servers. ChatGPT sendet bei OAuth genau diesen Wert als Abfrageparameter resource.
    • authorization_servers: eine oder mehrere Basis-URLs der Aussteller, die auf deinen Identitätsanbieter verweisen. ChatGPT versucht unter jeder URL, die OAuth-Metadaten abzurufen.
    • scopes_supported: eine optionale Liste, mit der ChatGPT den Nutzenden erklären kann, welche Berechtigungen es anfordern wird.
    • Optionale Angaben aus RFC 9728 wie resource_documentation, resource_policy_uri oder resource_tos_uri helfen Clients und Administrationsteams, deine Konfiguration nachzuvollziehen.

Wenn du eine Anfrage wegen fehlender Authentifizierung blockierst, gib eine Challenge wie diese zurück:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://your-mcp.example.com/.well-known/oauth-protected-resource",
                         scope="files:read"

Dieser eine Header genügt, damit ChatGPT die Metadaten-URL findet, auch wenn sie dem Client bisher unbekannt war.

OAuth-Metadaten auf deinem Autorisierungsserver veröffentlichen

  • Dein Identitätsanbieter muss eines der standardisierten Discovery-Dokumente bereitstellen, damit ChatGPT seine Konfiguration lesen kann:
    • OAuth-2.0-Metadaten unter https://auth.yourcompany.com/.well-known/oauth-authorization-server
    • OpenID-Connect-Metadaten unter https://auth.yourcompany.com/.well-known/openid-configuration
  • Aus jedem dieser Dokumente erfährt der OpenAI-Host, wohin er Nutzende weiterleiten soll, wie er Autorisierungscodes eintauscht und wie er sich selbst identifiziert. Eine typische Antwort sieht so aus:
{
  "issuer": "https://auth.yourcompany.com",
  "authorization_response_iss_parameter_supported": true,
  "authorization_endpoint": "https://auth.yourcompany.com/oauth2/v1/authorize",
  "token_endpoint": "https://auth.yourcompany.com/oauth2/v1/token",
  "client_id_metadata_document_supported": true,
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "registration_endpoint": "https://auth.yourcompany.com/oauth2/v1/register",
  "code_challenge_methods_supported": ["S256"],
  "scopes_supported": ["files:read", "files:write"]
}
  • Diese Felder müssen korrekt sein:
    • issuer: die kanonische Kennung des Autorisierungsservers. Verwende genau diesen Wert in der Liste authorization_servers in den Metadaten der geschützten Ressource.
    • authorization_response_iss_parameter_supported: Setze das Feld nur dann auf true, wenn dein Autorisierungsserver den Parameter iss in jeder Autorisierungsantwort zurückgibt, auch bei Fehlern.
    • authorization_endpoint, token_endpoint: die URLs, die ChatGPT für den vollständigen OAuth-Autorisierungscode-Ablauf mit PKCE benötigt.
    • client_id_metadata_document_supported: Setze das Feld auf true, wenn ChatGPT für die Clientregistrierung CIMD verwenden soll. ChatGPT bevorzugt CIMD, wenn es verfügbar ist. Sind sowohl CIMD als auch DCR verfügbar, kannst du beim Erstellen des Plugins DCR auswählen.
    • token_endpoint_auth_methods_supported: Gib die Authentifizierungsmethoden an, die dein Autorisierungsserver am Token-Endpunkt akzeptiert. Das gilt für CIMD, DCR und vordefinierte OAuth-Clients. Bei CIMD unterstützt ChatGPT none für den Tokenaustausch mit einem öffentlichen Client und private_key_jwt für den Tokenaustausch mit einer signierten Client-Assertion. Andere OAuth-Clients verwenden häufig none, client_secret_post oder client_secret_basic.
    • registration_endpoint: Gib diesen Endpunkt an, wenn du die dynamische Clientregistrierung (DCR) unterstützt. Damit kann ChatGPT eine eigene client_id für die Verbindung zum MCP-Server erstellen und wiederverwenden.
    • code_challenge_methods_supported: Das Feld muss S256 enthalten. MCP-Server werden nicht unterstützt, wenn in den Metadaten ihres Autorisierungsservers dieses Feld fehlt oder S256 nicht als unterstützte Methode angegeben ist. Das schreibt die MCP-Spezifikation zur Autorisierung vor.
    • Für optionale Felder gelten RFC 8414 und OpenID Discovery. Nimm die Angaben auf, die deinem Administrationsteam beim Konfigurieren von Richtlinien helfen.

OIDC-Scopes

  • Wenn dein Anbieter OIDC-Scopes (etwa openid, email und profile) unter scopes_supported in seinem Dokument .well-known/oauth-authorization-server oder .well-known/openid-configuration aufführt, fordert ChatGPT diese Scopes im OAuth-Ablauf standardmäßig an.
  • Manche Identitätsanbieter aktivieren die angegebenen OIDC-Scopes nicht automatisch. Prüfe die Konfiguration deines Anbieters und stelle sicher, dass jeder angegebene Scope für den OAuth-Client aktiviert ist. Das gilt unabhängig davon, ob der Client CIMD verwendet oder manuell oder per DCR erstellt wurde.

Domainbeschränkungen für Workspaces unterstützen

In ChatGPT Enterprise können Organisationen für ihre Workspaces nachweisen, dass ihnen bestimmte E-Mail-Domains gehören. Wenn ein über OAuth verknüpftes Plugin die verifizierte E-Mail-Adresse einer Person bereitstellt, kann ChatGPT anhand der Domain verhindern, dass die Person das Plugin mit ihrer Unternehmensidentität in einem persönlichen Workspace oder einem anderen Workspace außerhalb der Organisation verknüpft.

Konfiguriere deinen Autorisierungsserver wie folgt, um diesen Schutz zu unterstützen:

  • Veröffentliche Discovery-Metadaten für OpenID Connect.
  • Gib die Scopes openid und email als unterstützt an und aktiviere sie.
  • Gib einen UserInfo-Endpunkt an, der den Claim email für die angemeldete Person sowie email_verified: true zurückgibt.

Du kannst diese Claims im OAuth-Ablauf auch in einem ID-Token zurückgeben. Für Domainbeschränkungen in Workspaces ist der UserInfo-Endpunkt jedoch erforderlich.

Die Domain muss auch für den Enterprise-Workspace verifiziert sein. Dein Autorisierungsserver stellt die Identität der angemeldeten Person bereit. ChatGPT gleicht sie mit den verifizierten Domains ab, die für den Workspace konfiguriert sind. Der Autorisierungsserver prüft nicht, ob eine Domain zum Workspace gehört.

Anmeldekontext bei erneuter Autorisierung beibehalten

Wenn ChatGPT eine bestehende Verknüpfung erneut autorisiert, etwa um zusätzliche OAuth-Scopes anzufordern, kann es das bisherige OIDC-ID-Token als Standardparameter id_token_hint in der Autorisierungsanfrage mitsenden. Damit Nutzende zusätzliche Scopes freigeben können, ohne die Anmeldung von vorn zu beginnen, konfiguriere deinen Autorisierungsserver so, dass er im ursprünglichen OAuth-Ablauf ein ID-Token ausstellt und bei der Autorisierung id_token_hint berücksichtigt.

Diese Optimierung ist optional. Die erneute Autorisierung funktioniert auch, wenn kein ID-Token vorliegt oder dein Autorisierungsserver den Hinweis nicht nutzt.

Callbacks durch Identifizierung des Ausstellers schützen

OpenAI-Hosts nutzen die Ausstelleridentifizierung nach RFC 9207, um OAuth-Callbacks vor Angriffen zu schützen, bei denen der Client Autorisierungsserver verwechselt. Damit ChatGPT und Codex beim Erstellen eines geeigneten OAuth-Clients eine stabile Weiterleitungs-URI verwenden können, erfülle folgende Anforderungen:

  • Setze authorization_response_iss_parameter_supported: true in den Metadaten deines Autorisierungsservers.
  • Verwende im Metadatenfeld issuer und in der Liste authorization_servers der geschützten Ressource exakt dieselbe Ausstellerkennung.
  • Gib iss in jeder Autorisierungsantwort zurück, sowohl bei Erfolg als auch bei Fehlern. Der Wert muss exakt mit dem Metadatenfeld issuer übereinstimmen. Clients vergleichen die Zeichenfolgen direkt und vereinheitlichen weder abschließende Schrägstriche noch Pfade, Ports oder Groß- und Kleinschreibung.

ChatGPT und Codex speichern den ausgewählten Metadatenwert issuer, bevor sie die Person weiterleiten. Bevor sie den Autorisierungscode eintauschen, prüfen sie den zurückgegebenen Wert von iss. Gibt der Server an, die Ausstelleridentifizierung zu unterstützen, lässt aber iss weg oder liefert einen abweichenden Wert, lehnen ChatGPT und Codex die Antwort ab. Diese Anforderungen entsprechen den MCP-Regeln zur Validierung von Autorisierungsantworten.

Weiterleitungs-URL

Kopiere die Weiterleitungs-URI für den Produktivbetrieb von der Verwaltungsseite des MCP-Servers exakt in die Zulassungsliste deines Autorisierungsservers.

  • Erfüllt dein Autorisierungsserver die oben genannten Anforderungen zur Ausstelleridentifizierung nicht, verwendet ChatGPT die Weiterleitungs-URI mit der jeweiligen Callback-ID: https://chatgpt.com/connector/oauth/{callback_id}.
  • Erfüllt dein Autorisierungsserver diese Anforderungen, verwendet ChatGPT die stabile Weiterleitungs-URI https://chatgpt.com/connector_platform_oauth_redirect.

MCP-Server, die vor der Einführung von Weiterleitungen mit Callback-ID in ChatGPT veröffentlicht wurden, verwenden ebenfalls weiterhin die stabile Weiterleitungs-URI.

Den Parameter resource im gesamten OAuth-Ablauf weitergeben

  • ChatGPT hängt resource=https%3A%2F%2Fyour-mcp.example.com sowohl an die Autorisierungsanfrage als auch an die Tokenanfrage an. Damit wird das Token der geschützten Ressource zugeordnet, die in den oben gezeigten Metadaten beschrieben ist.
  • Konfiguriere deinen Autorisierungsserver so, dass er diesen Wert in das Zugriffstoken übernimmt, üblicherweise in den Claim aud. So kann dein MCP-Server prüfen, ob das Token ausschließlich für ihn ausgestellt wurde.
  • Lehne Token ohne die erwartete Audience oder die erforderlichen Scopes ab. Fordere ChatGPT mit einer WWW-Authenticate-Challenge auf, die Autorisierung mit den richtigen Parametern zu wiederholen.

Den Autorisierungscode-Ablauf unterstützen

  • Als MCP-Client führt ChatGPT den Autorisierungscode-Ablauf mit PKCE und der Code-Challenge-Methode S256 aus. Wer einen Autorisierungscode abfängt, kann ihn dadurch nicht erneut verwenden.
  • Dein Autorisierungsserver muss code_challenge_methods_supported mit S256 als unterstützter Methode veröffentlichen, damit Clients anhand der Metadaten prüfen können, ob PKCE unterstützt wird.

OAuth-Ablauf

Wenn du die oben beschriebenen MCP-Vorgaben zur Autorisierung umgesetzt hast, läuft OAuth wie folgt ab:

  1. ChatGPT ruft die Metadaten der geschützten Ressource von deinem MCP-Server ab.

  1. ChatGPT identifiziert sich als OAuth-Client. Verwendet der MCP-Server CIMD, überspringt ChatGPT die dynamische Clientregistrierung und sendet die URL eines CIMD-Dokuments als client_id. Für Autorisierungsserver, die die oben genannten Anforderungen zur Ausstelleridentifizierung erfüllen, verwendet ChatGPT die stabile URL https://chatgpt.com/oauth/client.json. Für andere Server nutzt es die URL mit der jeweiligen Callback-ID: https://chatgpt.com/oauth/{callback_id}/client.json. Auf der Verwaltungsseite des MCP-Servers siehst du das genaue Client-Metadatendokument und die Weiterleitungs-URI für den Callback-Modus der Verbindung. Verwendet der MCP-Server DCR, ruft ChatGPT für die Verbindung zum MCP-Server einmal den registration_endpoint deines Autorisierungsservers auf. Es erhält eine generierte client_id und verwendet den Client für diese Verbindung wieder.

Bei CIMD entfällt der Registrierungsschritt. Die folgende Ansicht zeigt den Ablauf mit DCR:

  1. Beim ersten Tool-Aufruf startet der ChatGPT-Client den OAuth-Autorisierungscode-Ablauf mit PKCE. Die Person authentifiziert sich und stimmt den angeforderten Scopes zu.

  1. ChatGPT tauscht den Autorisierungscode gegen ein Zugriffstoken ein und sendet es bei nachfolgenden MCP-Anfragen mit (Authorization: Bearer <token>).

  1. Dein Server prüft bei jeder Anfrage das Token (Aussteller, Audience, Ablaufzeit und Scopes), bevor er das Tool ausführt.

Clientregistrierung

Verwende Client ID Metadata Documents (CIMD) als bevorzugte Methode zur Clientregistrierung, wenn dein Autorisierungsserver sie unterstützt und sie bei der Erstellung des Plugins ausgewählt wurde. Bei CIMD verwendet ChatGPT die HTTPS-URL eines Metadatendokuments als client_id. Dein Autorisierungsserver ruft das Dokument ab, validiert die veröffentlichten Client-Metadaten und Weiterleitungs-URIs und verwendet die URL als stabile Clientidentität von ChatGPT.

Wenn du CIMD unterstützt, setze client_id_metadata_document_supported: true in den Metadaten deines Autorisierungsservers. Damit kann ChatGPT für MCP-Server, die CIMD verwenden, eine einheitliche, stabile Clientidentität nutzen. Dein Autorisierungsserver kann anhand dieser Identität Zulassungslisten für Weiterleitungs-URIs, Ratenlimits und weitere Richtlinien anwenden.

ChatGPT stellt CIMD gemäß dem Vorschlag in MCP SEP-3149 um. Im CIMD-Dokument für den Produktivbetrieb enthält token_endpoint_auth_methods_supported ein Array der Methoden, die ChatGPT verwenden kann. Die Reihenfolge gibt keine Präferenz an. Während der Umstellung veröffentlicht ChatGPT die bevorzugte Methode zusätzlich im bisherigen Feld token_endpoint_auth_method im Singular:

{
  "token_endpoint_auth_methods_supported": ["none", "private_key_jwt"],
  "token_endpoint_auth_method": "private_key_jwt"
}

Das Feld im Plural beschreibt in den beiden Dokumenten unterschiedliche Seiten des Austauschs. In den Metadaten des Autorisierungsservers stehen die Methoden, die dein Token-Endpunkt akzeptiert. Das CIMD-Dokument von ChatGPT nennt die Methoden, die ChatGPT verwenden kann. ChatGPT wählt eine Methode aus der Schnittmenge. Gehört die im bisherigen Singularfeld bevorzugte Methode zur Schnittmenge, verwendet ChatGPT diese Methode. Dadurch bleibt es mit Autorisierungsservern kompatibel, die das Singularfeld weiterhin als verbindlich behandeln. Andernfalls kann ChatGPT eine andere Methode aus der Schnittmenge verwenden.

Autorisierungsserver, die das CIMD-Feld im Plural auswerten, sollten jede Methode aus der Schnittmenge akzeptieren, sofern die lokale Sicherheitsrichtlinie sie für den Client zulässt. Methoden außerhalb der Schnittmenge müssen sie ablehnen. Die URL für client_id bleibt stabil. Sie verwendet keine Abfrageparameter, um ein methodenspezifisches Dokument auszuwählen.

Folgende Methoden werden unterstützt:

  • none: Verwende diesen Ablauf für öffentliche Clients, wenn dein Token-Endpunkt den Austausch von Autorisierungscodes mit PKCE ohne Clientauthentifizierung unterstützt. ChatGPT speichert kein clientspezifisches Geheimnis.
  • private_key_jwt: Verwende diesen Ablauf mit signierter Client-Assertion, wenn dein Token-Endpunkt eine Clientauthentifizierung verlangt. ChatGPT veröffentlicht in seinen CIMD-Metadaten eine öffentliche JWKS-URL. Das JWKS ist unter /oauth/jwks.json auf demselben Origin wie die Metadaten verfügbar. ChatGPT signiert Tokenanfragen serverseitig mit einem verwalteten privaten Schlüssel und gibt dessen kid an. Dein Autorisierungsserver prüft die Assertion anhand des öffentlichen JWKS.

DCR wird weiterhin unterstützt. Wenn du registration_endpoint angibst, kann sich ChatGPT dynamisch registrieren, sofern bei der Erstellung des Plugins DCR ausgewählt wurde oder CIMD nicht verfügbar ist. ChatGPT führt DCR einmal pro Verbindung zum MCP-Server aus. Anschließend behält es den registrierten OAuth-Client und verwendet ihn für diese Verbindung wieder. Bei vielen separaten Verbindungen können mit DCR entsprechend viele registrierte Clients entstehen. Daher lässt sich CIMD in großen Umgebungen meist einfacher verwalten.

Sorge dafür, dass der registrierte OAuth-Client und ein etwaiges Clientgeheimnis gültig bleiben, solange die Verbindung zum MCP-Server genutzt wird. Wenn dein Autorisierungsserver eine dieser Zugangsdaten ablaufen lässt, löscht oder ersetzt, können Nutzende und Prüfende beim Verbindungsaufbau den Fehler invalid_client erhalten. Zugriffs- und Refresh-Token können weiterhin wie gewohnt ablaufen oder rotieren.

Clientidentifizierung

Wie kann dein MCP-Server feststellen, ob eine Anfrage tatsächlich von ChatGPT stammt? Beim Verbindungsaufbau zu MCP-Servern legt ChatGPT ein von OpenAI verwaltetes Clientzertifikat vor. So kannst du den Client auf der Transportschicht mit mTLS verifizieren. Du kannst auch die veröffentlichten IP-Bereiche für ausgehenden Datenverkehr von ChatGPT in deine Zulassungsliste aufnehmen. ChatGPT unterstützt keine OAuth-Verfahren für die Kommunikation zwischen Maschinen, etwa mit Client Credentials, Dienstkonten oder JWT-Bearer-Assertions. Es kann auch keine benutzerdefinierten API-Schlüssel oder kundenseitig bereitgestellten mTLS-Zertifikate vorlegen.

CIMD stärkt die Clientidentifizierung zusätzlich. Dein Autorisierungsserver erhält eine stabile, über HTTPS abrufbare Erklärung zur Identität von ChatGPT. Wenn du private_key_jwt verwendest, prüfe die Client-Assertion von ChatGPT am Token-Endpunkt anhand des öffentlichen JWKS, das in den CIMD-Metadaten angegeben ist.

Gegenseitige TLS-Authentifizierung (mTLS)

ChatGPT legt beim Aufbau von TLS-Verbindungen zu MCP-Servern jetzt ein von OpenAI verwaltetes Clientzertifikat vor. Wenn deine Anwendung Clientzertifikate validiert, konfiguriere sie so, dass sie der folgenden OpenAI-Zertifikatskette vertraut.

So validierst du das Clientzertifikat beim Aufbau der TLS-Verbindung zu deinem MCP-Server:

  • Prüfe, ob ein Endzertifikat vorliegt und seine Zertifikatskette zur OpenAI Connectors mTLS-Zwischenzertifizierungsstelle führt.
  • Prüfe, ob das Endzertifikat für die Clientauthentifizierung gültig ist.
  • Prüfe, ob im SAN des Endzertifikats für dnsName der Wert mtls.prod.connectors.openai.com steht.
  • Lege dich nicht auf den Fingerabdruck eines bestimmten Endzertifikats fest. OpenAI kann das Endzertifikat innerhalb der veröffentlichten Zertifikatskette austauschen.

Authentifiziere ChatGPT mit mTLS als MCP-Client. Verwende weiterhin OAuth 2.1, um die Person zu authentifizieren, die den Client nutzt, und den Zugriff auf Tools zu autorisieren.

Identitätsanbieter auswählen

Die meisten Identitätsanbieter für OAuth 2.1 können die MCP-Anforderungen zur Autorisierung erfüllen, wenn sie ein Discovery-Dokument bereitstellen, CIMD mit none oder private_key_jwt unterstützen, bei Bedarf DCR anbieten und den Parameter resource in die ausgestellten Token übernehmen. Bevorzuge Anbieter, die CIMD für die Clientregistrierung unterstützen.

Wir empfehlen dir ausdrücklich, einen etablierten Identitätsanbieter zu nutzen, anstatt die Authentifizierung von Grund auf selbst zu implementieren.

Hier findest du Anleitungen für einige gängige Identitätsanbieter.

Auth0

Mit Auth0 können MCP-Clients sichere Verbindungen zu MCP-Servern herstellen. Auth0 unterstützt die automatische Ermittlung von Metadaten, die Registrierung mit CIMD, die Absicherung von APIs und den Tokenaustausch für Aufrufe eigener Tools und Tools von Drittanbietern.

Beispiel für einen gehosteten Anbieter (Stytch)

Tokenprüfung implementieren

Nach Abschluss des OAuth-Ablaufs sendet ChatGPT das erhaltene Zugriffstoken direkt mit nachfolgenden MCP-Anfragen (Authorization: Bearer …). Wenn eine Anfrage deinen MCP-Server erreicht, darfst du dem Token zunächst nicht vertrauen. Du bist dafür verantwortlich, alle Prüfungen des Ressourcenservers selbst durchzuführen. Validiere die Signatur, gleiche Aussteller und Audience ab, prüfe die Ablaufzeit, berücksichtige mögliche Replay-Angriffe und setze die Scope-Beschränkungen durch. ChatGPT übernimmt diese Prüfungen nicht für dich.

Gehe dabei wie folgt vor:

  • Rufe die von deinem Autorisierungsserver veröffentlichten Signaturschlüssel ab (üblicherweise per JWKS) und prüfe die Signatur des Tokens sowie iss.
  • Lehne abgelaufene oder noch nicht gültige Token ab (exp/nbf).
  • Prüfe, ob das Token für deinen Server ausgestellt wurde (aud oder der Claim resource) und die von dir als erforderlich angegebenen Scopes enthält.
  • Prüfe alle serverspezifischen Richtlinien. Übernimm anschließend die ermittelte Identität in den Anfragekontext oder gib 401 mit einer WWW-Authenticate-Challenge zurück.

Schlägt die Prüfung fehl, antworte mit 401 Unauthorized und einem WWW-Authenticate-Header, der auf die Metadaten deiner geschützten Ressource verweist. Damit forderst du den Client auf, den OAuth-Ablauf zu wiederholen.

SDK-Hilfsfunktionen zur Tokenprüfung

Die MCP-SDKs für Python und TypeScript enthalten Hilfsfunktionen, damit du die Tokenprüfung nicht von Grund auf selbst implementieren musst.

Mehrere Konten unterstützen

Nutzende können mehrere Konten mit demselben Plugin verbinden, etwa ein privates und ein berufliches Konto. OpenAI leitet jeden Tool-Aufruf mit den authentifizierten Zugangsdaten der ausgewählten Verbindung weiter. Mehrere Konten lassen sich auch ohne Profil-Tool verbinden. Stelle ein authentifiziertes Profil-Tool mit einer stabilen ID und aussagekräftigen Anzeigemetadaten bereit, damit Nutzende die Verbindungen unterscheiden und dasselbe Profil nach einer erneuten Verbindung wiedererkennen können.

So nutzen Personen mehrere Konten

Über die Einstellungsseite des Plugins lassen sich weitere Konten verbinden. Dem Modell stehen alle verbundenen Konten zur Verfügung. Beim Aufruf von Tools wählt es anhand der Anfrage das passende Konto oder mehrere passende Konten aus. Jeder Tool-Aufruf verwendet die Zugangsdaten und Berechtigungen des ausgewählten Kontos.

Konten leichter identifizieren

Damit OpenAI verbundene Profile erkennt und aussagekräftige Bezeichnungen anzeigen kann, gehe wie folgt vor:

  • Stelle ein authentifiziertes Profil-Tool bereit, das eine opake ID zurückgibt. Die ID muss das Profil, zu dem die Zugangsdaten der Anfrage gehören, eindeutig und dauerhaft identifizieren. So kann OpenAI dasselbe Profil bei erneuten Verbindungen wiedererkennen und von anderen Profilen unterscheiden. Ein Feld namens id eignet sich dafür nur, wenn sein Wert diese Anforderungen erfüllt.
  • Kennzeichne das Profil-Tool in den MCP-Metadaten. So kann OpenAI ermitteln, welches Tool authentifizierte Profilinformationen liefert.

Wenn OpenAI Profilinformationen benötigt, ermittelt es das gekennzeichnete Tool zur Laufzeit, ruft es mit den Zugangsdaten der Verbindung auf und validiert die Antwort, bevor es die Profildaten verwendet. Ohne Profil-Tool lassen sich Konten weiterhin verbinden. Die Kontobezeichnungen, die Wiedererkennung von Konten oder die Erkennung von Duplikaten können jedoch weniger zuverlässig sein. Wenn du ein Profil-Tool deklarierst, muss es eine gültige Identität zurückgeben. Eine ungültige Antwort kann den Verbindungsaufbau verhindern.

Eine stabile Profilidentität definieren

Ein Profil bezeichnet die Identität, die durch die authentifizierten Zugangsdaten der Anfrage ausgewiesen wird. Dein Dienst legt fest, welche Profile unabhängig voneinander verbunden werden können. Die Vorgaben für Profile schreiben deinem Dienst weder ein Organisations- noch ein Autorisierungsmodell vor.

Gib eine opake Profil-ID zurück, die innerhalb deiner App eindeutig ist. Dasselbe Profil muss seine ID behalten, wenn ein Token erneuert oder die Verbindung erneut hergestellt wird. Unterschiedliche Profile müssen unterschiedliche IDs haben. OpenAI vergleicht diese IDs, ohne ihren Inhalt zu interpretieren.

Verwende eine vorhandene unveränderliche, opake ID deines Anbieters, wenn sie das vollständige Profil identifiziert. Andernfalls vergib einmalig eine opake ID, speichere ihre Zuordnung zum Profil dauerhaft und rufe bei späteren Anfragen dieselbe ID ab. Verwalte interne Beziehungen innerhalb deines Dienstes. Kodiere weder Namen noch E-Mail-Adressen noch organisatorische Beziehungen in der zurückgegebenen ID.

Für deine id gilt:

  • Sie muss eine Zeichenfolge sein, die mindestens ein Zeichen enthält, das kein Leerraumzeichen ist. Serialisiere numerische Anbieter-IDs als Zeichenfolgen.
  • Sie muss für dasselbe Profil bei einer Tokenerneuerung, einer erneuten Verbindung und einer Erweiterung der Scopes gleich bleiben.
  • Jedes eigenständig über die App verbindbare Profil muss eine eigene ID haben.
  • Sie muss unverändert bleiben, wenn sich E-Mail-Adresse, Name oder Anzeigebezeichnung des Profils ändern.
  • Sie darf nach dem Löschen eines Profils niemals einem anderen Profil zugewiesen werden.

Generiere nicht für jede Anmeldung, jedes Token, jede Sitzung oder jeden Tool-Aufruf eine neue ID. Speichere die E-Mail-Adresse und bearbeitbare Namen in den Anzeigemetadaten. Eine E-Mail-Adresse, die sich ändern oder neu vergeben werden kann, eignet sich nicht als stabile Profil-ID. Verwende bei Google OIDC den stabilen Claim sub anstelle des E-Mail-Claims. Laut Google kann sich die E-Mail-Adresse ändern, während sub unverändert bleibt und niemals neu vergeben wird. Weitere Informationen findest du in der Dokumentation von Google zur Identität.

Behalte vorhandene Profil-IDs bei, wenn du deine Integration aktualisierst. Ein geänderter Anzeigename, ein neues Token oder eine neue Verbindung dürfen keine neue Profilidentität erzeugen.

Profil-Tool implementieren und deklarieren

Stelle ein authentifiziertes Tool ohne Schreibzugriff bereit, das ein leeres Argumentobjekt akzeptiert und das aktuelle Profil zurückgibt. Das Tool kann get_profile, whoami oder anders heißen. Anhand seiner Metadaten lässt es sich zur Laufzeit als Profil-Tool erkennen. Die Antwort muss die folgenden Identitätsanforderungen erfüllen, damit OpenAI sie korrekt verwenden kann.

  • Ermittle die Identität anhand der validierten Zugangsdaten der Anfrage.
  • Stelle sicher, dass der Vorgang ohne Schreibzugriff auskommt und mit den üblichen Berechtigungen der Verbindung verfügbar ist.
  • Gib genau ein Profil zurück, und zwar das Profil, zu dem die Zugangsdaten der aktuellen Anfrage gehören.
  • Verlange beim Aufruf weder eine Benutzer-ID noch eine E-Mail-Adresse noch eine Angabe zur Kontoauswahl.
  • Schlägt die Authentifizierung fehl, gib den passenden Authentifizierungsfehler zurück. Verwende weder eine Platzhalter-ID noch das Profil eines anderen Kontos.

Die Profilantwort muss diesem JSON Schema entsprechen:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "minLength": 1,
      "pattern": "\\S",
      "description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
    },
    "name": {
      "type": "string",
      "description": "Display name for the authenticated profile."
    },
    "email": {
      "type": "string",
      "description": "Email address for display; not used as the profile identity."
    },
    "nickname": {
      "type": "string",
      "description": "A useful label that helps users distinguish connected profiles."
    }
  },
  "required": ["id"],
  "additionalProperties": false
}

Die Antwort muss für id eine Zeichenfolge enthalten, die weder leer ist noch ausschließlich aus Leerraumzeichen besteht. Die Anzeigefelder sind optional. Aus den Metadaten des Tools erfährt OpenAI, wo es Profilinformationen abrufen kann. Die Antwort identifiziert das Profil, zu dem die aktuellen Zugangsdaten gehören.

Die Schemavalidierung prüft, ob Struktur und Feldtypen der Antwort für die Verarbeitung des Profils geeignet sind. Dein Dienst muss außerdem sicherstellen, dass die ID eindeutig und stabil ist und zu den Zugangsdaten der Anfrage gehört. Weder die Metadaten noch eine erfolgreiche Schemaprüfung weisen diese Eigenschaften nach.

Gib name, email und/oder nickname an, sofern sie verfügbar sind, damit Nutzende ihre Profile unterscheiden können. Lass optionale Werte weg, wenn sie nicht vorliegen. Erfinde keine Werte und ergänze keine sachfremden personenbezogenen Daten. Verwende für verständliche Zusatzinformationen das Feld nickname und halte die ID davon frei.

Kennzeichne das Tool mit _meta["openai/profile"]: true und veröffentliche das Schema der Profilantwort als outputSchema des Tools. Die Kennzeichnung teilt OpenAI mit, welches Tool Profilinformationen liefert. Sie aktiviert weder die Funktion noch erteilt sie eine Zugangsberechtigung. Fehlt die Kennzeichnung oder hat sie den booleschen Wert false, ist das Tool über diesen Mechanismus nicht als Profilquelle ausgewiesen. Zeichenfolgen, Zahlen und null sind als Werte für die Kennzeichnung ungültig.

{
  "name": "get_profile",
  "description": "Return the profile represented by this request's authenticated credentials. The opaque id is unique within this app and remains unchanged across token refresh, reconnection, and display-metadata changes.",
  "inputSchema": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "outputSchema": {
    "$schema": "https://json-schema.org/draft/2020-12/schema",
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "minLength": 1,
        "pattern": "\\S",
        "description": "Opaque profile identifier, unique within this app and unchanged across token refresh, reconnection, and display-metadata changes. Never reassigned to another profile."
      },
      "name": {
        "type": "string",
        "description": "Display name for the authenticated profile."
      },
      "email": {
        "type": "string",
        "description": "Email address for display; not used as the profile identity."
      },
      "nickname": {
        "type": "string",
        "description": "A useful label that helps users distinguish connected profiles."
      }
    },
    "required": ["id"],
    "additionalProperties": false
  },
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false
  },
  "securitySchemes": [
    {
      "type": "oauth2",
      "scopes": []
    }
  ],
  "_meta": {
    "openai/profile": true
  }
}

Wenn der Profilzugriff bestimmte OAuth-Scopes erfordert, gib die tatsächlichen Scopes deiner Integration an. Die Deklaration allein authentifiziert keine Anfragen. Der Server muss die Zugangsdaten validieren und die Berechtigungen durchsetzen. Weitere Informationen findest du im Abschnitt Tokenprüfung implementieren und in der Tool-Referenz.

Gib das Profil in structuredContent zurück, damit es anhand von outputSchema validiert werden kann. Gib aus Kompatibilitätsgründen dasselbe Profil zusätzlich als serialisiertes JSON in einem Textelement zurück:

{
  "content": [
    {
      "type": "text",
      "text": "{\"id\":\"prf_8d7e4b19\",\"name\":\"Alex Chen\",\"email\":\"alex@example.com\",\"nickname\":\"Alex — Moonwaffle work\"}"
    }
  ],
  "structuredContent": {
    "id": "prf_8d7e4b19",
    "name": "Alex Chen",
    "email": "alex@example.com",
    "nickname": "Alex — Moonwaffle work"
  },
  "isError": false
}

Verwende ein einzelnes JSON-Objekt mit den Profilfeldern auf der obersten Ebene.

Du hast bereits ein Profil-Tool? Behalte seinen Namen bei, ergänze die Deklaration in den Metadaten und gib die standardisierte Profilantwort zurück. Hat deine bisherige Antwort eine andere Struktur, passe sie auf deinem Server an oder stelle ein kleines Wrapper-Tool bereit, das dem Schema entspricht. Die Standardintegration verwendet für jede App dieselbe Deklaration und dieselbe Antwortstruktur.

Beispiel für dauerhaft gespeicherte Profile bei Moonwaffle

Angenommen, Alex kann beim fiktiven Dienst Moonwaffle zwei Profile unabhängig voneinander verbinden. Moonwaffle speichert für jedes Profil eine eigene opake ID. Anhand der Zugangsdaten einer Anfrage wird eines der gespeicherten Profile ermittelt. Das Profil-Tool gibt dessen bestehende ID zurück.

Beispiele für gespeicherte Profile. Die Bezeichnungen können sich ändern, die Kennungen bleiben gleich:

Alex — Moonwaffle personal: prf_42a9c6e0
Alex — Moonwaffle work:     prf_8d7e4b19

Die Beispiel-IDs enthalten weder Profilbezeichnungen noch Informationen zu internen Beziehungen. Sie werden einmal pro Profil gespeichert und bei erneuter Verbindung, Tokenerneuerung sowie Änderungen der E-Mail-Adresse oder des Anzeigenamens wiederverwendet.

Erstelle die Antwort aus dem authentifizierten Profil. Dieses TypeScript-Beispiel zeigt die Logik eines Handlers, den du in dein MCP-SDK einbinden kannst. loadAuthenticatedProfile ist Teil des Integrationscodes deiner Anwendung. Die Funktion validiert die Zugangsdaten der Anfrage, setzt die zugehörigen Berechtigungen durch und ruft die gespeicherte ID und die Anzeigemetadaten des entsprechenden Profils ab. requestContext stammt aus der Anfrageverarbeitung deines Servers. Das Modell übergibt diesen Kontext nicht als Tool-Argument.

async function getProfile(requestContext: { token: string }) {
  // Your auth/provider integration validates credentials and loads
  // the existing profile. Auth failures use normal MCP auth handling.
  const account = await loadAuthenticatedProfile(requestContext);
  const id = account.profileId;

  if (typeof id !== "string" || id.trim().length === 0) {
    return {
      isError: true,
      content: [{ type: "text", text: "Profile identity unavailable." }],
    };
  }

  // Return the persisted ID unchanged; do not generate an ID per call.
  const profile = {
    id,
    ...(typeof account.name === "string" ? { name: account.name } : {}),
    ...(typeof account.email === "string" ? { email: account.email } : {}),
    ...(typeof account.nickname === "string"
      ? { nickname: account.nickname }
      : {}),
  };

  return {
    isError: false,
    structuredContent: profile,
    content: [{ type: "text", text: JSON.stringify(profile) }],
  };
}

Registriere diesen Handler mit der oben gezeigten Metadatendeklaration und den zugehörigen Eingabe- und Ausgabeschemas. loadAuthenticatedProfile muss für gleichwertige Zugangsdaten und nach einer erneuten Verbindung dasselbe gespeicherte Profil ermitteln. Die Funktion darf nicht für jede OAuth-Freigabe oder Sitzung eine neue Profil-ID erzeugen. Alle anderen Tools müssen die Zugangsdaten der Anfrage verwenden, um die Berechtigungen desselben Profils durchzusetzen.

Prüfe, ob die Profilidentität erhalten bleibt:

Test Erwartetes Ergebnis
Mehrere Aufrufe für das berufliche Moonwaffle-Profil Jedes Mal prf_8d7e4b19
Dasselbe Profil nach Tokenerneuerung, erneuter Verbindung oder Erweiterung der Scopes prf_8d7e4b19
Dasselbe Profil nach einer Änderung der E-Mail-Adresse oder der Anzeigebezeichnung prf_8d7e4b19, die Bezeichnungen dürfen sich ändern
Privates Moonwaffle-Profil prf_42a9c6e0, eine andere ID als die des beruflichen Profils
Die gespeicherte Profil-ID fehlt, ist leer oder besteht nur aus Leerraumzeichen Fehlerergebnis, ohne eine Identität zu erfinden oder auf ein anderes Profil auszuweichen

Dein Dienst muss diese Identitätsgarantie für alle Profile und auch bei künftigen Änderungen der Integration einhalten. Sie muss unabhängig von Anzeigemetadaten, Tokeninhalten und dem Zustand der Verbindung bestehen bleiben.

Tests und Einführung

  • Lokale Tests: Beginne mit einem Entwicklungsmandanten, der kurzlebige Token ausstellt, damit du Änderungen schnell testen kannst.
  • Interner Test: Sobald die Authentifizierung funktioniert, beschränke den Zugriff zunächst auf vertrauenswürdige Testpersonen, bevor du ihn allgemein freigibst. Du kannst eine Kontoverknüpfung für einzelne Tools oder den gesamten MCP-Server voraussetzen.
  • Rotation: Plane den Widerruf und die Erneuerung von Token sowie Änderungen der Scopes ein. Dein Server sollte Anfragen mit fehlenden oder veralteten Token als nicht authentifiziert behandeln und eine aussagekräftige Fehlermeldung zurückgeben.
  • OAuth-Fehlersuche: Gehe vor der Veröffentlichung in den Authentifizierungseinstellungen des MCP Inspector jeden OAuth-Schritt durch. So kannst du genau feststellen, an welcher Stelle der Ablauf scheitert.

Mit eingerichteter Authentifizierung kannst du Nutzenden in ChatGPT und Codex Zugriff auf nutzerspezifische Daten und auf Schreibaktionen geben.

Authentifizierungsoberfläche auslösen

ChatGPT zeigt die Oberfläche zur OAuth-Kontoverknüpfung nur an, wenn dein MCP-Server signalisiert, dass OAuth verfügbar oder erforderlich ist.

Um den OAuth-Ablauf für ein Tool auszulösen, brauchst du sowohl Metadaten (securitySchemes und das Metadatendokument der Ressource) als auch Laufzeitfehler, die _meta["mcp/www_authenticate"] enthalten. Fehlt eine dieser Voraussetzungen, zeigt ChatGPT für das Tool keine Oberfläche zur Kontoverknüpfung an.

  1. Veröffentliche die Ressourcenmetadaten. Der MCP-Server muss seine OAuth-Konfiguration unter einer standardisierten URL wie https://your-mcp.example.com/.well-known/oauth-protected-resource bereitstellen.

  2. Beschreibe die Authentifizierungsrichtlinie jedes Tools mit securitySchemes. Wenn du securitySchemes für jedes Tool einzeln deklarierst, erkennt ChatGPT, welche Tools OAuth erfordern und welche sich anonym ausführen lassen. Behalte die Deklaration pro Tool auch dann bei, wenn für den gesamten Server dieselbe Richtlinie gilt. Serverweite Standardwerte erschweren spätere Änderungen an einzelnen Tools.

    Derzeit stehen zwei Schematypen zur Verfügung. Du kannst mehrere angeben, um die Authentifizierung optional zu machen:

    • noauth: Das Tool lässt sich anonym aufrufen. ChatGPT kann es sofort ausführen.
    • oauth2: Das Tool benötigt ein OAuth-2.0-Zugriffstoken. Gib die Scopes an, die du anfordern wirst, damit der Zustimmungsdialog die richtigen Berechtigungen anzeigt.

    Lässt du das Array ganz weg, übernimmt das Tool den vom Server angegebenen Standardwert. Deklarierst du sowohl noauth als auch oauth2, kann ChatGPT zunächst anonyme Aufrufe ausführen. Durch die Kontoverknüpfung werden Funktionen mit erweiterten Berechtigungen verfügbar. Unabhängig von den Angaben für den Client muss dein Server bei jedem Aufruf weiterhin Token, Scopes und Audience prüfen.

    Beispiel mit dem TypeScript-SDK (öffentliches Tool mit optionaler Authentifizierung)

    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { z } from "zod";
    
    const server = new McpServer({ name: "auth-example", version: "1.0.0" });
    
    server.registerTool(
      "search",
      {
        title: "Public Search",
        description: "Search public documents.",
        inputSchema: {
          q: z.string(),
        },
        outputSchema: {},
        _meta: {
          securitySchemes: [
            { type: "noauth" },
            { type: "oauth2", scopes: ["search.read"] },
          ],
        },
      },
      async ({ q }) => {
        return {
          content: [{ type: "text", text: `Results for ${q}` }],
          structuredContent: {},
        };
      }
    );

    Beispiel mit dem TypeScript-SDK (Authentifizierung erforderlich)

    import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
    import { z } from "zod";
    
    const server = new McpServer({ name: "auth-example", version: "1.0.0" });
    
    server.registerTool(
      "create_doc",
      {
        title: "Create Document",
        description: "Make a new doc in your account.",
        inputSchema: {
          title: z.string(),
        },
        outputSchema: {},
        _meta: {
          securitySchemes: [{ type: "oauth2", scopes: ["docs.write"] }],
        },
      },
      async ({ title }) => {
        return {
          content: [{ type: "text", text: `Created doc: ${title}` }],
          structuredContent: {},
        };
      }
    );
  3. Prüfe die Token im Tool-Handler und gib _meta["mcp/www_authenticate"] zurück, wenn ChatGPT die Authentifizierungsoberfläche anzeigen soll. Prüfe beim Token den Aussteller, die Audience, die Ablaufzeit und die Scopes. Liegt kein gültiges Token vor, gib ein Fehlerergebnis mit _meta["mcp/www_authenticate"] zurück. Stelle sicher, dass der Wert die beiden Parameter error und error_description enthält. Sobald du die Schritte 1 und 2 umgesetzt hast, löst diese WWW-Authenticate-Nutzlast die OAuth-Oberfläche für das Tool aus. Fordert eine Challenge zur erneuten Autorisierung auf, kann dein Anbieter dabei den bestehenden Anmeldekontext der Person beibehalten.

    Beispiel

    {
      "jsonrpc": "2.0",
      "id": 4,
      "result": {
        "content": [
          {
            "type": "text",
            "text": "Authentication required: no access token provided."
          }
        ],
        "_meta": {
          "mcp/www_authenticate": [
            "'Bearer resource_metadata=\"https://your-mcp.example.com/.well-known/oauth-protected-resource\", error=\"insufficient_scope\", error_description=\"You need to login to continue\"'"
          ]
        },
        "isError": true
      }
    }