MCP 서버 게시하기
공식 MCP Registry에 MCP 서버를 게시하는 전체 가이드입니다.
AI 코딩 어시스턴트를 위한 프롬프트
빠르게 게시 작업을 진행하려면 아래 프롬프트를 사용하세요:
Read https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/publish-server.md and https://raw.githubusercontent.com/modelcontextprotocol/registry/refs/heads/main/docs/guides/publishing/github-actions.md. Evaluate the best way to publish this server to the registry (prefer automated CI flows over manual flows where possible), and implement that. If possible, validate the server.json against the $schema before telling the user you are done, using a proper json schema library or tool available on the user's machine.이 문서에서 배우는 것
이 튜토리얼을 끝내면 다음을 완료하게 됩니다:
- MCP 서버용
server.json생성 - Registry 인증
- 서버 게시 성공
- Registry에서 서버가 노출되는지 확인
사전 준비
- 이미 빌드한 MCP 서버(아직 없다면 이 가이드를 참고하세요)
배포 옵션 개요
MCP 서버는 여러 방식으로 제공할 수 있습니다:
📦 Package Deployment
레지스트리(npm, PyPI, NuGet, Docker Hub 등)에 게시하고, 클라이언트가 로컬에서 실행합니다.
🌐 Remote Deployment
클라이언트가 직접 연결하는 웹 서비스로 호스팅합니다.
🔄 Hybrid Deployment
유연성을 위해 패키지/원격 방식을 모두 제공합니다.
공식 문서에서 MCP 서버 아키텍처를 더 자세히 확인할 수 있습니다.
단계 1: Publisher CLI 설치
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/macOS/Linux/WSL: 소스에서 빌드
Git, Make, Go 1.24+가 필요합니다:
# Clone the registry repository
git clone https://github.com/modelcontextprotocol/registry
cd registry
make publisher
# The binary will be at bin/mcp-publisher
export PATH=$PATH:$(pwd)/binWindows 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
# Move mcp-publisher.exe to a directory in your PATH단계 2: server.json 초기화
서버 디렉터리로 이동한 뒤 템플릿을 생성합니다:
cd /path/to/your/mcp-server
mcp-publisher init자동 감지된 값으로 server.json이 생성됩니다. 예시는 다음과 같습니다:
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "io.github.yourname/your-server",
"description": "A description of your MCP server",
"version": "1.0.0",
"packages": [
{
"registry_type": "npm",
"identifier": "your-package-name",
"version": "1.0.0"
}
]
}단계 3: 서버 상세 설정
생성된 server.json을 편집합니다:
네임스페이스 선택
name 필드가 인증 요구사항을 결정합니다:
io.github.yourname/*- GitHub 인증 필요com.yourcompany/*- DNS 또는 HTTP 도메인 검증 필요
배포 방식 설정
서버가 패키지 배포, 원격 배포, 또는 둘 다를 지원하도록 구성합니다:
Package Deployment
패키지 소유권을 증명하기 위한 검증 메타데이터를 추가합니다.
NPM Packages
Requirements
package.json에 mcpName 필드를 추가합니다:
{
"name": "your-npm-package",
"version": "1.0.0",
"mcpName": "io.github.username/server-name"
}How It Works
- Registry가
https://registry.npmjs.org/your-npm-package를 조회합니다. mcpName필드가 서버 이름과 일치하는지 확인합니다.- 필드가 없거나 일치하지 않으면 실패합니다.
Example server.json
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "npm",
"identifier": "your-npm-package",
"version": "1.0.0"
}
]
}공식 MCP Registry는 현재 NPM 공개 레지스트리(https://registry.npmjs.org)만 지원합니다.
PyPI Packages
Requirements
패키지 README에 아래 형식으로 서버 이름을 포함합니다:
MCP name format: mcp-name: io.github.username/server-name
이를 README.md에 추가하세요(PyPI에서 패키지 설명으로 노출됩니다). 다른 곳에 보이지 않게 하고 싶다면 주석(comment) 형태로 넣어도 됩니다.
How It Works
- Registry가
https://pypi.org/pypi/your-package/json를 조회합니다. - README 콘텐츠에
mcp-name: server-name가 포함되어 있으면 통과합니다.
Example server.json
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "pypi",
"identifier": "your-pypi-package",
"version": "1.0.0"
}
]
}공식 MCP Registry는 현재 공식 PyPI(https://pypi.org)만 지원합니다.
NuGet Packages
Requirements
패키지 README에 아래 형식으로 서버 이름을 포함합니다:
MCP name format: mcp-name: io.github.username/server-name
NuGet 패키지에 README를 포함하고 그 안에 서버 이름을 넣으세요. 다른 곳에 보이지 않게 하려면 주석(comment) 형태로 넣어도 됩니다.
How It Works
- Registry가
https://api.nuget.org/v3-flatcontainer/{id}/{version}/readme에서 README를 가져옵니다. - README 콘텐츠에서
mcp-name: server-name를 찾으면 통과합니다.
Example server.json
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "nuget",
"identifier": "Your.NuGet.Package",
"version": "1.0.0"
}
]
}공식 MCP Registry는 현재 공식 NuGet(https://api.nuget.org)만 지원합니다.
Docker/OCI Images
Requirements
Docker 이미지에 아래 어노테이션(라벨)을 추가합니다:
LABEL io.modelcontextprotocol.server.name="io.github.username/server-name"How It Works
- Registry가 토큰 기반 인증으로 컨테이너 레지스트리에 인증합니다.
- Docker Registry v2 API로 이미지 매니페스트를 가져옵니다.
io.modelcontextprotocol.server.name어노테이션이 서버 이름과 일치하는지 확인합니다.- 어노테이션이 없거나 일치하지 않으면 실패합니다.
Example server.json (Docker Hub)
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "oci",
"registry_base_url": "https://docker.io",
"identifier": "yourusername/your-mcp-server",
"version": "1.0.0"
}
]
}Example server.json (GitHub Container Registry)
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "oci",
"registry_base_url": "https://ghcr.io",
"identifier": "yourusername/your-mcp-server",
"version": "1.0.0"
}
]
}공식 MCP Registry는 현재 Docker Hub(https://docker.io)와 GitHub Container Registry(https://ghcr.io)를 지원합니다.
MCPB Packages
Requirements
MCP 참조 - 올바른 아티팩트가 업로드되었는지 확인하기 위해, MCPB 패키지 URL에는 어딘가에 “mcp"가 포함되어야 합니다. 이는 .mcpb 확장자이거나 저장소 이름에 포함되는 형태일 수 있습니다.
파일 무결성 - MCPB 패키지는 파일 무결성 검증을 위해 SHA-256 해시를 포함해야 합니다. 게시 시 필수이며, MCP 클라이언트는 설치 전에 이 해시를 검증합니다.
How to Generate File Hashes
MCPB 파일의 SHA-256 해시를 계산합니다:
openssl dgst -sha256 server.mcpbExample server.json
{
"name": "io.github.username/server-name",
"packages": [
{
"registry_type": "mcpb",
"identifier": "https://github.com/you/your-repo/releases/download/v1.0.0/server.mcpb",
"file_sha256": "fe333e598595000ae021bd27117db32ec69af6987f507ba7a63c90638ff633ce"
}
]
}File Hash Validation
- **작성자(Authors)**는
server.json을 만들 때 올바른 SHA-256 해시를 생성할 책임이 있습니다. - MCP 클라이언트는 설치 전에 해시를 검증해 파일 무결성을 확인합니다.
- 공식 Registry는 해시를 저장하지만 검증하지는 않습니다.
- **서브레지스트리(Subregistry)**는 자체 검증을 구현할 수 있습니다.
공식 MCP Registry는 현재 GitHub 또는 GitLab Releases에 호스팅된 아티팩트만 지원합니다.
Remote Deployment
server.json에 remotes 필드를 추가합니다(packages와 공존 가능):
Remote Server Configuration
Requirements
- 서비스 엔드포인트: 지정한 URL에서 MCP 서버에 접근 가능해야 합니다.
- 전송 프로토콜:
sse(Server-Sent Events) 또는streamable-http중 선택합니다. - URL 검증: 도메인 네임스페이스에서만 적용됩니다(아래 URL 요구사항 참고).
Example server.json
{
"$schema": "https://static.modelcontextprotocol.io/schemas/2025-07-09/server.schema.json",
"name": "com.yourcompany/api-server",
"description": "Cloud-hosted MCP server for API operations",
"version": "2.0.0",
"remotes": [
{
"type": "sse",
"url": "https://mcp.yourcompany.com/sse"
}
]
}URL Validation Requirements
com.yourcompany/*네임스페이스: URL은yourcompany.com또는 그 하위 도메인이어야 합니다.io.github.username/*네임스페이스: URL 제한은 없지만 GitHub로 인증해야 합니다.
단계 4: 인증
네임스페이스에 따라 인증 방식을 선택합니다:
GitHub 인증(io.github.* 네임스페이스)
mcp-publisher login github브라우저가 열리며 OAuth 인증을 진행합니다.
DNS 인증(커스텀 도메인)
# Generate keypair
openssl genpkey -algorithm Ed25519 -out key.pem
# Get public key for DNS record
echo "yourcompany.com. IN TXT \"v=MCPv1; k=ed25519; p=$(openssl pkey -in key.pem -pubout -outform DER | tail -c 32 | base64)\""
# Add the TXT record to your DNS, then login
mcp-publisher login dns --domain yourcompany.com --private-key $(openssl pkey -in key.pem -noout -text | grep -A3 "priv:" | tail -n +2 | tr -d ' :\n')단계 5: 서버 게시
인증이 완료되면 서버를 게시합니다:
mcp-publisher publish다음과 같은 출력이 표시됩니다:
✓ Successfully published단계 6: 게시 확인
검색을 통해 서버가 Registry에 표시되는지 확인합니다:
curl "https://registry.modelcontextprotocol.io/v0/servers?search=io.github.yourname/weather-server"JSON 응답에 서버 메타데이터가 반환되어야 합니다.
문제 해결
“Package validation failed” - 패키지에 필요한 검증 메타데이터(mcpName 필드, README 표기, Docker 라벨)가 포함되어 있는지 확인하세요.
“Authentication failed” - DNS 레코드를 올바르게 설정했는지, 또는 올바른 GitHub 계정으로 로그인했는지 확인하세요.
“Namespace not authorized” - 선택한 네임스페이스 형식과 인증 방식이 일치하지 않습니다.
예시
실제 게시된 서버 예시는 다음을 참고하세요:
다음 단계
완료한 내용
첫 번째 MCP 서버를 Registry에 성공적으로 게시했습니다. 이제 MCP 클라이언트에서 검색할 수 있으며, 전 세계 사용자가 설치할 수 있습니다.