클라이언트 등록

클라이언트 등록 (Client Registration)

MCP가 지원하는 세 가지 클라이언트 등록 메커니즘을 설명하는 페이지예요. 시나리오에 따라 Client ID Metadata Documents, 사전 등록(Pre-registration), Dynamic Client Registration 중에서 선택할 수 있어요.

출처: 문서

본문

MCP는 세 가지 클라이언트 등록 메커니즘을 지원해요. 시나리오에 따라 선택하세요:

Client ID Metadata Documents: 클라이언트와 서버 사이에 사전 관계가 없을 때 (가장 일반적)
사전 등록 (Pre-registration): 클라이언트와 서버 사이에 기존 관계가 있을 때
Dynamic Client Registration: 하위 호환성 또는 특정 요구사항을 위해

모든 옵션을 지원하는 클라이언트는 SHOULD 다음 우선순위 순서를 사용해야 해요:

클라이언트가 사용 가능하다면 서버에 대한 사전 등록된 클라이언트 정보를 사용한다
Authorization Server가 지원을 나타내면(OAuth Authorization Server Metadata의 client_id_metadata_document_supported) Client ID Metadata Documents를 사용한다
Authorization Server가 지원하면(OAuth Authorization Server Metadata의 registration_endpoint) 폴백으로 Dynamic Client Registration을 사용한다
다른 옵션이 없으면 사용자에게 클라이언트 정보를 입력하도록 요청한다

Client ID Metadata Documents

MCP 클라이언트와 인증 서버는 SHOULD 클라이언트 등록을 위해 OAuth Client ID Metadata Document에 명시된 대로 OAuth Client ID Metadata Documents를 지원해야 해요.

이 접근 방식은 클라이언트가 HTTPS URL을 클라이언트 식별자로 사용할 수 있게 해 주는데, 그 URL은 클라이언트 메타데이터를 담은 JSON 문서를 가리켜요. 이는 서버와 클라이언트 사이에 사전 관계가 없는 일반적인 MCP 시나리오를 해결해요.

구현 요구사항 (Implementation Requirements)

Client ID Metadata Documents를 지원하는 MCP 구현은 MUST OAuth Client ID Metadata Document에 명시된 요구사항을 따라야 해요. 핵심 요구사항:

MCP 클라이언트의 경우:

클라이언트는 MUST RFC 요구사항에 따라 HTTPS URL에서 메타데이터 문서를 호스팅해야 한다
client_id URL은 MUST "https" 스킴을 사용하고 경로 구성 요소를 포함해야 한다. 예: https://example.com/client.json
메타데이터 문서는 MUST 최소한 client_id, client_name, redirect_uris 속성을 포함해야 한다
클라이언트는 MUST 메타데이터의 client_id 값이 문서 URL과 정확히 일치하도록 보장해야 한다
클라이언트는 MAY Client ID Metadata Document의 Section 6.2에 설명된 대로 적절한 JWKS 설정으로 private_key_jwt를 클라이언트 인증(예: 토큰 엔드포인트 요청)에 사용할 수 있다

Authorization Server의 경우:

SHOULD URL 형식의 client_id를 만나면 메타데이터 문서를 가져와야 한다
MUST 가져온 문서의 client_id가 URL과 정확히 일치하는지 검증해야 한다
SHOULD HTTP 캐시 헤더를 존중하며 메타데이터를 캐시해야 한다
MUST 승인 요청에 제시된 redirect URI를 메타데이터 문서의 그것과 대조해 검증해야 한다
MUST 문서 구조가 유효한 JSON이고 필수 필드를 담고 있는지 검증해야 한다
SHOULD Client ID Metadata Document의 Section 6과 Client ID Metadata Document Security의 보안 고려 사항을 따라야 한다

예시 메타데이터 문서 (Example Metadata Document)

