4부 18장. 내 MCP 서버를 세상에 내보내기

PKM-MCP는 이제 제법 그럴듯하다. 메모를 읽고, 쓰고, 검색하고, 의미를 찾아주고, OAuth로 사용자를 구분하고, Cloudflare Workers에도 올라가 있다. 여기까지 오면 흔히 이런 생각이 든다.

"배포했으니 공개한 거 아닌가요?"

아쉽지만 아직 반만 맞았다.

배포는 서버를 올리는 일이고, 공개는 사람들이 그 서버를 발견하고, 이해하고, 믿고, 계속 쓸 수 있게 만드는 일이다. 서버 주소 하나만 던져 놓는다고 공개가 되지는 않는다. 간판도 있어야 하고, 사용 설명서도 있어야 하고, 다음 버전에서 무엇이 안 깨질지에 대한 약속도 있어야 한다.¹²

이 장에서는 PKM-MCP v1.0을 진짜 "세상에 내보내는" 과정을 정리한다. 핵심은 네 가지다. MCP Registry에 등록해 발견 가능성을 만들고, README와 Server Card로 이해 가능성을 높이고, 버전 정책으로 예측 가능성을 보장하고, Smithery나 MintMCP 같은 플랫폼을 통해 유통 전략까지 갖추는 것이다.¹³

배포와 공개는 왜 다른가

배포는 문을 여는 일이다. 공개는 문 앞에 간판, 주소, 이용 시간, 출입 조건, 내부 안내도까지 붙이는 일이다.

예를 들어 누군가가 PKM-MCP를 처음 본다고 해보자. 그 사람은 최소한 다음 질문에 답을 얻어야 한다.

• 이 서버는 무슨 문제를 해결하나?

• 로컬 설치형인가, 원격 접속형인가?

• 인증은 어떻게 하나?

• 어떤 Tool과 Resource를 제공하나?

• 다음 달에 업데이트되면 내 자동화가 깨지지는 않나?

이 질문들에 답이 없으면 서버는 존재해도 쓰이기 어렵다. 반대로 이 답이 명확하면, 작은 개인 프로젝트도 꽤 믿음직한 제품처럼 보인다. MCP 생태계에서 공개는 결국 찾을 수 있음, 설명되어 있음, 약속이 있음의 조합이다.¹³

18.1 MCP Registry에 등록하기

공식 MCP Registry는 MCP 서버의 코드를 직접 호스팅하는 곳이 아니다. 더 정확히 말하면, 어디서 설치하거나 어디로 접속해야 하는지 알려주는 메타데이터의 원본 저장소에 가깝다.¹³ 이 점이 중요하다. PKM-MCP의 실제 실행 위치는 Cloudflare Workers일 수 있고, 로컬 설치용 패키지는 npm이나 PyPI에 있을 수 있다. 레지스트리는 그 사실을 한곳에 정리해 두는 안내 데스크다.

그래서 Registry 등록의 핵심 파일은 server.json이다. 이 파일에는 서버의 이름, 버전, 설명, 저장소 주소, 그리고 설치 가능한 패키지나 원격 접속 주소가 들어간다. 이름은 역방향 DNS 스타일의 네임스페이스를 쓰는 것이 일반적이며, GitHub 기반으로 공개할 때는 io.github.<username>/... 형식이 자주 쓰인다.²³

PKM-MCP는 이미 Cloudflare Workers에서 원격 서버로 운영하고 있으니, v1.0의 기준 배포 형태를 remote-first로 잡는 편이 자연스럽다. 그러면 packages보다 remotes가 중심이 된다. 예를 들면 이런 식이다.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.honggildong/pkm-mcp",
  "version": "1.0.0",
  "description": "Personal knowledge MCP server for note CRUD, RAG search, and weekly summaries.",
  "title": "PKM-MCP",
  "websiteUrl": "https://pkm.example.com",
  "repository": {
    "url": "https://github.com/honggildong/pkm-mcp",
    "source": "github"
  },
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  ]
}

