Zum Hauptinhalt springen

Autorisierung

Diese Seite richtet sich an Entwickler, die einen MCP-Client erstellen oder Fehler darin untersuchen. Wenn Sie nur einen bestehenden Client verbinden möchten, siehe Client verbinden.

NameBeta folgt der MCP-Autorisierungsspezifikation: Der MCP-Endpunkt ist ein OAuth-2.1-Ressourcenserver, und der Kontodienst von NameBeta unter auth.namebeta.com ist der Autorisierungsserver. Nutzer melden sich mit ihrem NameBeta-Konto an; es gibt keine API-Schlüssel.

Überblick​

ElementWert
Ressourcehttps://namebeta.com/api/mcp
Protected Resource Metadata (PRM)https://namebeta.com/.well-known/oauth-protected-resource/api/mcp
Autorisierungsserver (Issuer)https://auth.namebeta.com/oidc
Client-RegistrierungClient ID Metadata Documents (CIMD) oder Vorabregistrierung. Kein DCR
GrantAutorisierungscode mit PKCE (S256)
Scopesprofile email. Es gibt keinen API-Scope
TokenJWT, gesendet als Authorization: Bearer <token>

Ablauf​

Client                         namebeta.com                 auth.namebeta.com
  │  POST /api/mcp (no token)       │                               │
  │────────────────────────────────▶│                               │
  │  401 + WWW-Authenticate         │                               │
  │◀────────────────────────────────│                               │
  │  GET PRM                        │                               │
  │────────────────────────────────▶│                               │
  │  { resource, authorization_servers, scopes_supported }          │
  │◀────────────────────────────────│                               │
  │  GET /oidc/.well-known/openid-configuration                     │
  │────────────────────────────────────────────────────────────────▶│
  │  authorization code + PKCE, resource=https://namebeta.com/api/mcp│
  │────────────────────────────────────────────────────────────────▶│
  │                user signs in and consents, client gets a token  │
  │◀────────────────────────────────────────────────────────────────│
  │  POST /api/mcp, Authorization: Bearer <JWT>                     │
  │────────────────────────────────▶│                               │
  │  200                            │                               │
  │◀────────────────────────────────│                               │

1. Die 401-Challenge​

Eine Anfrage ohne Token erhält 401 Unauthorized:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer resource_metadata="https://namebeta.com/.well-known/oauth-protected-resource/api/mcp", scope="profile email"
Content-Type: application/json

{"jsonrpc":"2.0","error":{"code":-32000,"message":"unauthorized"},"id":null}

Eine Anfrage ohne Zugangsdaten erhält eine Challenge ohne das Attribut error, wie in RFC 6750 §3.1 vorgeschrieben. Schlägt die Prüfung eines mitgesendeten Tokens fehl, erhält die Anfrage dieselbe Challenge mit dem Zusatz error="invalid_token" und invalid_token als JSON-RPC-Meldung.

2. Protected Resource Metadata​

GET https://namebeta.com/.well-known/oauth-protected-resource/api/mcp gibt das Dokument nach RFC 9728 zurück:

{
    "resource": "https://namebeta.com/api/mcp",
    "authorization_servers": ["https://auth.namebeta.com/oidc"],
    "scopes_supported": ["profile", "email"],
    "bearer_methods_supported": ["header"],
    "resource_name": "NameBeta MCP"
}

Dasselbe Dokument steht auch direkt unter https://namebeta.com/.well-known/oauth-protected-resource bereit, für Clients, die resource_metadata nicht aus der Challenge auslesen. Die Antworten enthalten Cache-Control: public, max-age=3600.

3. Metadaten des Autorisierungsservers​

Der Issuer https://auth.namebeta.com/oidc enthält einen Pfad. Seine Metadaten werden nur unter URLs veröffentlicht, bei denen das Well-known-Suffix nach diesem Pfad steht:

URLStatus
https://auth.namebeta.com/oidc/.well-known/openid-configuration200
https://auth.namebeta.com/oidc/.well-known/oauth-authorization-server200
https://auth.namebeta.com/.well-known/oauth-authorization-server/oidc404

