Pular para o conteúdo principal

Autorização

Esta página é voltada a desenvolvedores que estão criando ou depurando um cliente MCP. Se você só quer conectar um cliente existente, consulte Conectar um cliente.

O NameBeta segue a especificação de autorização do MCP: o endpoint MCP é um servidor de recursos OAuth 2.1, e o serviço de contas do NameBeta em auth.namebeta.com é o servidor de autorização. Os usuários entram com sua conta do NameBeta; não há chaves de API.

Resumo​

ItemValor
Recursohttps://namebeta.com/api/mcp
Metadados do recurso protegido (PRM)https://namebeta.com/.well-known/oauth-protected-resource/api/mcp
Servidor de autorização (emissor)https://auth.namebeta.com/oidc
Registro de clientesClient ID Metadata Documents (CIMD) ou pré-registro. Sem DCR
Tipo de concessãoCódigo de autorização com PKCE (S256)
Escoposprofile email. Não existe escopo de API
TokenJWT, enviado como Authorization: Bearer <token>

O fluxo​

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. O desafio 401​

Uma solicitação sem token recebe 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}

Uma solicitação sem credenciais recebe um desafio sem o atributo error, conforme RFC 6750 §3.1. Se o token da solicitação não passar na verificação, ela recebe o mesmo desafio com error="invalid_token" acrescentado e invalid_token como mensagem JSON-RPC.

2. Metadados do recurso protegido​

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

O mesmo documento também está disponível na raiz, https://namebeta.com/.well-known/oauth-protected-resource, para clientes que não leem resource_metadata do desafio. As respostas incluem Cache-Control: public, max-age=3600.

3. Metadados do servidor de autorização​

O emissor https://auth.namebeta.com/oidc inclui um caminho, e seus metadados são publicados apenas com o sufixo well-known depois desse caminho:

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

A especificação MCP orienta os clientes a tentar primeiro a URL da RFC 8414 com o caminho inserido e, se ela falhar, recorrer à descoberta do OpenID Connect; assim, um cliente em conformidade encontra a primeira URL. Os metadados anunciam client_id_metadata_document_supported: true e code_challenge_methods_supported: ["S256"] e não incluem registration_endpoint.

4. Registro de clientes​

O NameBeta oferece suporte a Client ID Metadata Documents (CIMD): seu client_id é uma URL HTTPS, e o documento hospedado nela descreve o cliente, incluindo seu nome e suas URIs de redirecionamento. O servidor de autorização busca o documento durante a autorização, então não há uma etapa de registro.

Dynamic Client Registration (DCR, RFC 7591) não é oferecido. Um cliente que só consiga se registrar por DCR será interrompido com um erro como “does not support dynamic client registration”.

IDs de cliente pré-registrados​

Um cliente que não consiga usar um documento de metadados, como um que só ofereça suporte a DCR, ainda pode se conectar se permitir informar um ID de cliente OAuth. Escreva para contact@namebeta.com com o nome do cliente e as URIs de redirecionamento que ele usa, e responderemos com um ID de cliente. Cada cliente aceita o ID em um lugar diferente:

ClienteOnde informar o ID de cliente
Claude Codeclaude mcp add … --client-id <client ID>
Codexcodex mcp add … --oauth-client-id <client ID>
CursorCLIENT_ID no bloco auth do servidor em mcp.json
Gemini CLIoauth.clientId do servidor em settings.json
Devin Desktopdevin mcp login … --oauth-client-id <client ID>

O Cursor e o Gemini CLI só se registram por Dynamic Client Registration, não por Client ID Metadata Documents, então sempre precisam de um ID de cliente fornecido por nós.

5. Solicitação de autorização​

Use o fluxo de código de autorização com PKCE (code_challenge_method=S256) e envie o parâmetro de recurso da RFC 8707:

resource=https://namebeta.com/api/mcp
scope=profile email
  • Escopos. Solicite profile email, conforme anunciado pelo desafio e pelo PRM. São escopos de identidade: a tela de consentimento mostra ao usuário quais dados da conta o cliente verá. Não há escopo de API como mcp:tools; não o solicite.
  • Tokens de atualização. Para obter um, adicione offline_access ao escopo e envie prompt=consent. Sem prompt=consent, offline_access é descartado sem aviso e você recebe apenas um token de acesso.
  • O recurso. É o que o servidor verifica. Mesmo sem ele, o token continua sendo emitido para o NameBeta MCP, mas envie-o de qualquer forma, como exige a especificação MCP.

Na primeira vez que um usuário autoriza qualquer cliente, o NameBeta cria sua conta com inglês como idioma e USD como moeda. Ele pode alterar as duas opções em namebeta.com.

6. Chamar o endpoint​

Envie o token de acesso como Authorization: Bearer <token> em cada solicitação. Endpoint e transporte mostra uma solicitação completa.

Como o servidor verifica um token​

O servidor verifica a assinatura do JWT com o JWKS do emissor (https://auth.namebeta.com/oidc/jwks) e depois verifica estas declarações (claims):

DeclaraçãoRequisito
isshttps://auth.namebeta.com/oidc
audhttps://namebeta.com/api/mcp
expDeve estar presente e indicar um momento futuro
subDeve estar presente; identifica o usuário do NameBeta

Os escopos não são verificados. A audiência delimita a autorização: um token emitido para https://namebeta.com/api/mcp é válido para todas as ferramentas. Qualquer falha retorna 401 com error="invalid_token"; atualize o token ou autorize novamente. Solução de problemas lista as causas comuns.

Última atualização em