이 매니페스트가 하는 일은 단순하지만 강력하다. "PKM-MCP라는 서버가 있고, 현재 버전은 1.0.0이며, 이 URL로 붙으면 된다"를 표준 형식으로 선언하는 것이다. 클라이언트나 서브레지스트리, 마켓플레이스가 이 정보를 읽고 서버를 소개하거나 연결 흐름을 자동화할 수 있다.¹³

공개 절차도 생각보다 단순하다. GitHub 네임스페이스를 쓴다면 mcp-publisher로 로그인하고 server.json을 발행하면 된다.²³

mcp-publisher login github
mcp-publisher publish .mcp/server.json

처음에는 실제 등록 전에 유효성 검사만 해보는 습관이 좋다.

mcp-publisher publish --dry-run

만약 PKM-MCP를 나중에 npm 패키지나 PyPI 패키지로도 배포한다면, 거기서부터는 "이 패키지가 정말 이 서버 이름의 소유자인가?"를 증명해야 한다. npm은 package.json의 mcpName, PyPI나 NuGet은 README 안의 선언, Docker는 이미지 라벨처럼 레지스트리별 소유권 검증 방법이 다르다.²³

여기서 꼭 기억할 문장이 하나 있다.

Registry 등록은 마케팅이 아니라 식별과 신뢰의 출발점이다.

검색 결과에 보이는 것만으로는 부족하다. 누가 만든 서버인지, 어디로 접속하는지, 지금 살아 있는 최신 버전이 무엇인지를 기계도 사람도 이해할 수 있어야 한다.

18.2 README와 Server Card 잘 쓰기

Registry가 "전화번호부"라면 README는 "첫인상"이다. 그리고 Server Card는 기계가 읽는 명함이다. 셋은 서로 다른 역할을 하지만, 같은 서버에 대해 같은 이야기를 해야 한다.

README를 쓸 때 가장 흔한 실수는 구현자 시점으로만 쓰는 것이다. 예를 들어 "FastMCP 기반", "Workers 배포", "D1 사용" 같은 정보는 중요하지만, 사용자는 먼저 이런 걸 알고 싶다. "그래서 이걸 쓰면 무엇이 편해지나?"

좋은 README는 기술 소개서이면서 동시에 운영 안내서다. PKM-MCP v1.0의 README 첫 부분에는 최소한 다음 내용이 들어가야 한다.

• 어떤 문제를 해결하는지

• 누구를 위한 서버인지

• 어떻게 연결하는지

• 어떤 도구를 제공하는지

• 인증과 권한이 어떻게 동작하는지

• 제한 사항과 안전장치가 무엇인지

예를 들어 README의 도입부는 이렇게 쓸 수 있다.

# PKM-MCP

PKM-MCP is a remote MCP server for personal knowledge workflows.
It lets AI clients search notes, create and edit notes, run semantic retrieval,
and render note cards through a lightweight MCP Apps UI.

## Who this is for
- 개인 메모와 프로젝트 기록을 AI와 함께 다루고 싶은 사용자
- 읽기 전용 검색을 넘어서 쓰기 자동화까지 원하는 팀
- OAuth 기반의 사용자 격리와 감사 로그가 필요한 운영 환경

## Endpoint
- Streamable HTTP: `https://mcp.example.com/mcp`

## Authentication
- OAuth 2.1 required
- Example scopes: `notes.read`, `notes.write`, `notes.admin`

이 정도만 읽어도 사용자는 감을 잡는다. "아, 이 서버는 개인 지식 관리용이고, 원격 접속형이며, OAuth가 필요하고, 읽기/쓰기 권한이 나뉘는구나." 여기까지 전달되면 절반은 성공이다.

그리고 README에는 도구 목록을 다 적는 것보다 도구를 어떻게 분류해 보여줄지가 더 중요하다. 예를 들어 PKM-MCP라면 읽기, 쓰기, 가져오기, 검색, UI 같은 관점으로 묶는 편이 이해가 빠르다. 같은 정보를 나열하더라도 사용자의 머릿속에서 구조가 생긴다.