Laut MCP-Spezifikation müssen Clients zunächst die RFC-8414-URL mit eingefügtem Pfad versuchen und anschließend auf OpenID Connect Discovery zurückgreifen. Ein spezifikationskonformer Client findet daher die erste URL. Die Metadaten enthalten client_id_metadata_document_supported: true und code_challenge_methods_supported: ["S256"], aber keinen registration_endpoint.

4. Client-Registrierung​

NameBeta unterstützt Client ID Metadata Documents (CIMD): Ihre client_id ist eine HTTPS-URL. Das Dokument unter dieser URL beschreibt Ihren Client, etwa seinen Namen und seine Weiterleitungs-URIs. Der Autorisierungsserver ruft das Dokument während der Autorisierung ab; ein eigener Registrierungsschritt entfällt.

Dynamic Client Registration (DCR, RFC 7591) wird nicht angeboten. Ein Client, der sich nur über DCR registrieren kann, bricht mit einer Meldung wie „does not support dynamic client registration“ ab.

Vorab registrierte Client-IDs​

Ein Client, der kein Metadatendokument verwenden kann – etwa weil er nur DCR unterstützt –, kann sich dennoch verbinden, wenn Nutzer eine OAuth-Client-ID eingeben können. Schreiben Sie an contact@namebeta.com mit dem Namen des Clients und seinen Weiterleitungs-URIs. Wir antworten mit einer Client-ID. Wo Sie diese eintragen, hängt vom Client ab:

ClientEingabe der Client-ID
Claude Codeclaude mcp add … --client-id <client ID>
Codexcodex mcp add … --oauth-client-id <client ID>
CursorCLIENT_ID im Block auth des Servers in mcp.json
Gemini CLIoauth.clientId des Servers in settings.json
Devin Desktopdevin mcp login … --oauth-client-id <client ID>

Cursor und Gemini CLI registrieren sich ausschließlich über Dynamic Client Registration, nicht über Client ID Metadata Documents. Sie benötigen daher immer eine Client-ID von uns.

5. Autorisierungsanfrage​

Verwenden Sie den Authorization-Code-Grant mit PKCE (code_challenge_method=S256) und senden Sie den Ressourcenparameter gemäß RFC 8707:

resource=https://namebeta.com/api/mcp
scope=profile email
  • Scopes. Fordern Sie profile email an, wie in der Challenge und den PRM angegeben. Das sind Identitäts-Scopes: Die Zustimmungsseite zeigt dem Nutzer, welche Kontodaten der Client einsehen kann. Es gibt keinen API-Scope wie mcp:tools; fordern Sie keinen solchen Scope an.
  • Refresh-Tokens. Um ein Refresh-Token zu erhalten, ergänzen Sie den Scope um offline_access und senden Sie prompt=consent. Ohne prompt=consent wird offline_access ohne Fehlermeldung verworfen, und Sie erhalten nur ein Zugriffstoken.
  • Ressource. Sie ist entscheidend für die Prüfung durch den Server. Ohne diesen Parameter wird das Token zwar ebenfalls für NameBeta MCP ausgestellt; senden Sie ihn dennoch, wie von der MCP-Spezifikation verlangt.

Wenn ein Nutzer erstmals einen Client autorisiert, legt NameBeta sein Konto mit Englisch als Sprache und USD als Währung an. Beides kann er auf namebeta.com ändern.

6. Endpunkt aufrufen​

Senden Sie das Zugriffstoken bei jeder Anfrage als Authorization: Bearer <token>. Endpunkt und Transport zeigt eine vollständige Anfrage.

So prüft der Server ein Token​

Der Server prüft die JWT-Signatur anhand des JWKS des Issuers (https://auth.namebeta.com/oidc/jwks) und kontrolliert anschließend diese Claims:

ClaimAnforderung
isshttps://auth.namebeta.com/oidc
audhttps://namebeta.com/api/mcp
expVorhanden und in der Zukunft
subVorhanden; identifiziert den NameBeta-Nutzer

Scopes werden nicht geprüft. Die Audience legt den Geltungsbereich der Autorisierung fest: Ein für https://namebeta.com/api/mcp ausgestelltes Token gilt für alle Tools. Jede fehlgeschlagene Prüfung führt zu 401 mit error="invalid_token". Erneuern Sie das Token oder führen Sie die Autorisierung erneut durch. Fehlerbehebung nennt die häufigsten Ursachen.

Letztes Update am