MCP 레지스트리 퀵스타트 (Quickstart)¶
MCP 레지스트리 전체 문서 목록이 필요하면 /llms.txt에서 모든 페이지를 확인할 수 있어요.
MCP 레지스트리는 현재 프리뷰(preview) 상태예요. 정식 공개(GA) 전까지는 호환성이 깨지거나 데이터가 초기화될 수 있답니다. 문제가 생기면 GitHub에 리포트해 주세요.
이 튜토리얼에서는 TypeScript로 작성된 MCP 서버를 공식 mcp-publisher CLI 도구로 MCP 레지스트리에 게시하는 방법을 보여드릴게요.
사전 준비 (Prerequisites)¶
- Node.js — 이 튜토리얼은 MCP 서버가 TypeScript로 작성되어 있다고 가정해요.
- npm 계정 — MCP 레지스트리는 메타데이터만 호스팅하고 아티팩트(패키지 본체)는 호스팅하지 않아요. MCP 레지스트리에 게시하기 전에 먼저 MCP 서버의 패키지를 npm에 게시해야 하므로, npm 계정이 필요해요.
- GitHub 계정 — MCP 레지스트리는 여러 인증 방식을 지원해요. 이 튜토리얼에서는 단순함을 위해 GitHub 기반 인증을 사용할 거라 GitHub 계정이 필요해요.
TypeScript로 작성된 MCP 서버가 아직 없다면, modelcontextprotocol/quickstart-resources 저장소에서 weather-server-typescript 서버를 복사해서 튜토리얼을 따라 해 볼 수 있어요:
git clone --depth 1 [email protected]:modelcontextprotocol/quickstart-resources.git
cp -r quickstart-resources/weather-server-typescript .
rm -rf quickstart-resources
cd weather-server-typescript
그리고 package.json을 여러분의 정보에 맞게 수정하세요:
package.json
{
- "name": "mcp-quickstart-ts",
- "version": "1.0.0",
+ "name": "@my-username/mcp-weather-server",
+ "version": "1.0.1",
"main": "index.js",
package.json
"license": "ISC",
- "description": "",
+ "repository": {
+ "type": "git",
+ "url": "https://github.com/my-username/mcp-weather-server.git"
+ },
+ "description": "An MCP server for weather information.",
"devDependencies": {
1단계: 패키지에 검증 정보 추가하기¶
MCP 레지스트리는 서버의 기반이 되는 패키지가 그 메타데이터와 일치하는지 검증해요. npm 패키지의 경우 package.json에 mcpName 속성을 추가해야 해요:
package.json
{
"name": "@my-username/mcp-weather-server",
"version": "1.0.1",
+ "mcpName": "io.github.my-username/weather",
"main": "index.js",
mcpName 값이 MCP 레지스트리에서의 서버 이름이 돼요. GitHub 기반 인증을 사용할 예정이므로 mcpName은 반드시 io.github.my-username/으로 시작해야 해요.
2단계: 패키지 게시하기¶
MCP 레지스트리는 메타데이터만 호스팅하고 아티팩트는 호스팅하지 않기 때문에, 서버를 MCP 레지스트리에 게시하기 전에 먼저 패키지를 npm에 게시해야 해요. 배포 파일이 빌드되어 있는지 확인하세요:
그다음 npm의 게시 가이드를 따라 진행하세요. 특히 대체로 다음 명령을 실행하게 될 거예요:
패키지가 게시되었는지 npm URL(예: https://www.npmjs.com/package/@my-username/mcp-weather-server)을 방문해 확인할 수 있어요.
3단계: mcp-publisher 설치하기¶
mcp-publisher CLI 도구를 사전 빌드된 바이너리 또는 Homebrew로 설치하세요:
macOS/Linux
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(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
$arch = if ([System.Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }; Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile "mcp-publisher.tar.gz"; tar xf mcp-publisher.tar.gz mcp-publisher.exe; rm mcp-publisher.tar.gz
# mcp-publisher.exe를 PATH에 있는 디렉터리로 이동하세요
Homebrew
mcp-publisher가 제대로 설치되었는지 다음 명령으로 확인하세요:
다음과 같은 출력이 보이면 돼요:
Output
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
4단계: server.json 만들기¶
mcp-publisher init 명령은 프로젝트에서 파생된 일부 정보로 server.json 템플릿 파일을 생성해 줘요. 서버 프로젝트 디렉터리에서 mcp-publisher init을 실행하세요:
생성된 server.json 파일을 열면 다음과 같은 내용이 보일 거예요:
server.json
{
"$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.0",
"packages": [
{
"registryType": "npm",
"identifier": "@my-username/mcp-weather-server",
"version": "1.0.0",
"transport": {
"type": "stdio"
},
"environmentVariables": [
{
"description": "Your API key for the service",
"isRequired": true,
"format": "string",
"isSecret": true,
"name": "YOUR_API_KEY"
}
]
}
]
}
내용을 필요에 맞게 수정하세요:
server.json
{
"$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.0",
+ "version": "1.0.1",
"packages": [
{
"registryType": "npm",
"identifier": "@my-username/mcp-weather-server",
- "version": "1.0.0",
+ "version": "1.0.1",
"transport": {
"type": "stdio"
- },
- "environmentVariables": [
- {
- "description": "Your API key for the service",
- "isRequired": true,
- "format": "string",
- "isSecret": true,
- "name": "YOUR_API_KEY"
- }
- ]
+ }
}
]
}
server.json의 name 속성은 반드시 package.json의 mcpName 속성과 일치해야 해요.
5단계: MCP 레지스트리 인증하기¶
이 튜토리얼에서는 GitHub 기반 인증으로 MCP 레지스트리에 인증할 거예요. mcp-publisher login 명령을 실행해 인증을 시작하세요:
다음과 같은 출력이 보일 거예요:
Output
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...
링크를 방문해 안내를 따르고, 터미널에 출력된 인증 코드(예: 위 출력의 ABCD-1234)를 입력하세요. 완료되면 터미널로 돌아가서 다음과 같은 출력이 보일 거예요:
Output
6단계: MCP 레지스트리에 게시하기¶
마지막으로 mcp-publisher publish 명령으로 서버를 MCP 레지스트리에 게시하세요:
다음과 같은 출력이 보일 거예요:
Output
Publishing to https://registry.modelcontextprotocol.io...
✓ Successfully published
✓ Server io.github.my-username/weather version 1.0.1
MCP 레지스트리 API로 서버를 검색하면 게시되었는지 확인할 수 있어요:
검색 결과 JSON에서 여러분의 서버 메타데이터가 보일 거예요:
Output
문제 해결 (Troubleshooting)¶
| 오류 메시지 | 조치 |
|---|---|
| "Registry validation failed for package" | 패키지에 필요한 검증 정보(예: package.json의 mcpName 속성)가 포함되어 있는지 확인하세요. |
| "Invalid or expired Registry JWT token" | mcp-publisher login github을 실행해 다시 인증하세요. |
| "You do not have permission to publish this server" | 인증 방식이 서버의 네임스페이스 형식과 일치하지 않아요. GitHub 인증을 사용한다면 서버 이름이 io.github.your-username/으로 시작해야 해요. |
다음 단계 (Next Steps)¶
- 다른 패키지 유형 지원에 대해 알아보기
- 원격 서버 지원에 대해 알아보기
- 다른 인증 방식 사용법 배우기 — 예를 들어 DNS 인증은 서버 이름 접두사에 커스텀 도메인을 사용할 수 있게 해줘요.
- GitHub Actions로 게시 자동화 배우기