Server Card는 이미 10장에서 구조를 살펴봤으니, 여기서는 한 가지만 강조하자. README는 사람용 설명서이고, Server Card는 기계용 입구 표지판이다. 둘이 서로 다른 말을 하면 신뢰가 깨진다. README에는 OAuth 필수라고 적혀 있는데 Server Card에는 인증 없음으로 되어 있으면, 사용자는 연결 실패보다 먼저 불신을 느낀다.

그래서 공개 직전에는 반드시 세 문서를 대조해야 한다.

• Registry의 이름, 버전, URL

• README의 이름, 버전, 접속 방법

• Server Card의 이름, 버전, 엔드포인트, 인증 정보

세 군데가 같은 이야기를 하면 서버가 정돈되어 보인다. 공개 프로젝트의 품질은 코드보다 정렬된 설명에서 먼저 드러날 때가 많다.

18.3 버전 관리와 호환성 정책

서버를 공개하는 순간, Tool 이름은 함수명이 아니라 외부 계약이 된다. search_notes는 이제 여러분 코드 안의 편한 이름이 아니라, 다른 사람의 프롬프트, 자동화 스크립트, 팀 워크플로우에 박히는 공개 인터페이스다.

이때부터 버전은 숫자가 아니라 약속이다.

PKM-MCP v1.0의 호환성 정책은 단순할수록 좋다. 괜히 멋있어 보이는 규칙을 만들기보다, 사용자가 실제로 기억할 수 있는 규칙을 제시해야 한다. 추천하는 정책은 다음과 같다.

이 표가 중요한 이유는 간단하다. 사용자는 새 버전을 봤을 때 "업데이트해도 괜찮은가?"를 즉시 판단하고 싶어 한다. 1.0.3이면 안심하고 올리고, 1.2.0이면 새 기능이 있겠거니 하고 읽어보고, 2.0.0이면 잠깐 멈춰서 마이그레이션 가이드를 찾는다.

PKM-MCP 같은 서버에서는 특히 다음 항목을 공개 계약으로 취급해야 한다.

• Tool 이름과 설명의 의미

• 입력 스키마에서의 필수 필드

• Resource URI 패턴

• Prompt 이름과 인자 의미

• OAuth 스코프 이름과 권한 범위

여기서 중요한 운영 감각이 하나 있다. 새 기능을 추가하는 것보다, 기존 의미를 바꾸지 않는 것이 더 어렵다.

예를 들어 search_notes의 기본 정렬 순서를 갑자기 최신순에서 관련도순으로 바꿔 버리면, 스키마는 그대로여도 실제 체감은 깨진다. create_note가 예전에는 빈 본문을 허용했는데 갑자기 필수 검증이 생겨 실패하기 시작해도 마찬가지다. 사용자는 "버그가 생겼다"고 느낀다. 공개 서버에서 호환성은 문법만이 아니라 행동의 일관성까지 포함한다.

그래서 PKM-MCP v1.0에는 다음 운영 원칙을 붙이는 편이 좋다.

• Tool 이름을 바꿔야 하면, 기존 이름을 한동안 별칭으로 유지한다.

• 필수 인자를 늘려야 하면, 먼저 선택 인자로 도입하고 다음 메이저에서 승격한다.

• 응답 형식을 손대야 하면, 새 Tool을 추가하고 이전 Tool은 폐기 예정으로 표시한다.

• README와 CHANGELOG에 "무엇이 바뀌었는지"보다 "누가 영향을 받는지"를 먼저 적는다.

이 네 가지만 지켜도 공개 서버의 인상이 달라진다. 사용자는 최신 기능보다도 "이 서버는 함부로 나를 깨뜨리지 않는다"는 감각을 더 오래 기억한다.

18.4 매니지드 플랫폼(Smithery, MintMCP 등) 비교

이제 많은 초보자가 헷갈리는 질문으로 가보자.

"공식 Registry에 올리면 끝인가요?"

아니다. Registry는 발견 가능성을 높여주지만, 호스팅이나 운영, 조직 정책, 클라이언트 온보딩까지 전부 대신해 주지는 않는다.¹³ MCP 생태계에는 층위가 다른 여러 플랫폼이 있다. 이걸 같은 종류의 서비스로 보면 판단이 꼬인다.

