MCP Publisher CLI 도구

mcp-publisher는 MCP Registry와 상호작용하기 위한 공식 커맨드라인 도구로, 서버 게시(publish), 인증, 관리 기능을 제공합니다.

설치

Homebrew(권장)

macOS/Linux에서 Homebrew를 사용하는 경우:

brew install mcp-publisher

사전 빌드 바이너리

macOS/Linux/WSL:

curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

Windows PowerShell:

$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/download/v1.0.0/mcp-publisher_1.0.0_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"
tar xf mcp-publisher.tar.gz mcp-publisher.exe
rm mcp-publisher.tar.gz

소스에서 빌드

git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher
# Binary will be at bin/mcp-publisher

전역 옵션

모든 명령어는 다음 옵션을 지원합니다:

• --help, -h - 명령어 도움말 표시
• --registry - Registry URL(기본: https://registry.modelcontextprotocol.io)

명령어 레퍼런스

mcp-publisher init

자동 감지 기능으로 server.json 템플릿을 생성합니다.

Usage:

mcp-publisher init [options]

Behavior:

• 현재 디렉터리에 server.json을 생성합니다.
• 패키지 매니저(package.json, setup.py 등)를 자동 감지합니다.
• 가능한 필드는 자동으로 채웁니다.
• 필수 값이 비어 있으면 입력을 요청합니다.

Example output:

{
  "name": "io.github.username/server-name",
  "description": "TODO: Add server description",
  "version": "1.0.0",
  "packages": [
    {
      "registry_type": "npm",
      "identifier": "detected-package-name",
      "version": "1.0.0"
    }
  ]
}

mcp-publisher login <method>

Authenticate with the registry.

Registry에 인증합니다.

GitHub Interactive

mcp-publisher login github [--registry=URL]

• 브라우저가 열리며 GitHub OAuth 플로우를 진행합니다.
• io.github.{username}/* 및 io.github.{org}/* 네임스페이스에 대한 접근 권한을 부여합니다.

GitHub OIDC (CI/CD)

mcp-publisher login github-oidc [--registry=URL]

• GitHub Actions OIDC 토큰을 자동으로 사용합니다.
• 워크플로에 id-token: write 권한이 필요합니다.
• 브라우저 상호작용이 필요 없습니다.

DNS Verification

mcp-publisher login dns --domain=example.com --private-key=HEX_KEY [--registry=URL]

• DNS TXT 레코드로 도메인 소유권을 검증합니다.
• com.example.* 네임스페이스에 대한 접근 권한을 부여합니다.
• Ed25519 개인키(64자리 hex)가 필요합니다.

설정 단계:

# Generate Ed25519 keypair
openssl genpkey -algorithm Ed25519 -out key.pem

# Get public key for DNS record
openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64

# Add DNS TXT record:
example.com. IN TXT "v=MCPv1; k=ed25519; p=PUBLIC_KEY"

# Extract private key for login
openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n'

HTTP Verification

mcp-publisher login http --domain=example.com --private-key=HEX_KEY [--registry=URL]

• HTTPS 엔드포인트로 도메인 소유권을 검증합니다.
• com.example.* 네임스페이스에 대한 접근 권한을 부여합니다.
• Ed25519 개인키(64자리 hex)가 필요합니다.

설정:

# Generate keypair (same as DNS)
openssl genpkey -algorithm Ed25519 -out key.pem

# Host public key at:
# https://example.com/.well-known/mcp-registry-auth
# Content: v=MCPv1; k=ed25519; p=PUBLIC_KEY

Anonymous (Testing)

mcp-publisher login none [--registry=URL]

• 인증 없음(로컬 테스트 전용)
• 로컬 Registry 인스턴스에서만 동작

mcp-publisher publish

Publish server to the registry.

서버를 Registry에 게시합니다.

Usage:

mcp-publisher publish [options]

Options:

• --file=PATH - server.json 경로(기본: ./server.json)
• --registry=URL - Registry URL 재정의
• --dry-run - 게시 없이 검증만 수행

Process:

1. 스키마로 server.json을 검증
2. 패키지 소유권 검증(Official Registry Requirements 참고)
3. 네임스페이스 인증 확인
4. Registry에 게시

Examples:

# Basic publish
mcp-publisher publish

# Dry run validation
mcp-publisher publish --dry-run

# Custom file location
mcp-publisher publish --file=./config/server.json

mcp-publisher logout

저장된 인증 정보를 제거합니다.

Usage:

mcp-publisher logout

Behavior:

• ~/.mcp_publisher_token 파일을 제거합니다.
• 서버 측 토큰 폐기(revoke)는 수행하지 않습니다.

설정

토큰 저장

인증 토큰은 ~/.mcp_publisher_token에 JSON 형태로 저장됩니다:

{
  "token": "jwt-token-here",
  "registry_url": "https://registry.modelcontextprotocol.io",
  "expires_at": "2024-12-31T23:59:59Z"
}

네임스페이스 및 보안

네임스페이스 형식

모든 서버 이름은 reverse-DNS 형식을 따릅니다:

• io.github.alice/weather-server - GitHub 사용자 alice
• com.acme/internal-tool - 회사 도메인 acme.com
• org.nonprofit.research/data-analyzer - 서브도메인 research.nonprofit.org

소유권 검증

네임스페이스에 게시하려면 해당 아이덴티티를 실제로 제어하고 있음을 증명해야 합니다:

GitHub namespaces (io.github.*):

• GitHub 계정/조직으로 OAuth 로그인
• GitHub Actions 워크플로의 OIDC 토큰

Domain namespaces (com.company.*):

• DNS 검증: company.com에 TXT 레코드 추가
• HTTP 검증: https://company.com/.well-known/mcp-registry-auth에 파일 제공

네임스페이스 범위

인증 방식에 따라 접근 가능한 네임스페이스 범위가 달라집니다:

GitHub OAuth/OIDC:

• io.github.username/* (개인 계정)
• io.github.orgname/* (조직)

DNS verification:

• com.domain/* 및 com.domain.*/* (도메인 + 모든 하위 도메인)

HTTP verification:

• com.domain/*만 (정확한 도메인, 하위 도메인 제외)

버저닝 모범 사례

시맨틱 버저닝

서버 작성자는 MAJOR.MINOR.PATCH 형식의 시맨틱 버전 사용을 권장합니다:

{
  "version": "1.2.3"
}

패키지 버전과 정렬

혼선을 줄이기 위해, 서버 버전은 기반 패키지 버전과 맞추는 것을 권장합니다:

{
  "version": "1.2.3",
  "packages": [{
    "registry_type": "npm",
    "identifier": "@myorg/my-server",
    "version": "1.2.3"
  }]
}

Multiple Registry Versions

같은 패키지 버전에 대해 Registry 버전을 여러 개 운용해야 한다면 프리릴리즈(prerelease) 라벨을 사용하세요:

{
  "version": "1.2.3-1",
  "packages": [{
    "registry_type": "npm", 
    "identifier": "@myorg/my-server",
    "version": "1.2.3"
  }]
}

자주 쓰는 사용 시나리오

기본 워크플로

# 1. Initialize server.json
mcp-publisher init

# 2. Edit generated server.json

# 3. Authenticate
mcp-publisher login github

# 4. Publish
mcp-publisher publish

CI/CD 워크플로

# In GitHub Actions
mcp-publisher login github-oidc
mcp-publisher publish

버전 업데이트

# Update version in server.json
# Then republish
mcp-publisher publish

문제 해결

“Authentication failed”

• OIDC의 경우 워크플로에 id-token: write 권한이 설정되어 있는지 확인하세요.
• 시크릿 또는 토큰 설정을 점검하세요.

“Package validation failed”

• 먼저 패키지가 레지스트리(NPM, PyPI 등)에 정상적으로 게시되어 있는지 확인하세요.
• 필요한 검증 단계를 모두 수행했는지 확인하세요.

“Namespace not authorized”

• 선택한 네임스페이스 형식과 인증 방식이 일치하지 않습니다.

“Version already exists”

• 동일한 서버 이름에 대해 버전은 모두 고유해야 합니다.
• 새 버전 번호 또는 프리릴리즈 라벨을 사용하세요.

다음 단계