게시한 MCP 서버 버전 관리

게시한 MCP 서버 버전 관리 (Versioning Published MCP Servers)

MCP 서버는 server.json에 MUST 버전 문자열을 정의해야 해요. 예를 들어:

출처: MCP 공식 문서 - Versioning Published MCP Servers

{
  "$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"
      }
    }
  ]
}

버전 문자열은 서버의 각 게시마다 유일해야 합니다. 한 번 게시하면 버전 문자열(및 다른 메타데이터)은 변경할 수 없어요.

💡 MCP 레지스트리는 현재 프리뷰 단계예요. 일반 공개 전에 파괴적 변경이나 데이터 리셋이 있을 수 있습니다. 이슈가 있으면 GitHub에 보고해 주세요.

버전 형식

MCP 레지스트리는 시맨틱 버저닝을 권장하지만, 어떤 버전 문자열 형식이든 지원해요. 서버가 게시될 때 MCP 레지스트리는 정렬 목적으로 그 버전을 시맨틱 버전 문자열로 파싱하려 시도하고, 적절하면 그 버전을 "latest"로 표시합니다. 파싱에 실패하면 그 버전은 항상 "latest"로 표시돼요.

⚠️ 서버가 시맨틱 버전 문자열을 쓰면서도 시맨틱 버저닝을 따르지 않는 새 버전을 게시하면, 그 새 버전은 그렇지 않으면 시맨틱 버전 문자열보다 먼저 정렬될지라도 "latest"로 표시됩니다.

오류 방지 메커니즘으로, MCP 레지스트리는 버전 범위를 가리키는 것처럼 보이는 버전 문자열을 금지합니다.

예제	유형	지침
`1.0.0`	semantic version	권장(Recommended)
`2.1.3-alpha`	semantic prerelease	권장
`1.0.0-beta.1`	semantic prerelease	권장
`3.0.0-rc.2`	semantic prerelease	권장
`2025.11.25`	semantic date	권장
`2025.6.18`	semantic date	권장 (⚠️Caution!⚠️)
`2025.06.18`	non-semantic date	허용 (⚠️Caution!⚠️)
`2025-06-18`	non-semantic date	허용
`v1.0`	prefixed version	허용
`^1.2.3`	version range	금지(Prohibited)
`~1.2.3`	version range	금지
`>=1.2.3`	version range	금지
`<=1.2.3`	version range	금지
`>1.2.3`	version range	금지
`<1.2.3`	version range	금지
`1.x`	version range	금지
`1.2.*`	version range	금지
`1 - 2`	version range	금지
`1.2 \|\| 1.3`	version range	금지

모범 사례

시맨틱 버저닝 사용

버전 문자열에 시맨틱 버저닝을 쓰세요.

서버 버전과 패키지 버전 정렬

로컬 서버의 경우 혼동을 막기 위해 서버 버전을 기반 패키지 버전과 맞추세요.

{
  "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"
    }
  ]
}

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

기반 패키지나 원격 URL을 바꾸지 않고 서버를 여러 번 게시할 예정이라면(예: 메타데이터의 다른 부분을 업데이트하기 위해), 시맨틱 prerelease 버전을 쓰세요.

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

⚠️ 시맨틱 버저닝에 따르면 1.2.3-1 같은 prerelease 버전은 1.2.3 같은 일반 시맨틱 버전보다 먼저 정렬됩니다. 따라서 대응하는 일반 버전 이후에 prerelease 버전을 게시하면, 그 prerelease 버전은 "latest"로 표시되지 않아요.

애그리게이터 권장사항

MCP 레지스트리 애그리게이터는 SHOULD:

가능하면 버전을 시맨틱 버전으로 해석할 것
다음 버전 비교 규칙을 사용할 것
- 한 버전이 "latest"로 표시되면 그것을 더 이후로 취급
- 둘 다 유효한 시맨틱 버전이면 시맨틱 버저닝 비교 규칙 사용
- 둘 다 유효한 시맨틱 버전이 아니면 게시 타임스탬프 비교
- 하나는 유효한 시맨틱 버전이고 다른 하나는 아니면, 시맨틱 버전을 더 이후로 취급

더 알아보기 (Learn more)

레지스트리 지원 패키지 유형 — 각 패키지 유형과 검증 방법
MCP 레지스트리 — 레지스트리 소개
레지스트리 인증 — 게시 전 인증