Authorization

This page is for developers building or debugging an MCP client. If you only want to connect an existing client, see Connect a client.

NameBeta follows the MCP authorization specification: the MCP endpoint is an OAuth 2.1 resource server, and NameBeta's account service at auth.namebeta.com is the authorization server. Users sign in with their NameBeta account; there are no API keys.

Summary

Item	Value
Resource	`https://namebeta.com/api/mcp`
Protected Resource Metadata (PRM)	`https://namebeta.com/.well-known/oauth-protected-resource/api/mcp`
Authorization server (issuer)	`https://auth.namebeta.com/oidc`
Client registration	Client ID Metadata Documents (CIMD) or pre-registration. No DCR
Grant	Authorization code with PKCE (`S256`)
Scopes	`profile email`. No API scope exists
Token	JWT, sent as `Authorization: Bearer <token>`

The flow

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

A request without a token gets 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}

A request that carries no credentials gets a bare challenge with no error attribute, as RFC 6750 §3.1 prescribes. A request whose token fails verification gets the same challenge with error="invalid_token" appended, and invalid_token as the JSON-RPC message.

2. Protected Resource Metadata

GET https://namebeta.com/.well-known/oauth-protected-resource/api/mcp returns the RFC 9728 document:

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

The same document is also served at the root, https://namebeta.com/.well-known/oauth-protected-resource, for clients that do not read resource_metadata from the challenge. Responses carry Cache-Control: public, max-age=3600.

3. Authorization server metadata

The issuer https://auth.namebeta.com/oidc has a path, and its metadata is published only with the well-known suffix after that path:

URL	Status
`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

The MCP specification has clients try the path-inserted RFC 8414 URL first and fall back to OpenID Connect discovery, so a conforming client finds the first URL. The metadata advertises client_id_metadata_document_supported: true and code_challenge_methods_supported: ["S256"], and has no registration_endpoint.

4. Client registration

NameBeta supports Client ID Metadata Documents (CIMD): your client_id is an HTTPS URL, and the document at that URL describes your client — its name, redirect URIs and so on. The authorization server fetches it during authorization, so there is no registration step.

Dynamic Client Registration (DCR, RFC 7591) is not offered. If your client cannot host a metadata document, write to contact@namebeta.com for a pre-registered client_id.

5. Authorization request

Use the authorization code grant with PKCE (code_challenge_method=S256), and send the RFC 8707 resource parameter:

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

Scopes. Request profile email, as the challenge and PRM advertise. They are identity scopes: the consent screen shows the user which account details the client sees. There is no API scope such as mcp:tools; do not request one.
Refresh tokens. To get a refresh token, add offline_access to the scope and send prompt=consent. Without prompt=consent, offline_access is silently dropped and you get only an access token.
The resource. It is what the server checks. Without it the token is still issued for NameBeta MCP, but send it anyway, as the MCP specification requires.

The first time a user authorizes any client, NameBeta creates their account with English as the language and USD as the currency. They can change both on namebeta.com.

6. Calling the endpoint

Send the access token on every request:

POST /api/mcp HTTP/1.1
Host: namebeta.com
Authorization: Bearer eyJhbGciOi...
Content-Type: application/json
Accept: application/json, text/event-stream

{"jsonrpc":"2.0","id":1,"method":"tools/list"}

The endpoint is stateless: there is no Mcp-Session-Id, and each request stands alone.

How the server checks a token

The server verifies the JWT signature against the issuer's JWKS (https://auth.namebeta.com/oidc/jwks) and then checks these claims:

Claim	Requirement
`iss`	`https://auth.namebeta.com/oidc`
`aud`	`https://namebeta.com/api/mcp`
`exp`	Present and in the future
`sub`	Present; identifies the NameBeta user

Scopes are not checked. The audience is the authorization boundary: a token minted for https://namebeta.com/api/mcp is valid for every tool. Any failure returns 401 with error="invalid_token"; refresh the token or authorize again.

Quota

A valid token identifies a NameBeta user, and each tool call counts against that user's plan. See Quotas and errors.

Summary​

The flow​

1. The 401 challenge​

2. Protected Resource Metadata​

3. Authorization server metadata​

4. Client registration​

5. Authorization request​

6. Calling the endpoint​

How the server checks a token​

Quota​