게시된 MCP 서버 버전 관리

참고: MCP 레지스트리는 현재 프리뷰 단계입니다. 일반 공개 전까지 주요 변경 사항이나 데이터 초기화가 발생할 수 있습니다. 문제가 발생하면 GitHub에 보고해 주세요.

MCP 서버는 server.json에 버전 문자열을 반드시(MUST) 정의해야 합니다. 예를 들면:

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.username/email-integration-mcp",
  "title": "Email Integration",
  "description": "Send emails and manage email accounts",
  "version": "1.0.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@username/email-integration-mcp",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

버전 문자열은 서버를 게시할 때마다 고유해야 합니다(MUST). 게시 후에는 버전 문자열(및 기타 메타데이터)을 변경할 수 없습니다.

버전 형식

MCP 레지스트리는 시맨틱 버전 관리를 권장하지만, 모든 버전 문자열 형식을 지원합니다. 서버가 게시되면 MCP 레지스트리는 정렬 목적으로 버전을 시맨틱 버전 문자열로 파싱하려 시도하고, 적절하면 "latest"로 표시합니다. 파싱에 실패하면 버전은 항상 "latest"로 표시됩니다.

주의: 서버가 시맨틱 버전 문자열을 사용하다가 시맨틱 버전 관리를 따르지 않는 새 버전을 게시하면, 해당 새 버전은 시맨틱 버전 문자열보다 앞에 정렬되더라도 "latest"로 표시됩니다.

오류 방지 메커니즘으로, MCP 레지스트리는 버전 범위를 나타내는 것처럼 보이는 버전 문자열을 허용하지 않습니다.

모범 사례

시맨틱 버전 관리 사용

버전 문자열에는 시맨틱 버전 관리를 사용합니다.

서버 버전과 패키지 버전 일치

로컬 서버의 경우, 혼동을 방지하기 위해 서버 버전을 기반 패키지 버전과 일치시킵니다:

{
  "version": "1.2.3",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

기반 패키지가 여러 개인 경우 서버 버전을 전체 릴리스 버전으로 사용합니다:

{
  "version": "1.3.0",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.3.0",
      "transport": {
        "type": "stdio"
      }
    },
    {
      "registryType": "nuget",
      "identifier": "MyUsername.MyServer",
      "version": "1.0.0",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

서버 버전과 원격 API 버전 일치

API 버전이 있는 원격 서버의 경우, 서버 버전을 API 버전과 일치시켜야 합니다:

{
  "version": "2.1.0",
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://api.myservice.com/mcp/v2.1"
    }
  ]
}

레지스트리 전용 업데이트에는 사전 릴리스 버전 사용

기반 패키지나 원격 URL을 변경하지 않고 서버를 여러 번 게시해야 하는 경우(예: 메타데이터의 다른 부분 업데이트), 시맨틱 사전 릴리스 버전을 사용합니다:

{
  "version": "1.2.3-1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/my-server",
      "version": "1.2.3",
      "transport": {
        "type": "stdio"
      }
    }
  ]
}

주의: 시맨틱 버전 관리에 따르면, 1.2.3-1과 같은 사전 릴리스 버전은 1.2.3과 같은 정식 시맨틱 버전보다 앞에 정렬됩니다. 따라서 해당 정식 버전 이후에 사전 릴리스 버전을 게시하면, 사전 릴리스 버전은 "latest"로 표시되지 않습니다.

애그리게이터 권장 사항

MCP 레지스트리 애그리게이터는 다음을 따라야(SHOULD) 합니다:

1. 가능한 경우 버전을 시맨틱 버전으로 해석하려 시도할 것
2. 다음 버전 비교 규칙을 사용할 것: * 한 버전이 "latest"로 표시된 경우, 더 나중 버전으로 취급 * 두 버전 모두 유효한 시맨틱 버전인 경우, 시맨틱 버전 비교 규칙 적용 * 두 버전 모두 유효한 시맨틱 버전이 아닌 경우, 게시 타임스탬프 비교 * 한 버전은 유효한 시맨틱 버전이고 다른 버전은 그렇지 않은 경우, 시맨틱 버전을 더 나중 버전으로 취급

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

원문(영어): https://modelcontextprotocol.io/registry/versioning