본문 바로가기
삵
AI

MCP 서버를 공식 레지스트리에 등록하기

포포스트맨·2026년 11월 18일·조회 0

MCP 서버를 하나 만들어서 사내에서만 돌리다 보면, "이거 남들도 쓰게 공개 목록에 올릴 수 없나" 하는 질문을 받게 된다. 예전에는 README에 설치법을 적고 각자 설정 파일에 손으로 등록하는 방식뿐이었는데, 이제는 Anthropic과 GitHub, Microsoft, PulseMCP가 함께 운영하는 공식 레지스트리가 생겼다. 등록은 무료이고 심사 단계도 없다.

핵심만 먼저 적으면, 공개 등록은 server.json 한 장을 작성해 mcp-publisher CLI로 올리는 작업이다. 레지스트리는 메타데이터만 보관하므로 실제 패키지(npm, PyPI 등)나 원격 엔드포인트는 미리 배포돼 있어야 한다. 등록할 이름의 네임스페이스는 GitHub 로그인이나 도메인 인증으로 소유권을 증명한다.

레지스트리는 메타데이터만 들고 있다

공식 MCP Registry(registry.modelcontextprotocol.io)는 공개된 MCP 서버의 목록을 담는 카탈로그다. 서버의 코드나 패키지 자체를 호스팅하지 않고, "이 이름의 서버는 이 패키지를 이 방식으로 실행한다"는 정보만 저장한다.

그래서 순서가 중요하다. npm이나 PyPI 같은 아티팩트 레지스트리에 패키지를 먼저 올리고, 그다음 그 패키지를 가리키는 메타데이터를 MCP Registry에 등록한다. 원격으로만 접근하는 서버라면 패키지 없이 공개된 remotes 엔드포인트 정보만 올려도 된다.

2025년 11월 기준 레지스트리는 preview 상태다. 스키마나 데이터가 정식 출시 전에 바뀔 수 있다는 점은 감안하고 시작하는 편이 맞다.

server.json 한 장이 전부다

먼저 CLI를 설치한다. macOS나 Linux는 릴리스 바이너리를 받거나 Homebrew를 쓴다.

$ brew install mcp-publisher
$ mcp-publisher --help
MCP Registry Publisher Tool

Usage:
  mcp-publisher <command> [arguments]

Commands:
  init          Create a server.json file template
  login         Authenticate with the registry
  logout        Clear saved authentication
  publish       Publish server.json to the registry
  status        Update the status of a server version
  validate      Validate server.json without publishing

서버 프로젝트 디렉터리에서 mcp-publisher init을 실행하면 프로젝트 정보를 긁어 server.json 초안을 만들어 준다. npm 패키지 기반이면 대략 이런 모양이 나온다.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "An MCP server for weather information.",
  "repository": {
    "url": "https://github.com/my-username/mcp-weather-server",
    "source": "github"
  },
  "version": "1.0.1",
  "packages": [
    {
      "registryType": "npm",
      "identifier": "@my-username/mcp-weather-server",
      "version": "1.0.1",
      "transport": { "type": "stdio" }
    }
  ]
}

여기서 두 가지를 꼭 맞춰야 한다. 첫째, description은 100자를 넘기면 검증에서 떨어진다. 서버가 무엇을 하는지만 간결하게 적는다. 둘째, npm의 경우 소유권 증명을 위해 package.json에 mcpName 필드를 넣고, 그 값이 server.json의 name과 정확히 같아야 한다.

{
  "name": "@my-username/mcp-weather-server",
  "version": "1.0.1",
  "mcpName": "io.github.my-username/weather",
  "main": "index.js"
}

PyPI나 NuGet은 package.json 대신 패키지 README에 mcp-name: io.github.my-username/weather 한 줄을 넣는 방식으로 소유권을 표시한다. 패키지 타입마다 마커 위치가 다르니 그 부분만 확인하면 나머지 순서는 같다.

원격 전용 서버라면 packages를 지우고 remotes를 넣는다. mcp-publisher init이 packages를 생성하더라도 직접 바꿔 주면 된다.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.my-username/weather",
  "description": "A remote MCP server for weather information.",
  "version": "1.0.0",
  "remotes": [
    { "type": "streamable-http", "url": "https://weather.example.com/mcp" }
  ]
}

네임스페이스를 증명하는 세 가지 로그인