아래처럼 나누어 보면 훨씬 명확하다.

Cloudflare 쪽은 "내 서버를 어디서 실행할 것인가?"에 강하다. 원격 MCP 서버를 Streamable HTTP로 배포하고, 필요하면 인증과 권한 부여까지 엮기 좋다.⁴⁵ 반면 Smithery는 "사람들이 내 서버를 어떻게 찾고 써보게 할 것인가?"에 더 가깝다. 공식 문서에서도 Smithery를 MCP 서버를 찾고, 사용하고, 게시하는 장소로 소개한다.⁶

MintMCP 같은 엔터프라이즈 지향 플랫폼은 또 다른 문제를 푼다. 기업 환경에서는 서버 한두 개를 띄우는 것보다, 누가 어떤 서버에 어떤 권한으로 접근하는지, 로그와 정책을 어떻게 한곳에서 통제할지가 더 중요해진다. 이런 플랫폼은 중앙 인증, 역할 기반 접근 제어, 가상 MCP 서버 구성 같은 운영 레이어를 제공하는 쪽에 가깝다.⁷

중요한 것은 이 셋이 경쟁 관계만은 아니라는 점이다. 예를 들어 PKM-MCP는 이렇게 조합할 수 있다.

PKM-MCP는 Cloudflare Workers에서 실행되고, MCP Registry에 등록되며, Smithery에도 노출되고, 회사 내부 배포판은 MintMCP 같은 제어 레이어 뒤에서 쓰일 수 있다. 서로 대체재라기보다, 각각 다른 층에서 역할을 나눠 맡는다.

이 관점을 이해하면 "어디에 올려야 하지?"가 아니라 "어떤 문제를 누구에게 풀어주고 있지?"라는 질문으로 바뀐다. 그리고 그 질문이 맞아야 플랫폼 선택도 덜 흔들린다.

만들기: PKM-MCP v1.0을 레지스트리에 공개

이제 PKM-MCP v1.0을 실제로 공개해 보자. 목표는 단순하다. 누군가가 처음 발견했을 때 바로 이해하고, 연결하고, 믿고, 업데이트할 수 있게 만드는 것이다.

먼저 PKM-MCP의 기준 배포 형태를 하나로 정한다. 이번 책의 흐름이라면 원격 접속형 Cloudflare Workers 배포본을 기준으로 삼는 것이 자연스럽다. 엔드포인트는 https://mcp.example.com/mcp처럼 고정하고, README·Server Card·Registry 매니페스트 모두 이 URL을 가리키게 한다.

다음으로 저장소 루트에 .mcp/server.json을 준비한다.

{
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
  "name": "io.github.honggildong/pkm-mcp",
  "version": "1.0.0",
  "description": "Personal knowledge MCP server for note CRUD, RAG search, and note card UI.",
  "title": "PKM-MCP",
  "websiteUrl": "https://pkm.example.com",
  "repository": {
    "url": "https://github.com/honggildong/pkm-mcp",
    "source": "github"
  },
  "remotes": [
    {
      "type": "streamable-http",
      "url": "https://mcp.example.com/mcp"
    }
  ]
}

README의 첫 화면도 제품 소개형으로 다듬는다. 여기서는 구현 세부보다 사용 가치와 접속 방법이 앞에 와야 한다. 예를 들면 이런 순서가 좋다.

• 한 줄 설명

• 누구를 위한 서버인지

• 연결 URL과 인증 방식

• 핵심 Tool 묶음 소개

• 안전장치와 권한 모델

• 버전 정책과 CHANGELOG 링크

Server Card도 함께 점검한다. 이름, 버전, 엔드포인트, 인증 요구 사항이 README와 정확히 일치해야 한다. 여기서 한 글자라도 어긋나면 공개 품질이 툭 떨어진다.

그다음에는 공개 전 최종 테스트를 한다. Inspector에서 원격 URL로 붙어 initialize, tools/list, OAuth 로그인, search_notes, create_note, semantic_search_notes까지 한 번씩 돌려 본다. 특히 외부 사용자를 상정한다면, 여러분 계정이 아닌 새 사용자 계정으로 연결 테스트를 꼭 해봐야 한다. 운영자는 종종 자기 권한이 너무 넓어서 문제를 못 본다.

