Autorización

Esta página está dirigida a desarrolladores que crean o depuran un cliente MCP. Si solo quieres conectar un cliente existente, consulta Conectar un cliente.

NameBeta sigue la especificación de autorización de MCP: el endpoint MCP es un servidor de recursos OAuth 2.1, y el servicio de cuentas de NameBeta en auth.namebeta.com es el servidor de autorización. Los usuarios inician sesión con su cuenta de NameBeta; no hay claves de API.

Resumen

Elemento	Valor
Recurso	https://namebeta.com/api/mcp
Metadatos del recurso protegido (PRM)	https://namebeta.com/.well-known/oauth-protected-resource/api/mcp
Servidor de autorización (emisor)	https://auth.namebeta.com/oidc
Registro de clientes	Client ID Metadata Documents (CIMD) o registro previo. Sin DCR
Tipo de concesión	Código de autorización con PKCE (S256)
Ámbitos	profile email. No existe ningún ámbito de API
Token	JWT, enviado como Authorization: Bearer <token>

El flujo

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. El desafío 401

Una solicitud sin token recibe 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}

Una solicitud sin credenciales recibe un desafío sin el atributo error, tal como establece RFC 6750 §3.1. Si el token de la solicitud no supera la verificación, recibe el mismo desafío con error="invalid_token" añadido e invalid_token como mensaje JSON-RPC.

2. Metadatos del recurso protegido

GET https://namebeta.com/.well-known/oauth-protected-resource/api/mcp devuelve el documento definido en 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"
}

El mismo documento también está disponible en la raíz, https://namebeta.com/.well-known/oauth-protected-resource, para los clientes que no leen resource_metadata del desafío. Las respuestas incluyen Cache-Control: public, max-age=3600.

3. Metadatos del servidor de autorización

El emisor https://auth.namebeta.com/oidc incluye una ruta, y sus metadatos se publican únicamente con el sufijo well-known después de esa ruta:

URL	Estado
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 especificación MCP indica que los clientes deben probar primero la URL de RFC 8414 con la ruta insertada y, si falla, recurrir al descubrimiento de OpenID Connect; por tanto, un cliente que siga la especificación encontrará la primera URL. Los metadatos anuncian client_id_metadata_document_supported: true y code_challenge_methods_supported: ["S256"], y no incluyen registration_endpoint.

4. Registro de clientes

NameBeta admite Client ID Metadata Documents (CIMD): tu client_id es una URL HTTPS, y el documento alojado en ella describe el cliente, incluido su nombre y sus URI de redirección. El servidor de autorización obtiene el documento durante la autorización, por lo que no hay un paso de registro.

No se ofrece Dynamic Client Registration (DCR, RFC 7591). Un cliente que solo pueda registrarse mediante DCR se detendrá con un error como «does not support dynamic client registration».

IDs de cliente registrados previamente

Un cliente que no pueda usar un documento de metadatos, por ejemplo uno que solo admita DCR, puede conectarse si permite introducir un ID de cliente OAuth. Escribe a contact@namebeta.com con el nombre del cliente y las URI de redirección que utiliza, y te responderemos con un ID de cliente. Cada cliente lo acepta en un lugar distinto:

Cliente	Dónde se introduce el ID de cliente
Claude Code	claude mcp add … --client-id <client ID>
Codex	codex mcp add … --oauth-client-id <client ID>
Cursor	CLIENT_ID en el bloque auth del servidor en mcp.json
Gemini CLI	oauth.clientId del servidor en settings.json
Devin Desktop	devin mcp login … --oauth-client-id <client ID>

Cursor y Gemini CLI solo se registran mediante Dynamic Client Registration, no mediante Client ID Metadata Documents, por lo que siempre necesitan un ID de cliente que les proporcionemos.

5. Solicitud de autorización

Usa el flujo de código de autorización con PKCE (code_challenge_method=S256) y envía el parámetro de recurso de RFC 8707:

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

• Ámbitos. Solicita profile email, tal como anuncian el desafío y PRM. Son ámbitos de identidad: la pantalla de consentimiento muestra al usuario qué datos de su cuenta verá el cliente. No hay ningún ámbito de API como mcp:tools; no lo solicites.
• Tokens de actualización. Para obtener uno, añade offline_access al ámbito y envía prompt=consent. Sin prompt=consent, se descarta offline_access sin aviso y solo recibes un token de acceso.
• El recurso. Es lo que comprueba el servidor. Si se omite, el token sigue emitiéndose para NameBeta MCP, pero envíalo de todos modos, como exige la especificación MCP.

La primera vez que un usuario autoriza a cualquier cliente, NameBeta crea su cuenta con inglés como idioma y USD como moneda. Puede cambiar ambas opciones en namebeta.com.

6. Llamar al endpoint

Envía el token de acceso como Authorization: Bearer <token> en cada solicitud. Endpoint y transporte muestra una solicitud completa.

Cómo comprueba el servidor un token

El servidor verifica la firma del JWT con el JWKS del emisor (https://auth.namebeta.com/oidc/jwks) y después comprueba estas declaraciones (claims):

Declaración	Requisito
iss	https://auth.namebeta.com/oidc
aud	https://namebeta.com/api/mcp
exp	Debe estar presente y ser una fecha futura
sub	Debe estar presente; identifica al usuario de NameBeta

Los ámbitos no se comprueban. La audiencia delimita la autorización: un token emitido para https://namebeta.com/api/mcp es válido para todas las herramientas. Cualquier fallo devuelve 401 con error="invalid_token"; actualiza el token o vuelve a autorizar. Solución de problemas enumera las causas habituales.