Autorisation

Cette page s’adresse aux développeurs qui créent ou déboguent un client MCP. Si vous souhaitez simplement connecter un client existant, consultez Connecter un client.

NameBeta suit la spécification d’autorisation MCP : le point de terminaison MCP est un serveur de ressources OAuth 2.1, et le service de comptes de NameBeta, sur auth.namebeta.com, est le serveur d’autorisation. Les utilisateurs se connectent avec leur compte NameBeta ; il n’existe pas de clés API.

Récapitulatif

Élément	Valeur
Ressource	https://namebeta.com/api/mcp
Protected Resource Metadata (PRM)	https://namebeta.com/.well-known/oauth-protected-resource/api/mcp
Serveur d’autorisation (émetteur)	https://auth.namebeta.com/oidc
Enregistrement du client	Client ID Metadata Documents (CIMD) ou préenregistrement. Pas de DCR
Type d’octroi	Code d’autorisation avec PKCE (S256)
Portées	profile email. Il n’existe aucune portée d’API
Jeton	JWT, envoyé sous la forme Authorization: Bearer <token>

Le flux

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. Le challenge 401

Une requête sans jeton reçoit 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}

Une requête qui ne transmet aucun identifiant reçoit un challenge simple, sans attribut error, comme le prescrit la RFC 6750 §3.1. Une requête dont le jeton échoue à la vérification reçoit le même challenge, complété par error="invalid_token", avec invalid_token comme message JSON-RPC.

2. Protected Resource Metadata

GET https://namebeta.com/.well-known/oauth-protected-resource/api/mcp renvoie le document défini par la RFC 9728 :

{
    "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"
}

Le même document est également servi à la racine, https://namebeta.com/.well-known/oauth-protected-resource, pour les clients qui ne lisent pas resource_metadata dans le challenge. Les réponses portent l’en-tête Cache-Control: public, max-age=3600.

3. Métadonnées du serveur d’autorisation

L’émetteur https://auth.namebeta.com/oidc comporte un chemin, et ses métadonnées ne sont publiées qu’avec le suffixe well-known placé après ce chemin :

URL	Statut
https://auth.namebeta.com/oidc/.well-known/openid-configuration	200
https://auth.namebeta.com/oidc/.well-known/oauth-authorization-server	200
https://auth.namebeta.com/.well-known/oauth-authorization-server/oidc	404

La spécification MCP demande aux clients d’essayer d’abord l’URL RFC 8414 avec insertion du chemin, puis de se rabattre sur la découverte OpenID Connect : un client conforme trouve donc la première URL. Les métadonnées annoncent client_id_metadata_document_supported: true et code_challenge_methods_supported: ["S256"], et ne contiennent pas de registration_endpoint.

4. Enregistrement du client

NameBeta prend en charge les Client ID Metadata Documents (CIMD) : votre client_id est une URL HTTPS, et le document situé à cette URL décrit votre client — son nom, ses URI de redirection, etc. Le serveur d’autorisation récupère ce document pendant l’autorisation : aucune étape d’enregistrement n’est donc nécessaire.

Dynamic Client Registration (DCR, RFC 7591) n’est pas proposé. Un client qui ne sait s’enregistrer que par DCR s’arrête sur une erreur du type « does not support dynamic client registration ».

Identifiants client préenregistrés

Un client qui ne peut pas utiliser de document de métadonnées — par exemple un client qui ne prend en charge que DCR — peut tout de même se connecter s’il permet à l’utilisateur de saisir un identifiant client OAuth. Écrivez à contact@namebeta.com en indiquant le nom du client et les URI de redirection qu’il utilise, et nous vous répondrons avec un identifiant client. L’endroit où le saisir varie selon le client :

Client	Emplacement de l’identifiant client
Claude Code	claude mcp add … --client-id <client ID>
Codex	codex mcp add … --oauth-client-id <client ID>
Cursor	CLIENT_ID dans le bloc auth du serveur, dans mcp.json
Gemini CLI	oauth.clientId du serveur, dans settings.json
Devin Desktop	devin mcp login … --oauth-client-id <client ID>

Cursor et Gemini CLI ne s’enregistrent que via Dynamic Client Registration, et non via les Client ID Metadata Documents : ils ont donc toujours besoin d’un identifiant client fourni par nos soins.

5. Requête d’autorisation

Utilisez l’octroi par code d’autorisation avec PKCE (code_challenge_method=S256), et envoyez le paramètre resource défini par la RFC 8707 :

resource=https://namebeta.com/api/mcp
scope=profile email

• Portées. Demandez profile email, comme l’annoncent le challenge et les PRM. Ce sont des portées d’identité : l’écran de consentement indique à l’utilisateur quelles informations de son compte le client pourra voir. Il n’existe aucune portée d’API comme mcp:tools ; n’en demandez pas.
• Jetons d’actualisation. Pour obtenir un jeton d’actualisation, ajoutez offline_access à la portée et envoyez prompt=consent. Sans prompt=consent, offline_access est ignoré sans avertissement et vous n’obtenez qu’un jeton d’accès.
• La ressource. C’est elle que vérifie le serveur. Sans ce paramètre, le jeton est tout de même émis pour NameBeta MCP, mais envoyez-le quand même, comme l’exige la spécification MCP.

La première fois qu’un utilisateur autorise un client, quel qu’il soit, NameBeta crée son compte avec l’anglais comme langue et l’USD comme devise. Il peut modifier ces deux réglages sur namebeta.com.

6. Appeler le point de terminaison

Envoyez le jeton d’accès sous la forme Authorization: Bearer <token> dans chaque requête. La page Point de terminaison et transport montre une requête complète.

Vérification des jetons par le serveur

Le serveur vérifie la signature du JWT à l’aide du JWKS de l’émetteur (https://auth.namebeta.com/oidc/jwks), puis contrôle les claims suivants :

Claim	Exigence
iss	https://auth.namebeta.com/oidc
aud	https://namebeta.com/api/mcp
exp	Présent et dans le futur
sub	Présent ; identifie l’utilisateur NameBeta

Les portées ne sont pas vérifiées. C’est l’audience qui délimite l’autorisation : un jeton émis pour https://namebeta.com/api/mcp est valable pour tous les outils. Tout échec renvoie 401 avec error="invalid_token" ; actualisez le jeton ou relancez l’autorisation. La section Dépannage liste les causes habituelles.