Anmeldung mit OAuth

Ein KI-Assistent meldet sich bei Setherion mit OAuth statt mit einem API-Schlüssel an: Die Person klickt auf einer Setherion-Seite auf Allow, und der Assistent erhält ein Token. Diese Seite ist der Vertrag für den Bau eines eigenen Clients. Wenn Sie nur Claude, ChatGPT, Cursor oder VS Code verbinden möchten, folgen Sie MCP: einen KI-Assistenten verbinden.

Der Ablauf ist OAuth 2.1, so wie ihn die MCP-Autorisierungsspezifikation (2025-06-18) verlangt:

• der Authorization-Code-Flow, bei dem PKCE (S256) immer erforderlich ist;
• nur öffentliche Clients, ohne Client-Secret;
• dynamische Client-Registrierung (RFC 7591), sodass niemand irgendwo eine Client-ID einfügen muss;
• Token, die an eine einzige Ressource gebunden sind, den MCP-Endpunkt (RFC 8707).

Die Token funktionieren am MCP-Server und nirgendwo sonst. Die REST-Endpunkte dieser Referenz verlangen einen API-Schlüssel.

1. Discovery

Senden Sie eine Anfrage an den MCP-Endpunkt ohne Zugangsdaten. Das 401 verweist in seinem Header WWW-Authenticate auf die Ressourcen-Metadaten (RFC 9728):

curl https://www.setherion.com/.well-known/oauth-protected-resource/api/mcp

{
  "resource": "https://www.setherion.com/api/mcp",
  "authorization_servers": ["https://www.setherion.com"],
  "bearer_methods_supported": ["header"],
  "scopes_supported": ["mcp"],
  "resource_name": "Setherion"
}

Dasselbe Dokument liegt unter /.well-known/oauth-protected-resource. Lesen Sie dann die Metadaten des Autorisierungsservers (RFC 8414):

curl https://www.setherion.com/.well-known/oauth-authorization-server

{
  "issuer": "https://www.setherion.com",
  "authorization_endpoint": "https://www.setherion.com/oauth/authorize",
  "token_endpoint": "https://www.setherion.com/api/oauth/token",
  "registration_endpoint": "https://www.setherion.com/api/oauth/register",
  "response_types_supported": ["code"],
  "grant_types_supported": ["authorization_code", "refresh_token"],
  "code_challenge_methods_supported": ["S256"],
  "token_endpoint_auth_methods_supported": ["none"],
  "scopes_supported": ["mcp"]
}

Beide Dokumente, die Registrierung und der Token-Endpunkt antworten jedem Origin (Access-Control-Allow-Origin: *), sodass ein Client in einer Browserseite sie aufrufen kann.

2. Registrieren

Registrieren Sie sich einmal pro Installation. Die Registrierung gewährt für sich genommen nichts: Eine Person muss weiterhin auf Allow klicken, und der Code wird nur an die genau hier registrierten Adressen zurückgesendet.

curl -X POST https://www.setherion.com/api/oauth/register \
  -H "Content-Type: application/json" \
  -d '{ "client_name": "My assistant", "redirect_uris": ["http://localhost:8787/callback"] }'

Eine Redirect-Adresse muss https sein oder http zurück zu diesem Rechner (localhost, 127.0.0.1 oder [::1]). Sie darf kein Fragment und keinen Benutzernamen enthalten. Die eine Adresse, die weder https noch http ist, lautet cursor://anysphere.cursor-mcp/oauth/callback, für ältere Cursor-Apps.

Welche Authentifizierungsmethode ein Client auch verlangt, er wird als öffentlicher Client ohne Secret registriert, und die Antwort sagt das:

{
  "client_id": "5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30",
  "client_id_issued_at": 1790000000,
  "client_name": "My assistant",
  "redirect_uris": ["http://localhost:8787/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Der Status ist 201. Registrierungen sind auf 20 pro Stunde und Netzwerkadresse begrenzt.

3. Die Person fragen

Öffnen Sie den Autorisierungs-Endpunkt im Browser der Person. Er ist eine Seite, keine API: Die Person meldet sich bei Setherion an, falls sie es nicht schon ist, sieht den Namen, den Sie registriert haben, und wohin sie zurückgeleitet wird, und klickt auf Allow oder Cancel.

https://www.setherion.com/oauth/authorize
  ?response_type=code
  &client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30
  &redirect_uri=http%3A%2F%2Flocalhost%3A8787%2Fcallback
  &code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
  &code_challenge_method=S256
  &state=af0ifjsldkj
  &resource=https%3A%2F%2Fwww.setherion.com%2Fapi%2Fmcp

Bilden Sie den Verifier aus 43 bis 128 Zeichen von A-Z a-z 0-9 - . _ ~ und behalten Sie ihn bis Schritt 4.

Die Person wird zu Ihrer redirect_uri zurückgeleitet, mit:

• bei Allow: code, state und iss (der Issuer);
• bei Cancel: error=access_denied, error_description=The request was declined., state und iss;
• bei einem Problem mit der Anfrage, sobald feststeht, dass Client und Adresse echt sind: error, error_description, state und iss. Der error ist unsupported_response_type, invalid_request (PKCE fehlt, oder die Methode ist nicht S256) oder invalid_target (die Ressource ist nicht der MCP-Endpunkt).

Ist der Client unbekannt oder die Adresse keine, die er registriert hat, sagt die Seite das der Person und schickt niemanden irgendwohin, sodass diese Seite nie benutzt werden kann, um jemanden an eine Adresse weiterzuleiten, die Sie nicht registriert haben.

4. Den Code eintauschen

Senden Sie formularkodierte Felder, wie OAuth es vorgibt. JSON mit denselben Namen wird ebenfalls akzeptiert.

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=authorization_code \
  -d code=stc_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30 \
  -d redirect_uri=http://localhost:8787/callback \
  -d code_verifier=YOUR_VERIFIER

{
  "access_token": "sto_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scope": "mcp"
}

Senden Sie das Access-Token an den MCP-Server als Authorization: Bearer sto_.... Token werden nie zwischengespeichert: Die Antwort trägt Cache-Control: no-store.

5. Erneuern

Ein Access-Token gilt eine Stunde. Bevor es abläuft, oder wenn der MCP-Server mit 401 antwortet, tauschen Sie das Refresh-Token ein:

curl -X POST https://www.setherion.com/api/oauth/token \
  -d grant_type=refresh_token \
  -d refresh_token=str_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -d client_id=5f0c2a9d-4e30-4d7f-b8a5-6f1c2a9d4e30

Die Antwort ist dieselbe wie in Schritt 4, mit einem neuen Refresh-Token. Das alte funktioniert nicht mehr, speichern Sie also jedes Mal das neue.

Fehler

Jeder Fehler des Token-Endpunkts hat den Status 400, außer server_error, und den Body { "error": "...", "error_description": "..." }.

Eine Verbindung beenden

Die Person kann einen Assistenten unter Settings, dann AI assistants and MCP trennen. Jedes Token dieser Verbindung, Access und Refresh, funktioniert bei der allerersten folgenden Anfrage nicht mehr, nicht erst, wenn die Stunde abläuft. Verbindungen aufzulisten und zu beenden ist nur aus einer angemeldeten Setherion-Sitzung möglich, sodass nichts, was ein Assistent besitzt, es tun kann.

Stattdessen einen API-Schlüssel verwenden

Ein Client, der nur einen festen Header senden kann, kann all das überspringen und einen API-Schlüssel an den MCP-Server senden. Siehe Authentifizierung.