byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

MCP 문서 · Extensions

익스텐션 개요

Extensions Overview · 원문: modelcontextprotocol.io/extensions/overview

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

Model Context Protocol의 선택적 확장

MCP 익스텐션

MCP 익스텐션(extension)은 핵심 프로토콜 외의 기능을 정의하는 명세의 선택적 추가 사항입니다. 익스텐션을 통해 모듈식(예: 인증과 같은 독립적 기능), 특수 목적(예: 산업별 로직), 또는 실험적(예: 향후 핵심 포함을 검토 중인 기능) 기능을 활성화할 수 있습니다.

익스텐션은 {vendor-prefix}/{extension-name} 형식의 고유한 익스텐션 식별자로 구분됩니다. 예를 들어 io.modelcontextprotocol/oauth-client-credentials와 같습니다. 식별자는 _meta 키와 동일한 규칙을 따르며, 반드시 접두어를 포함해야 합니다. 공식 익스텐션은 io.modelcontextprotocol 벤더 접두어를 사용합니다.

팁: 서드파티 익스텐션을 개발하는 경우, 충돌을 방지하기 위해 소유한 도메인의 역순 이름을 벤더 접두어로 사용하세요(Java 패키지 명명 방식과 유사합니다). 예를 들어 example.com을 소유한 기업은 com.example/을 접두어로 사용합니다(예: com.example/my-extension).

공식 익스텐션 저장소

공식 익스텐션은 Model Context Protocol GitHub 조직 내의 ext- 접두어를 가진 저장소에 있습니다.

MCP 인가 익스텐션

익스텐션 설명
OAuth Client Credentials 머신 간 인증을 위한 OAuth 2.0 클라이언트 자격증명 플로우
Enterprise-Managed Authorization 중앙화된 접근 제어가 필요한 엔터프라이즈 환경을 위한 프레임워크

MCP 앱

익스텐션 설명
MCP Apps MCP 서버가 대화 내에 차트, 폼, 동영상 플레이어 등 인터랙티브 UI 요소를 표시할 수 있게 합니다

MCP 앱 개발을 시작하려면 빠른 시작 가이드를 참고하거나 전체 MCP 앱 문서를 읽어보세요.

MCP 태스크

익스텐션 설명
MCP Tasks 폴링, 실행 중 입력, 영속적 핸들을 지원하는 장시간 작업의 비동기 태스크 실행

실험적 익스텐션

실험적 익스텐션은 워킹 그룹 및 인터레스트 그룹이 공식 SEP 제출 전에 아이디어를 프로토타입화하고 익스텐션 개념을 협업할 수 있는 인큐베이션 경로를 제공합니다.

실험적 익스텐션 저장소는 MCP GitHub 조직 내에 experimental-ext- 접두어를 가지고 있습니다(예: experimental-ext-interceptors).

기본 규칙

공식 상태로 승격

실험적 익스텐션을 공식 상태로 승격하려면 표준 SEP 프로세스(익스텐션 트랙)를 거쳐야 합니다. 인큐베이션 중 구축한 실험적 저장소와 참조 구현을 활용하여 익스텐션의 실용성을 입증할 수 있습니다.

익스텐션 만들기

공식 익스텐션의 라이프사이클은 SEP 기반 프로세스를 따릅니다. 전체 세부 사항은 SEP-2133: Extensions를 참조하세요.

  1. 제안: Extensions Track 유형으로 표준 SEP 가이드라인에 따라 메인 MCP 저장소에 SEP를 생성합니다.
  2. 구현: 공식 SDK 중 하나에 참조 구현을 최소 1개 이상 구축합니다 — SEP 검토 전에 필수 사항입니다.
  3. 검토: 핵심 관리자가 SEP를 검토하며 포함 여부에 대한 최종 결정권을 가집니다.
  4. 게시: 승인 후 익스텐션 저장소에 추가하는 PR을 열어 추가합니다.
  5. 채택: 이후 다른 클라이언트, 서버, SDK에서도 해당 익스텐션을 구현할 수 있습니다.

요구 사항

SDK 구현

SDK는 익스텐션 구현 여부를 선택할 수 있으며, 프로토콜 적합성에 필수 사항은 아닙니다. SDK 관리자는 지원할 익스텐션에 대한 완전한 자율권을 가집니다. SDK가 익스텐션을 지원하는 경우, SDK 문서에는 지원되는 익스텐션 목록이 명시되어야 합니다.

참고: 익스텐션은 항상 기본적으로 비활성화되어 있으며, 개발자가 명시적으로 활성화해야 합니다.

발전

익스텐션은 핵심 프로토콜과 독립적으로 발전합니다. 업데이트는 익스텐션 저장소 관리자가 관리하며 핵심 관리자의 검토가 필요하지 않습니다.

그러나 하위 호환성은 중요합니다. 익스텐션을 변경해야 할 경우, 새로운 익스텐션 식별자를 생성하는 대신 익스텐션 설정 객체 내에서 기능 플래그나 버전 관리를 사용하는 것이 좋습니다. 호환성을 깨는 변경이 불가피한 경우에는 새 식별자를 사용하세요(예: io.modelcontextprotocol/my-extension-v2).

호환성을 깨는 변경은 기존 구현이 실패하거나 잘못 동작하게 만드는 모든 수정 사항으로, 다음을 포함합니다:

협상

클라이언트와 서버는 초기화 핸드셰이크 중 각자의 capabilities의 extensions 필드에서 익스텐션 지원을 광고합니다.

클라이언트 Capabilities

클라이언트는 initialize 요청에서 익스텐션 지원을 광고합니다:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "extensions": {
        "io.modelcontextprotocol/ui": {
          "mimeTypes": ["text/html;profile=mcp-app"]
        }
      }
    },
    "clientInfo": {
      "name": "ExampleClient",
      "version": "1.0.0"
    }
  }
}

서버 Capabilities

서버는 initialize 응답에서 익스텐션 지원을 광고합니다:

코드 · 명령
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": {
      "tools": {},
      "extensions": {
        "io.modelcontextprotocol/ui": {}
      }
    },
    "serverInfo": {
      "name": "ExampleServer",
      "version": "1.0.0"
    }
  }
}

각 익스텐션은 설정 객체의 스키마(schema)를 지정합니다. 빈 객체는 설정이 없음을 나타냅니다.

점진적 저하

한쪽이 익스텐션을 지원하고 다른 쪽이 지원하지 않는 경우, 지원하는 쪽은 핵심 프로토콜 동작으로 폴백하거나, 익스텐션이 필수적인 경우 적절한 오류와 함께 요청을 거부해야 합니다.

익스텐션에 예상 폴백 동작을 문서화하는 것이 좋은 관행입니다. 예를 들어, UI 강화 도구를 제공하는 서버는 UI 익스텐션을 지원하지 않는 클라이언트를 위해 여전히 의미 있는 텍스트 콘텐츠를 반환해야 합니다. 반면 특정 인증 익스텐션이 필요한 서버는 해당 익스텐션을 지원하지 않는 클라이언트의 연결을 거부할 수 있습니다.

원문(영어): https://modelcontextprotocol.io/extensions/overview · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Model Context Protocol)에게 있습니다.

원문(영어): https://modelcontextprotocol.io/extensions/overview