어떤 인증을 쓰느냐에 따라 서버 이름의 앞부분(네임스페이스)이 정해진다. GitHub 로그인을 쓰면 이름은 반드시 io.github.사용자명/* 형태여야 하고, 도메인 인증을 쓰면 com.example.*/* 처럼 도메인을 역순으로 뒤집은 형태여야 한다.

가장 간단한 길은 GitHub OAuth다. 디바이스 코드가 뜨면 브라우저에서 승인한다.

$ mcp-publisher login github
Logging in with github...

To authenticate, please:
1. Go to: https://github.com/login/device
2. Enter code: ABCD-1234
3. Authorize this application
Waiting for authorization...

Successfully authenticated!
✓ Successfully logged in

여기서 자주 걸리는 지점이 있다. 개인 네임스페이스(io.github.본인아이디/*)는 이 디바이스 플로우로 바로 되지만, 조직 네임스페이스(io.github.조직명/*)는 현재 이 방식으로 올라가지 않는다. GitHub App 사용자 토큰이 조직 멤버십을 못 읽어서, 레지스트리가 조직 소유권을 확인하지 못하기 때문이다. 조직 이름으로 올리려면 GitHub Actions의 OIDC를 쓰거나, read:org 권한이 있는 Personal Access Token으로 로그인한다.

$ mcp-publisher login github --token <YOUR_TOKEN>

자체 도메인을 네임스페이스로 쓰고 싶으면 DNS 인증을 선택한다. 도메인 apex에 TXT 레코드를 심는다. 여기서 한 번 크게 막히는데, 레코드를 _mcp-auth.example.com 같은 셀렉터 밑에 넣으면 레지스트리가 못 찾고 서명 오류로 떨어진다. SPF처럼 apex(example.com)에 직접 올려야 한다.

$ MY_DOMAIN="example.com"
$ openssl genpkey -algorithm Ed25519 -out key.pem
$ PUBLIC_KEY="$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)"
$ echo "${MY_DOMAIN}. IN TXT \"v=MCPv1; k=ed25519; p=${PUBLIC_KEY}\""
example.com. IN TXT "v=MCPv1; k=ed25519; p=CmELkdW27Q+pySZRD1ezkXAG/SbeDhGWAjtuKKMKixg="

레코드를 넣고 전파를 기다린 뒤, 개인키로 로그인한다. 올리기 전에 dig TXT example.com +short로 apex에 실제로 떠 있는지 확인하면 삽질을 줄인다.

$ PRIVATE_KEY="$(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')"
$ mcp-publisher login dns --domain "example.com" --private-key "${PRIVATE_KEY}"

DNS를 못 건드리는 환경이면 HTTP 인증도 있다. 같은 증명 문자열을 https://도메인/.well-known/mcp-registry-auth에 평문으로 호스팅하는 방식이다. 주의할 점은 레지스트리가 Google Cloud에서 그 URL을 직접 긁어 간다는 것이다. 내 노트북에서 curl이 되더라도, WAF나 봇 차단, 리다이렉트(3xx)가 걸려 있으면 token exchange failed with status 401로 실패한다. 리다이렉트 없이 200으로 평문을 돌려줘야 한다.

$ curl -sS -o - -w '\n%{http_code}\n' \
  -H 'Accept: text/plain' \
  -A 'mcp-registry/1.0' \
  https://example.com/.well-known/mcp-registry-auth

publish 전에 validate로 거른다

로그인이 끝났으면 바로 publish하지 말고 먼저 검증한다. 스키마 위반이나 길이 초과를 미리 잡아 준다.

$ mcp-publisher validate
$ mcp-publisher publish
Publishing to https://registry.modelcontextprotocol.io...
✓ Successfully published
✓ Server io.github.my-username/weather version 1.0.1

여기서 가장 흔한 에러 두 개가 이렇게 나온다. 패키지에 소유권 마커가 없으면 Registry validation failed for package가 뜬다. npm이면 package.json의 mcpName을, PyPI면 README의 mcp-name 줄을 확인한다. 그리고 You do not have permission to publish this server는 인증 방식과 이름 형식이 어긋났을 때다. GitHub 로그인인데 이름이 io.github.본인아이디/로 시작하지 않으면 이 에러가 난다.

등록이 됐는지는 검색 API로 바로 확인한다.

$ curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=io.github.my-username/weather"
{"servers":[{ ... "name":"io.github.my-username/weather" ... }]}

같은 이름에 버전을 올려 쌓는다

업데이트는 어렵지 않다. 코드와 패키지를 새 버전으로 올린 뒤, server.json의 version과 packages[].version을 같이 올리고 다시 publish한다. 이름(name)은 그대로 두면 레지스트리가 같은 서버의 새 버전으로 쌓는다. 버전 문자열은 semver를 따른다.

더 이상 쓰지 말라고 알리고 싶을 때는 mcp-publisher status로 특정 버전의 상태를 바꾼다. 패키지를 내려도 레지스트리의 메타데이터는 자동으로 사라지지 않으므로, 폐기할 버전은 상태를 손봐 주는 편이 소비자 쪽 혼란을 줄인다.

네임스페이스는 소유권과 묶여 있다는 점을 기억하면 운영이 단순해진다. 개인 프로젝트는 io.github.본인아이디로, 팀 제품은 도메인 인증을 받아 com.회사도메인으로 가져가면 이름 충돌 걱정이 없다.

.well-known Server Card는 아직 초안이다

레지스트리가 중앙 목록이라면, 반대 방향의 디스커버리도 논의되고 있다. 서버가 자기 도메인의 /.well-known/mcp-server-card에 자신을 설명하는 카드를 직접 걸어 두면, 클라이언트나 레지스트리가 그 URL을 긁어 서버를 찾아내는 방식이다. 한 도메인에서 여러 서버를 돌리면 /.well-known/mcp-server-card/{server-name}처럼 하위 경로로 나눈다.

카드의 내용은 server.json과 모양을 맞춰 두었다. name, version, description, repository, remotes 같은 필드를 그대로 쓰므로 파서를 하나만 유지하면 된다.

다만 이 Server Card는 SEP 단계의 Draft다. 정식(Final)이 되려면 레퍼런스 구현이 필요하다고 명시돼 있어서, 경로나 필드가 바뀔 여지가 있다. 지금 공개 등록을 확실히 하고 싶다면 레지스트리에 publish하는 길이 안정적이다. Server Card는 같은 server.json 데이터를 재활용하는 보완 수단으로 보고, 스펙이 굳을 때 자기 도메인에 얹어도 늦지 않다.

자주 묻는 질문

MCP Registry에 패키지 코드도 같이 올라가나

아니다. 레지스트리는 메타데이터만 보관한다. 실제 실행 파일은 npm이나 PyPI 같은 아티팩트 레지스트리에 먼저 배포하거나, 원격 서버라면 공개 엔드포인트가 접근 가능해야 한다. server.json은 그것을 가리키는 포인터 역할만 한다.

GitHub 조직 이름으로 서버를 올리려는데 권한 오류가 난다

mcp-publisher login github의 디바이스 플로우는 현재 조직 네임스페이스로 publish하지 못한다. GitHub App 사용자 토큰이 조직 멤버십을 읽지 못하기 때문이다. GitHub Actions의 OIDC로 발행하거나, read:org 권한이 있는 Personal Access Token으로 login github --token을 쓴다.

server.json의 name과 package.json의 mcpName이 달라도 되나

안 된다. 두 값이 정확히 같아야 한다. 다르면 소유권 검증에서 Registry validation failed for package 또는 publish 권한 오류가 난다. 또 GitHub 인증이면 두 값 모두 io.github.사용자명/ 으로 시작해야 한다.

DNS 인증 TXT 레코드는 어디에 넣어야 하나

도메인 apex(예: example.com)에 직접 넣는다. _mcp-auth.example.com 같은 셀렉터 하위에 넣으면 레지스트리가 찾지 못하고 서명 오류로 실패한다. dig TXT example.com +short로 apex에 떠 있는지 먼저 확인하는 것이 좋다.

등록한 서버의 버전을 올리려면 어떻게 하나

패키지를 새 버전으로 배포한 뒤 server.json의 version과 packages의 version을 올리고 다시 publish한다. name을 그대로 두면 같은 서버의 새 버전으로 쌓인다. 폐기할 버전은 mcp-publisher status로 상태를 바꿔 소비자에게 알린다.

관련 글

댓글 0

로그인 후 댓글을 남길 수 있습니다.

아직 댓글이 없습니다.