跳到主要内容

授权

本页面向开发或调试 MCP 客户端的开发者。如果你只是想接入现有的客户端，请参阅连接客户端。

NameBeta 遵循 MCP 授权规范：MCP 端点是 OAuth 2.1 资源服务器，位于 auth.namebeta.com 的 NameBeta 账号服务是授权服务器。用户用自己的 NameBeta 账号登录，不存在 API key。

概览​

项目值
资源（resource）https://namebeta.com/api/mcp
Protected Resource Metadata (PRM)https://namebeta.com/.well-known/oauth-protected-resource/api/mcp
授权服务器（issuer）https://auth.namebeta.com/oidc
客户端注册Client ID Metadata Documents（CIMD）或预注册，不支持 DCR
授权类型带 PKCE（S256）的授权码模式
scopeprofile email，没有 API scope
令牌JWT，以 Authorization: Bearer <token> 发送

流程​

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. 401 质询​

不带令牌的请求会收到 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}

按照 RFC 6750 §3.1 的规定，不带任何凭据的请求收到的质询不含 error 属性。令牌校验失败的请求收到的质询相同，但会追加 error="invalid_token"，JSON-RPC 消息也为 invalid_token。

2. Protected Resource Metadata​

GET https://namebeta.com/.well-known/oauth-protected-resource/api/mcp 返回 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"
}

对于不从质询中读取 resource_metadata 的客户端，同一份文档也发布在根路径 https://namebeta.com/.well-known/oauth-protected-resource。响应带有 Cache-Control: public, max-age=3600。

3. 授权服务器元数据​

issuer https://auth.namebeta.com/oidc 带有路径，其元数据只发布在该路径之后加上 well-known 后缀的位置：

URL状态码
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

MCP 规范要求客户端先尝试按 RFC 8414 插入路径的 URL，失败后再回退到 OpenID Connect 发现，因此符合规范的客户端能找到第一个 URL。元数据中声明了 client_id_metadata_document_supported: true 和 code_challenge_methods_supported: ["S256"]，且没有 registration_endpoint。

4. 客户端注册​

NameBeta 支持 Client ID Metadata Documents（CIMD）：你的 client_id 是一个 HTTPS URL，该 URL 上的文档描述了你的客户端——名称、回调地址等。授权服务器会在授权过程中获取这份文档，因此不需要单独的注册步骤。

NameBeta 不提供 Dynamic Client Registration（DCR，RFC 7591）。只能通过 DCR 注册自己的客户端，会报出类似「does not support dynamic client registration」的错误并中止。

预注册的 client ID​

无法使用元数据文档的客户端（例如只支持 DCR 的客户端），只要允许用户填写 OAuth client ID，仍然可以接入。请把客户端名称及其使用的回调地址发送至 contact@namebeta.com，我们会回复一个 client ID。不同客户端填写的位置不同：

客户端client ID 填写位置
Claude Codeclaude mcp add … --client-id <client ID>
Codexcodex mcp add … --oauth-client-id <client ID>
Cursormcp.json 中该服务器 auth 块里的 CLIENT_ID
Gemini CLIsettings.json 中该服务器的 oauth.clientId
Devin Desktopdevin mcp login … --oauth-client-id <client ID>

Cursor 和 Gemini CLI 只通过 Dynamic Client Registration 注册自己，不支持 Client ID Metadata Documents，因此它们始终需要向我们申请 client ID。

5. 授权请求​

使用带 PKCE（code_challenge_method=S256）的授权码模式，并发送 RFC 8707 定义的 resource 参数：

resource=https://namebeta.com/api/mcp
scope=profile email
  • scope。 按质询和 PRM 中公布的那样请求 profile email。这两个是身份 scope：授权确认页会告诉用户客户端能看到哪些账号信息。不存在 mcp:tools 之类的 API scope，请不要请求。
  • 刷新令牌。 要获取刷新令牌，需在 scope 中加上 offline_access，并发送 prompt=consent。不带 prompt=consent 时，offline_access 会被静默忽略，你只能拿到访问令牌。
  • resource。 服务器校验的正是它。即使不传，签发的令牌也仍然适用于 NameBeta MCP，但 MCP 规范要求发送，所以请照常发送。

用户首次授权任意客户端时，NameBeta 会为其创建账号，语言默认为英语，货币默认为美元（USD）。两者都可以在 namebeta.com 上修改。

6. 调用端点​

每个请求都以 Authorization: Bearer <token> 携带访问令牌。完整请求示例见端点与传输。

服务器如何校验令牌​

服务器先用 issuer 的 JWKS（https://auth.namebeta.com/oidc/jwks）验证 JWT 签名，再检查以下 claim：

Claim要求
isshttps://auth.namebeta.com/oidc
audhttps://namebeta.com/api/mcp
exp必须存在，且尚未过期
sub必须存在，用于标识 NameBeta 用户

scope 不会被检查。audience 就是授权边界：为 https://namebeta.com/api/mcp 签发的令牌对所有工具都有效。任何一项校验失败都返回带 error="invalid_token" 的 401；请刷新令牌或重新授权。常见原因见故障排查。

最后于 更新