레지스트리 FAQ

MCP Registry FAQ

다음 질문들은 MCP Registry 관련 논의에서 자주 등장합니다. 여기에서 답을 찾지 못했다면 MCP Registry Discussions에서 새 토론을 시작해 주세요.

일반 질문

MCP Registry란 무엇인가요?

MCP Registry는 공개적으로 접근 가능한 MCP 서버를 위한 공식 중앙 메타데이터 저장소입니다. 다음을 제공합니다:

  • 서버 제작자가 서버 메타데이터를 게시할 수 있는 단일 장소
  • MCP 클라이언트 및 애그리게이터(서브레지스트리)가 서버를 탐색/검색할 수 있는 REST API
  • 표준화된 설치 및 설정 정보
  • DNS 검증을 통한 네임스페이스(namespace) 관리

“Official MCP Registry”, “MCP Registry”, “MCP registry”, “MCP Registry API"는 어떻게 다른가요?

크게 4가지 개념이 있습니다:

  • “MCP Server Registry API”(또는 “MCP Registry API”): openapi.yaml에 정의된 OpenAPI 사양입니다. 어떤 형태의 “MCP 서버 레지스트리"를 만들든, 이 사양을 채택하거나 정렬(alignment)하는 것이 좋습니다.
  • “Official MCP Registry”(또는 “MCP Registry”): https://registry.modelcontextprotocol.io에서 제공되는 공식 레지스트리 애플리케이션입니다. 현재는 MCP 서버만 카탈로그하지만, 향후 MCP 클라이언트/호스트 앱 및 프레임워크까지 확장될 수 있습니다.
  • “Official MCP Registry API”: https://registry.modelcontextprotocol.io에서 제공되는 REST API로, MCP Registry API의 상위 집합(superset)입니다.
  • “MCP server registry”(또는 “MCP registry”): 제3자가(대개 상용일 가능성이 높음) MCP Server Registry API 또는 파생 사양을 구현한 레지스트리입니다.

MCP Registry는 패키지 레지스트리인가요?

아닙니다. MCP Registry는 MCP 서버 메타데이터와 호스팅 위치(npm, PyPI, NuGet, Docker Hub 등)에 대한 참조를 저장할 뿐, 실제 소스 코드나 패키지를 호스팅하지 않습니다.

누가 MCP Registry를 직접 사용해야 하나요?

Registry는 주로 서브레지스트리(Smithery, PulseMCP, Docker Hub, Anthropic, GitHub 등)가 프로그램 방식으로 소비하도록 설계되었습니다. 현재 단계에서는 개별 클라이언트나 최종 사용자(end-user)가 직접 사용하도록 의도된 것이 아닙니다(이 경우 서브레지스트리를 사용하는 것이 좋습니다).

기능 X가 추가될 예정인가요?

roadmap.md를 참고하세요.

서버 게시

MCP 서버를 어떻게 게시하나요?

게시 가이드를 참고하세요.