이상이 없으면 Registry에 발행한다.

mcp-publisher login github
mcp-publisher publish --dry-run .mcp/server.json
mcp-publisher publish .mcp/server.json

공개가 끝나면 거기서 끝내지 말고, 바로 다음 두 가지를 이어서 한다.

첫째, 릴리스 노트를 쓴다. 단순히 "v1.0 출시"가 아니라, 누가 지금 바로 무엇을 할 수 있는지를 써야 한다. 예를 들면 "OAuth 기반 사용자별 노트 격리 지원", "RAG 의미 검색 지원", "MCP Apps 노트 카드 UI 지원" 같은 문장이다.

둘째, 유통 채널을 넓힌다. Registry만으로도 충분할 수 있지만, Smithery 같은 마켓플레이스에 노출하면 사용자가 훨씬 쉽게 발견하고 시험해 볼 수 있다.⁶ 특히 초반에는 "좋은 서버"보다 "설치가 쉬운 서버"가 더 빨리 퍼진다.

마지막으로, 공개 후 운영 원칙을 저장소 맨 앞에 선언한다.

## Compatibility Policy
- Patch releases never break existing tool schemas.
- Minor releases only add backward-compatible capabilities.
- Breaking changes require a major version bump and a migration guide.
- Deprecated tools remain available for at least one minor release.

이 짧은 문단이 생각보다 큰 힘을 가진다. 서버를 처음 쓰는 사람에게 "이 프로젝트는 버전 숫자를 장식으로 쓰지 않는다"는 신호를 보내기 때문이다.

PKM-MCP v1.0의 공개는 여기서 끝난다. 하지만 진짜 의미는 이제부터 시작이다. 로컬에서 잘 돌아가는 서버를 만드는 일과, 낯선 사람이 안심하고 연결할 수 있는 서버를 만드는 일은 다른 기술이다. 이번 장에서 배운 것은 바로 그 두 번째 기술이다.

정리

이 장에서 기억할 핵심은 간단하다.

배포와 공개는 다르다. 공개에는 발견 가능성, 문서화, 호환성 약속이 필요하다.

공식 MCP Registry는 코드를 올리는 곳이 아니라, 서버의 존재와 접속 방법을 표준 메타데이터로 알리는 곳이다.¹³

README는 사람을 위한 설명서이고, Server Card는 기계를 위한 표지판이다. 둘은 같은 내용을 서로 다른 독자에게 전달해야 한다.

버전 정책은 숫자 놀이가 아니라 신뢰 계약이다. Tool 이름, 입력 스키마, Resource URI, 스코프 이름은 모두 공개 인터페이스로 다뤄야 한다.

Cloudflare Workers, Smithery, MintMCP 같은 플랫폼은 같은 종류의 서비스가 아니다. 실행, 유통, 거버넌스라는 서로 다른 층을 담당한다.⁴⁶⁷

그리고 무엇보다, 공개된 MCP 서버는 코드보다 약속으로 평가받는다.

PKM-MCP는 이제 내 장난감 서버가 아니다. 주소가 있고, 설명이 있고, 정책이 있고, 다른 사람이 실제로 쓸 수 있는 제품이 되었다. 다음 장에서는 여기서 한 걸음 더 나아가, 이 생태계 자체가 어디로 가고 있는지 살펴본다. MCP의 미래는 단순한 도구 호출을 넘어, 더 긴 작업, 더 많은 매체, 더 많은 에이전트의 협력으로 향하고 있다.

참고

¹Official MCP Registry Reference

²NuGet.org MCP 서버를 공식 MCP 레지스트리에 게시

³MCP Registry

⁴Build a Remote MCP server

⁵Build and deploy Remote Model Context Protocol (MCP) servers to Cloudflare

⁶Introduction - Smithery Documentation

⁷How to Connect Cloudflare Worker to MCP: Enterprise Guide