OAuth 2.1

OAuth 2.1 (ChatGPT Apps SDK, MCP-Clients)

OAuth-2.1-Autorisierungsserver mit PKCE-S256, Dynamic Client Registration (RFC 7591) und Discovery-Metadaten (RFC 8414 und RFC 9728). Wird vom ChatGPT Apps SDK und von jedem anderen MCP-Client verwendet, der OAuth unterstützt. In allen Tarifen für die MCP-Ressource unter /api/v1/mcp verfügbar. Die mit RS256 signierten JWT-Zugriffstoken und das wiederverwendbare Aktualisierungstoken haben eine gemeinsame, feste Ablauffrist: ein Jahr ab der Autorisierung.

OAuth 2.1 im Überblick

Verwenden Sie OAuth 2.1, wenn Ihr Client für jede Person einzeln delegierten Zugriff auf den MCP-Endpunkt benötigt und Sie keinen API-Schlüssel mitliefern können (z. B. bei einem mandantenfähigen KI-Assistenten). Verwenden Sie API-Schlüssel, wenn Sie beide Seiten kontrollieren und eine einfachere Integration wünschen (ab Tarif Scale). MCP per OAuth ist in allen Tarifen verfügbar, auch in der kostenlosen Testphase.

Endpunkte: /oauth/authorize, /oauth/token, /oauth/register, /oauth/jwks.json, /.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource.

GET/.well-known/oauth-authorization-server

Metadaten des Autorisierungsservers unter /.well-known/oauth-authorization-server (RFC 8414) und Metadaten der geschützten Ressource unter /.well-known/oauth-protected-resource (RFC 9728). Das JWKS zur Prüfung der Signaturen von Zugriffstoken liegt unter /oauth/jwks.json. Clients sollten diese Metadaten abrufen, um die Endpunkte für Autorisierung, Token und Registrierung zu ermitteln, und diese Endpunkte nie fest im Code hinterlegen.

Keine Parameter. Liefert JSON mit issuer, authorization_endpoint, token_endpoint, registration_endpoint, jwks_uri, scopes_supported, code_challenge_methods_supported und weiteren zugehörigen Metadaten.

POST/oauth/register

Dynamic Client Registration nach RFC 7591. Erfordert keine Authentifizierung und ist auf 5 Anfragen pro Stunde und IP-Adresse begrenzt. Gespeichert werden nur Felder aus RFC 7591 (zusätzliche Felder werden verworfen). Weiterleitungs-URIs müssen HTTPS (beliebiger Host) oder HTTP über Loopback (localhost / 127.0.0.1) verwenden; benutzerdefinierte Schemata wie javascript:, data: oder file: werden abgelehnt. Höchstens 10 Weiterleitungs-URIs pro Client; client_name ist auf 200 Zeichen begrenzt, URIs auf 2.048 Zeichen.

JSON-Anfragetext: redirect_uris (erforderlich, Array), client_name, grant_types (standardmäßig authorization_code refresh_token), token_endpoint_auth_method (none für öffentliche PKCE-Clients, client_secret_post für vertrauliche Clients), scope.

GET/oauth/authorize

Zeigt in der App einen Zustimmungsbildschirm an. Erlaubt die Person den Zugriff, wird sie mit einem nur einmal verwendbaren code (10 Minuten gültig) und dem ursprünglichen state an redirect_uri zurückgeleitet. PKCE-S256 ist Pflicht; Code-Challenges mit plain werden abgelehnt.

Parameter: response_type=code (erforderlich), client_id (erforderlich), redirect_uri (erforderlich, muss exakt einer registrierten URI entsprechen), code_challenge (erforderlich), code_challenge_method=S256 (erforderlich), scope (durch Leerzeichen getrennt: mcp:read mcp:write), state, resource (Ressourcenindikator nach RFC 8707).

POST/oauth/token

Tauscht einen Autorisierungscode gegen ein Zugriffstoken und ein Aktualisierungstoken ein oder aktualisiert ein Zugriffstoken. Verwendet application/x-www-form-urlencoded. Auf 60 Anfragen pro Minute und IP-Adresse begrenzt. Bei einer Aktualisierung wird dasselbe wiederverwendbare Aktualisierungstoken zurückgegeben, und alle Zugangsdaten verlieren mit Ablauf der festen Frist von einem Jahr ab der Autorisierung ihre Gültigkeit.

Anfragetext: grant_type (authorization_code oder refresh_token), client_id (erforderlich), client_secret (erforderlich für vertrauliche Clients) sowie entweder {code, code_verifier, redirect_uri} ODER {refresh_token, optional scope zum Einschränken des Zugriffsumfangs}.

Zugriffsumfang & Audience-Prüfung

mcp:read (Standard) gewährt Zugriff auf lesende Tools. mcp:write ist für schreibende Tools erforderlich, darunter create_prompts, create_intelligence_task, create_competitor, create_collection, assign_prompt_tags, create_annotation, update_intelligence_task_content, revert_intelligence_task_content, launch_recommendations, create_technical_geo_report, update_technical_geo_report_content und revert_technical_geo_report_content. Rufen Sie nach dem Verbinden tools/list auf, um zu sehen, welche Tools für das Token verfügbar sind. Ein Token, das nur mit mcp:read ausgestellt wurde, kann keine schreibenden Tools aufrufen: tools/list blendet sie aus, und ein direkter Aufruf von tools/call gibt einen Fehler zurück. Ein Token ohne mcp:read kann keine lesenden Tools nutzen, auch nicht mit mcp:write. Der Claim aud des JWT muss der veröffentlichten URL der MCP-Ressource, der Basis-URL des angefragten Hosts, dem Issuer des Autorisierungsservers oder diesem Issuer mit /api/v1/mcp entsprechen. Wird kein Ressourcenindikator übergeben, wird der Issuer verwendet; jede andere Audience wird von /api/v1/mcp abgelehnt.

Beim Aktualisieren eines Tokens können Sie optional einen engeren Zugriffsumfang in scope übergeben; ein umfassenderer Zugriffsumfang als bei der ursprünglichen Autorisierung führt zu invalid_grant.