본문으로 건너뛰기

권한 부여

이 페이지는 MCP 클라이언트를 개발하거나 디버깅하는 개발자를 위한 문서입니다. 기존 클라이언트를 연결하기만 하려면 클라이언트 연결을 참조하세요.

NameBeta는 MCP 권한 부여 사양을 따릅니다. MCP 엔드포인트는 OAuth 2.1 리소스 서버이고, auth.namebeta.com에 있는 NameBeta 계정 서비스가 권한 부여 서버입니다. 사용자는 NameBeta 계정으로 로그인하며, API 키는 없습니다.

요약​

항목값
리소스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)를 사용하는 권한 부여 코드 그랜트
스코프profile email. API 스코프는 없음
토큰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에서만 제공됩니다.

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에 있는 문서가 클라이언트의 이름, 리디렉션 URI 등을 설명합니다. 권한 부여 서버가 권한 부여 과정에서 이 문서를 가져오므로 별도의 등록 단계가 없습니다.

동적 클라이언트 등록(DCR, RFC 7591)은 제공하지 않습니다. DCR로만 자신을 등록할 수 있는 클라이언트는 "does not support dynamic client registration" 같은 오류와 함께 멈춥니다.

사전 등록된 클라이언트 ID​

DCR만 지원하는 등 메타데이터 문서를 사용할 수 없는 클라이언트라도, 사용자가 OAuth 클라이언트 ID를 입력할 수 있다면 연결할 수 있습니다. 클라이언트 이름과 사용하는 리디렉션 URI를 적어 contact@namebeta.com으로 보내 주시면 클라이언트 ID를 회신해 드립니다. 클라이언트 ID를 입력하는 위치는 클라이언트마다 다릅니다.

클라이언트클라이언트 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는 Client ID Metadata Documents가 아닌 동적 클라이언트 등록으로만 자신을 등록하므로, 항상 저희가 발급한 클라이언트 ID가 필요합니다.

5. 권한 부여 요청​

PKCE(code_challenge_method=S256)를 사용하는 권한 부여 코드 그랜트를 쓰고, RFC 8707의 resource 매개변수를 보냅니다.

resource=https://namebeta.com/api/mcp
scope=profile email
  • 스코프. 챌린지와 PRM에 명시된 대로 profile email을 요청합니다. 이는 신원 확인용 스코프로, 클라이언트가 어떤 계정 정보를 보게 되는지 동의 화면에서 사용자에게 보여 줍니다. mcp:tools 같은 API 스코프는 없으므로 요청하지 마세요.
  • 리프레시 토큰. 리프레시 토큰을 받으려면 스코프에 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 서명을 검증한 다음, 다음 클레임을 확인합니다.

클레임요구 사항
isshttps://auth.namebeta.com/oidc
audhttps://namebeta.com/api/mcp
exp존재하며 미래 시각이어야 함
sub존재해야 함. NameBeta 사용자를 식별함

스코프는 검증하지 않습니다. 권한의 경계는 대상(audience)입니다. https://namebeta.com/api/mcp용으로 발급된 토큰은 모든 도구에 유효합니다. 검증에 하나라도 실패하면 error="invalid_token"과 함께 401을 반환하므로, 토큰을 갱신하거나 다시 권한을 부여받으세요. 흔한 원인은 문제 해결에 정리되어 있습니다.

최종 수정: 에