{
  "client_id": "https://app.example.com/oauth/client-metadata.json",
  "client_name": "Example MCP Client",
  "client_uri": "https://app.example.com",
  "logo_uri": "https://app.example.com/logo.png",
  "redirect_uris": [
    "http://127.0.0.1:3000/callback",
    "http://localhost:3000/callback"
  ],
  "grant_types": ["authorization_code"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "none"
}

Client ID Metadata Documents 흐름 (Client ID Metadata Documents Flow)

다음 다이어그램은 Client ID Metadata Documents를 사용할 때의 전체 흐름을 보여줘요:

sequenceDiagram
    participant User
    participant Client as MCP Client
    participant Server as Authorization Server
    participant Metadata as Metadata Endpoint<br/>(Client's HTTPS URL)
    participant Resource as MCP Server

    Note over Client,Metadata: Client hosts metadata at<br/>https://app.example.com/oauth/metadata.json

    User->>Client: Initiates connection to MCP Server
    Client->>Server: Authorization Request<br/>client_id=https://app.example.com/oauth/metadata.json<br/>redirect_uri=http://localhost:3000/callback

    Server->>User: Authentication prompt
    User->>Server: Provides credentials
    Note over Server: Authenticates user

    Note over Server: Detects URL-formatted client_id

    Server->>Metadata: GET https://app.example.com/oauth/metadata.json
    Metadata-->>Server: JSON Metadata Document<br/>{client_id, client_name, redirect_uris, ...}

    Note over Server: Validates:<br/>1. client_id matches URL<br/>2. redirect_uri in allowed list<br/>3. Document structure valid<br/>4. (Optional) Domain allowed via trust policy

    alt Validation Success
        Server->>User: Display consent page with client_name
        User->>Server: Approves access
        Server->>Client: Authorization code via redirect_uri
        Client->>Server: Exchange code for token<br/>client_id=https://app.example.com/oauth/metadata.json
        Server-->>Client: Access token
        Client->>Resource: MCP requests with access token
        Resource-->>Client: MCP responses
    else Validation Failure
        Server->>User: Error response<br/>error=invalid_client or invalid_request
    end

    Note over Server: Cache metadata for future requests<br/>(respecting HTTP cache headers)

CIMD 지원 광고 (Advertising CIMD Support)

인증 서버는 OAuth Authorization Server 메타데이터에 다음 속성을 포함해 Client ID Metadata Documents를 사용하는 클라이언트를 지원함을 광고해요:

{
  "client_id_metadata_document_supported": true
}

MCP 클라이언트는 SHOULD 이 기능을 확인하고, 사용할 수 없으면 MAY Dynamic Client Registration 또는 사전 등록으로 폴백할 수 있어요.

사전 등록 (Pre-registration)

MCP 클라이언트는 SHOULD 사전 등록 흐름으로 공급되는 정적 클라이언트 자격 증명 같은 옵션을 지원해야 해요. 이는 다음일 수 있어요:

그 인증 서버와 상호작용할 때 MCP 클라이언트가 사용할 클라이언트 ID(및 해당되면 클라이언트 자격 증명)를 하드코딩하거나,
사용자가 (예: 서버가 호스팅하는 설정 인터페이스를 통해) 스스로 OAuth 클라이언트를 등록한 후 이 세부 사항을 입력할 수 있는 UI를 사용자에게 제시한다.

Dynamic Client Registration

경고 (Warning): Dynamic Client Registration은 폐기되었어요. 새 구현은 대신 Client ID Metadata Documents를 사용해야 해요. 이 옵션은 Client ID Metadata Documents를 지원하지 않는 인증 서버와의 하위 호환성을 위해 계속 사용 가능하다.

MCP 클라이언트와 인증 서버는 MAY MCP 클라이언트가 사용자 상호작용 없이 OAuth 클라이언트 ID를 얻을 수 있게 하는 OAuth 2.0 Dynamic Client Registration Protocol RFC7591을 지원할 수 있어요. 이 옵션은 이전 MCP 인증 사양 버전과의 하위 호환성을 위해 포함됐어요.

애플리케이션 유형과 Redirect URI 제약 (Application Type and Redirect URI Constraints)

인증 서버가 OpenID Connect (OIDC)와 Dynamic Client Registration을 지원하면, OpenID Connect Dynamic Client Registration 1.0에 정의된 application_type 파라미터에 따라 redirect URI에 추가 제약을 강제할 수 있어요.

MCP 클라이언트는 MUST Dynamic Client Registration 중 적절한 application_type을 지정해야 해요. 생략하면 OIDC에서 기본값 "web"이 되는데, 이는 native 스타일 redirect URI와 충돌할 수 있어요. non-OIDC 서버는 그 파라미터를 안전하게 무시해요.

Native 애플리케이션 (데스크톱 앱, 모바일 앱, CLI 도구, localhost로 접근하는 로컬 호스팅 웹 앱)은 SHOULD application_type: "native"를 사용해야 한다
웹 애플리케이션 (non-local 호스트에서 서비스되는 원격 브라우저 기반 앱)은 SHOULD application_type: "web"을 사용해야 한다

MCP 클라이언트는 MUST 인증 서버가 OIDC를 구현할 때 redirect URI 제약 때문에 등록 실패를 처리할 준비가 되어 있어야 해요. 등록 요청이 거부되면 클라이언트는 SHOULD 사용자나 개발자에게 의미 있는 오류를 드러내야 해요. 클라이언트는 MAY 조정된 application_type 또는 주어진 애플리케이션 유형에 대한 인증 서버 요구사항을 따르는 redirect URI로 등록을 재시도할 수 있어요.

Authorization Server 바인딩 (Authorization Server Binding)

사전 등록된 자격 증명을 사용하거나 Dynamic Client Registration으로 얻은 클라이언트 자격 증명을 유지하는 클라이언트는 MUST 그 자격 증명을 발행한 특정 인증 서버와 연관시키고, 인증 서버의 issuer 식별자로 키를 잡아야 해요. 인증 서버가 바뀌면(갱신된 protected resource metadata로 감지), 클라이언트는 MUST NOT 다른 인증 서버의 클라이언트 자격 증명을 재사용하고 MUST 새 인증 서버에 재등록해야 해요.

사전 등록된 자격 증명은 본질적으로 특정 인증 서버에 한정돼요. protected resource metadata가 나타내는 인증 서버가 자격 증명이 등록된 것과 더 이상 일치하지 않으면, 클라이언트는 SHOULD 불일치 자격 증명을 조용히 사용하려 하기보다 오류를 드러내야 해요.

Client ID Metadata Documents 기반 클라이언트 ID는 자체 호스팅되는 HTTPS URL이고 인증 서버가 요청 시 해석하므로 인증 서버 간에 이식 가능해요. 인증 서버가 바뀌어도 재등록이 필요 없어요.

클라이언트 등록