어떤 네임스페이스를 사용할 수 있나요?

  • With GitHub verification: io.github.yourusername/server-name, io.github.yourorg/server-name
  • With DNS verification: com.yourcompany.*, com.yourcompany.*/*
  • With HTTP verification: com.yourcompany/*

오픈소스가 필수인가요?

아닙니다. 오픈소스는 권장되지만, 로컬 실행 서버든 원격 실행 서버든 오픈소스는 필수가 아닙니다.

어떤 패키지 레지스트리가 지원되나요?

  • npm (Node.js packages)
  • PyPI (Python packages)
  • NuGet.org (.NET packages)
  • GitHub Container Registry (GHCR)
  • Docker Hub
  • MCPB (MCP Bundle format)

커뮤니티 수요에 따라 더 많은 레지스트리를 추가할 수 있습니다. 다른 레지스트리 지원에 관심이 있다면 이슈를 열어 주세요.

여러 버전을 게시할 수 있나요?

네, 버저닝(versioning)을 지원합니다:

  • 각 버전은 변경 불가능(immutable)한 메타데이터를 가집니다.
  • 서버별로 버전 문자열은 고유해야 합니다.
  • 하위 호환성을 위해 과거 버전도 계속 접근 가능합니다.
  • 가능할 경우 시맨틱 버전 순서에 따라 “latest"를 추적합니다.

서버 메타데이터는 어떻게 업데이트하나요?

고유한 버전 문자열을 가진 새 server.json을 제출하세요. 한 번 게시된 버전 메타데이터는 변경할 수 없습니다(npm과 유사).

어떤 버전 형식을 사용해야 하나요?

Registry는 255자 이하의 어떤 버전 문자열도 허용하지만, 다음을 권장합니다:

  • 시맨틱 버저닝 사용 권장(SHOULD): 예) “1.0.2”, “2.1.0-alpha” (예측 가능한 정렬)
  • 패키지 버전과 정렬 권장(SHOULD): 혼선을 줄이기 위해
  • 프리릴리즈 라벨 사용 가능(MAY): 예) “1.0.0-1” (레지스트리 전용 버전)

Registry는 정렬을 위해 가능한 경우 버전을 시맨틱 버전으로 파싱합니다. 시맨틱이 아닌 버전도 허용되지만 게시 시각 기준으로 정렬됩니다. 버전 범위(예: ^1.2.3, ~1.2.3, >=1.2.3, 1.x, 1.*)는 거부되므로, 반드시 구체적인 버전을 게시하세요. 자세한 내용은 버저닝 가이드를 참고하세요.

게시할 때 커스텀 메타데이터를 추가할 수 있나요?

네. Registry에 게시할 때 _meta 하위의 확장(extension) 데이터는 유지됩니다. 이를 통해 게시 파이프라인에 특화된 커스텀 메타데이터를 포함할 수 있습니다.

서버를 삭제/게시 취소(unpublish)할 수 있나요?

마지막 업데이트 시점 기준으로, 이 주제는 #104에서 논의 중입니다.

프라이빗 서버를 게시할 수 있나요?

프라이빗 서버는 제한된 사용자에게만 접근 가능한 서버를 의미합니다. 예를 들어 사설 네트워크(mcp.acme-corp.internal)에 게시되거나, 사설 패키지 레지스트리(예: npx -y @acme/mcp --registry https://artifactory.acme-corp.internal/npm)에 게시된 서버가 해당됩니다.

공식 MCP Registry는 공개 접근 가능한 MCP 서버를 대상으로 설계되었기 때문에, 일반적으로 프라이빗 서버는 지원하지 않습니다.

프라이빗 서버를 게시하려면 자체 MCP 서브레지스트리를 운영하고, 그곳에 등록하는 방식을 권장합니다.

보안 및 신뢰

서버가 주장하는 조직에서 나온 것인지 어떻게 확인하나요?

DNS 검증은 네임스페이스 소유권을 보장합니다. 예를 들어:

  • com.microsoft/server requires DNS verification of microsoft.com
  • io.github.name/server is tied to a GitHub account or GitHub organization name

보안 스캐닝이 제공되나요?

MVP 단계에서는 보안 스캐닝을 다음에 위임합니다:

  • 기반 패키지 레지스트리
  • 서브레지스트리

스팸은 어떻게 방지하나요?

  • Namespace authentication requirements
  • Character limits and regex validation on free-form fields
  • Manual takedown of spam or malicious servers

향후 다음을 검토할 수 있습니다:

  • Stricter rate limiting (e.g., 10 new servers per user per day)
  • Potential AI-based spam detection
  • Community reporting and admin blacklisting capabilities

API 및 통합

Registry를 얼마나 자주 폴링(poll)해야 하나요?

권장 폴링 주기:

  • /servers endpoint: once per hour
  • /servers/:id endpoint: once per version (results are immutable)
  • Design assumes CDN caching between registry and consumers

또한 #291 이슈가 진행되면, 위 주기를 더 정교하게 조정할 수 있습니다.

웹훅(webhook)이 제공되나요?

초기 MVP에는 포함되지 않지만, 아키텍처 상으로는 향후 업데이트 알림을 위한 웹훅 추가가 가능합니다.

레지스트리를 직접 운영할 수 있나요?

네. API 형태와 데이터 포맷은 서브레지스트리가 재사용하기 쉽게 의도적으로 설계되어 있습니다. 사설 레지스트리가 필요한 조직이라면 다음을 고려하세요:

  • Implement the same API shape
  • Use the same server.json format
  • Potentially mirror/filter the official registry data

레지스트리 API를 확장할 수 있나요?

네. 공식 MCP Registry API 사양에서 여러 위치에 x-com.example 형태의 확장(extension)을 지원합니다. 이를 통해 보안 스캔 결과, 패키지 메타데이터 강화 등 다양한 어노테이션(annotation)을 추가할 수 있습니다.

여기에서 다루기 어려운 유스케이스가 있다면 GitHub 이슈를 열어 주세요.

여기의 코드를 사용해 레지스트리를 직접 호스팅할 수 있나요?

여기 제공되는 레지스트리 구현은 자체 호스팅(self-hosting)을 목적으로 설계되지 않았습니다. 필요하다면 포크(fork)해 사용해 볼 수는 있지만, 이는 의도된 사용 방식이 아니며 현재로서는 메인테이너가 지원을 제공할 수 없습니다.

운영 및 유지보수

기대할 수 있는 신뢰성(reliability)은 어느 정도인가요?

  • This is a community maintained project without full time staffing. You should therefore expect downtime periods of up to 1 business day. No strict guarantees are provided. (Also see discussion in #150)
  • Ideally clients should use subregistries with higher availability guarantees, to avoid direct end-user impact (as subregistries can cache data).

스팸/악성 서버를 신고하려면 어떻게 하나요?

  1. Report it as abuse to the underlying package registry (e.g. NPM, PyPI, DockerHub, etc.); and
  2. Raise a GitHub issue on the registry repo with a title beginning Abuse report:

레지스트리 자체의 보안 취약점을 제보하려면요?

MCP 커뮤니티 SECURITY.md를 따르세요.

기술 질문

Registry는 어떤 인증 방식을 지원하나요?

  • GitHub OAuth: Interactive authentication through browser
  • GitHub OIDC: Automated authentication for GitHub Actions workflows
  • DNS verification: By setting up TXT records on your domain
  • HTTP verification: By hosting verification files on your domain

버전 충돌은 어떻게 처리되나요?

서버 이름별로 버전 문자열은 고유해야 합니다. 이미 존재하는 버전을 게시하려고 하면 게시가 실패합니다. 새 버전 번호 또는 프리릴리즈 라벨을 사용하세요.

벌크(일괄) 작업이 지원되나요?

현재는 지원되지 않습니다. 각 게시 작업은 단일 server.json 파일을 처리합니다. 다만 스크립팅을 통해 여러 게시를 자동화할 수는 있습니다.

레이트 리밋(rate limit)이 있나요?

네. 남용 방지를 위해 레이트 리밋을 적용합니다. 구체적인 한도는 시간이 지나며 바뀔 수 있지만, 합리적인 게시 패턴을 허용하는 방향으로 설계되어 있습니다.

큰 server.json 파일은 어떻게 처리되나요?

server.json에는 성능을 위한 크기 제한이 있습니다. 파일이 너무 크다면 다음을 고려하세요:

  • Removing unnecessary metadata
  • Using external references instead of inlining large data
  • Splitting complex servers into multiple smaller servers

다음 단계

첫 서버를 게시하는 방법을 학습하세요. 전체 API 사양을 확인하세요. 커뮤니티 토론에 참여하세요. 이슈를 보고하거나 기능 요청을 남기세요.
아직 질문이 있으신가요? 여기에서 답을 찾지 못했다면 GitHub Discussions에서 새 토론을 시작해 주세요.