2주 만에 SaaS를 위한 공식 MCP 서버 구축하기

원문은 fadymondy.com에 게재되었습니다.

고객들이 영업 통화나 지원 티켓에서 "Claude와 작동하나요?"라는 새로운 질문을 하기 시작했습니다. 때로는 ChatGPT나 Cursor일 수도 있지만, 요청 자체는 같습니다. 그들은 데이터를 탭 간에 복사할 필요 없이 AI 비서가 제품 내부에서 실제 작업을 수행하기를 원합니다.

이를 구현하는 표준적인 방법은 **MCP 서버(MCP server)**입니다. Model Context Protocol은 AI 비서들이 다른 제품의 도구를 발견하고 호출하는 데 사용하는 공개 프로토콜입니다. 이미 괜찮은 API가 있다면, 공식 MCP 서버는 작고 경계가 명확한 프로젝트입니다. 여기서는 제가 약 2주 만에 이를 기획하고 구현할 계획과, 누군가 코드를 작성하기 전에 결정해야 할 사항들을 설명합니다.

SaaS 팀을 위한 MCP 서버의 실제 정의

MCP 서버는 제품 옆에 위치하여 기존 API와 통신하는 얇은 계층(thin layer)입니다. 이 서버는 이름, 일반 언어 설명, 그리고 타입이 지정된 입력 스키마를 가진 짧은 목록의 _도구(tools)_들을 노출합니다. 비서가 이러한 설명을 읽고 사용자 요청에 맞는 도구를 결정한 다음 호출하는 것입니다.

여기서 세 가지 사항을 유추할 수 있습니다:

• 백엔드는 변경되지 않습니다. 이 서버는 웹 앱이 API의 클라이언트인 것처럼, API의 클라이언트입니다.
• 언어는 중요하지 않습니다. 저는 보통 TypeScript나 Go로 구축하며, Laravel 제품의 경우 PHP를 사용합니다. 팀이 유지보수할 수 있는 어떤 언어든 상관없습니다.
• 코드 양보다 도구 설계가 더 중요합니다. 대부분의 작업은 비서가 무엇을 할 수 있어야 하는지 결정하고, 모델이 올바른 도구를 선택하도록 이를 설명하는 것입니다.

이를 실행하는 일반적인 방법은 두 가지가 있습니다: 원격(remote) (클라우드 고객이 OAuth를 통해 연결하는 호스팅된 HTTP 엔드포인트)과 로컬(local) (사용자가 자신의 기기에서 실행하는 패키지이며, 자체 호스팅 설치에 적합합니다). 많은 SaaS 제품은 원격 방식부터 시작합니다.

"공식적"이라는 것이 중요한 이유

만약 당신이 직접 출시하지 않는다면, 다른 누군가가 할 것입니다. 인기 제품을 위한 커뮤니티 MCP 서버가 빠르게 등장하며, 보통 사용자들에게 전체 접근 권한(full-access) API 키를 설정 파일에 붙여넣도록 요청합니다. 그러면 고객들은 검증되지 않은 코드(unvetted code)를 프로덕션 자격 증명(production credentials)과 함께 실행하게 되고, 당신은 지원 티켓만 받게 됩니다.

공식 서버는 세 가지를 제어할 수 있게 합니다: 어떤 동작(actions)이 노출되는지, 인증 방식(authentication)은 어떻게 작동하는지, 그리고 당신의 제품이 어시스턴트에게 어떻게 설명되는지입니다.

2주 계획

API가 존재하고 문서화되어 있다면, 2주는 현실적인 시간이며 첫 번째 버전은 사람들이 실제로 요청하는 10~20개 동작에 초점을 맞춥니다. 제가 사용하는 순서는 다음과 같습니다.

단계 0: 한 페이지 분량의 도구 명세서(tool spec) (어떤 약속도 하기 전)

빌드하기 전에, 저는 API 문서를 읽고 한 페이지짜리 명세서를 작성합니다. 이 명세서에는 제안된 도구들, 각 도구가 무엇을 하는지, 입력값(inputs), 읽기만 하는지 쓰기(writes)를 하는지 여부, 그리고 어떤 인증 범위(auth scope)가 필요한지가 나열됩니다. 이는 양측 모두에게 프로젝트가 말이 되는지 확인할 수 있는 가장 저렴한 방법입니다.

좋은 명세서는 다음 질문에 답합니다:

• 사용자가 첫날 어시스턴트에게 요청할 다섯 가지 것은 무엇인가?
• 그중 어떤 것이 읽기 전용이고 어떤 것이 데이터를 변경하는가?
• 어떤 동작이 파괴적이거나 비용이 많이 들어 명확한 경고가 필요한가?
• 어시스턴트가 무언가를 찾는 데(검색, 필터, ID) 무엇이 필요한가?

1~3일차: 도구 설계 및 스캐폴딩

명세서를 도구 정의로 바꿉니다. 목록은 짧게 유지하고 이름은 명확하게 합니다. 모든 엔드포인트(endpoint)를 그대로 복제하지 마십시오. 어시스턴트는 한 필드만 다른 40개의 CRUD 엔드포인트보다 find_customer와 create_invoice를 사용하는 것이 더 좋습니다.

설명은 모델에게 지침처럼 작성합니다: 언제 도구를 사용할지, 무엇을 반환하는지, 그리고 무엇에 사용해서는 안 되는지를 명시합니다. 제 경험상 이 부분이 서버 성능을 가장 많이 변화시키는 작업입니다.

제가 운영하는 서버에서는 도구들이 **레지스트리(registry)**에 존재합니다: 프로토콜 계층이 읽는 하나의 목록이죠. 나중에 도구를 추가한다는 것은 트랜스포트나 인증 구조를 건드리는 것이 아니라, 단순히 항목을 하나 추가하는 것을 의미합니다. 이는 인계 후에도 서버가 쉽게 확장될 수 있도록 합니다.

4일차–7일차: 인증 및 권한 관리

이 단계에서 공식 서버가 그 이름을 얻게 됩니다.

• 원격 서버를 위한 OAuth. MCP 인증 사양은 OAuth 2.1을 기반으로 합니다. Zekra의 원격 MCP 엔드포인트에 전체 흐름(PKCE (S256), 동적 클라이언트 등록 및 개별 브레인 동의)을 구현했으며, 호출마다 현재 멤버십과 비교하여 접근 권한을 재확인합니다.
• 폴백(fallback)으로서 범위 지정된 API 키. Moharrik에서는 기본적으로 키가 읽기 전용이며 90일 후에 만료됩니다.
• 읽기와 쓰기 분리. 읽기 전용 도구는 읽기 전용으로 표시합니다 (MCP 도구 주석은 readOnlyHint와 destructiveHint를 지원). Zekra에서는 읽기 전용 주석을 추가하여 AI 코딩 에이전트 및 기타 MCP 클라이언트가 승인 프롬프트 없이 리콜(recall) 및 목록화 도구를 실행할 수 있게 했으며, 쓰기는 여전히 요청합니다.
• 에이전트 행동 추적 가능하게 만들기. 어시스턴트가 데이터를 작성할 때 그것이 에이전트에 의한 것임을 기록합니다. 제 이슈 트래커에서는 MCP를 통해 생성된 댓글을 author_kind = 'agent'로 저장하여 사람이 항상 이를 구별할 수 있도록 합니다.

8일차–10일차: 실제 어시스턴트를 대상으로 테스트하기

단위 테스트만으로는 충분하지 않습니다. 서버를 Claude, ChatGPT 및 Cursor에 연결하고 사양에서 제시된 프롬프트를 실행합니다. 다음 사항을 관찰하세요:

• 어시스턴트가 잘못된 도구를 선택하는 경우 (모델이 아닌 설명을 수정해야 합니다).
• 도구가 너무 많은 데이터를 반환하는 경우 (페이지네이션 및 자르기; 컨텍스트는 공짜가 아닙니다).
• 모호한 오류 (어시스턴트가 조치할 수 있는 메시지(예: "고객을 찾을 수 없습니다. search_customers를 시도해 보세요")를 반환합니다.).

11일차–14일차: 문서화, 목록 등록 및 인계

• 각 어시스턴트를 위한 설정 가이드: 각 페이지에 정확한 구성 정보와 함께 작성합니다.
• 권한 설명 페이지: 각 범위가 무엇을 허용하는지 일반 언어로 설명합니다. Moharrik에서는 이 설명을 도구 레지스트리에서 생성하므로 코드와 일치할 수 있습니다.
• 주요 MCP 디렉토리 목록 등록: 사용자가 공식 서버를 찾을 수 있도록 합니다.
• 인계(Handover): 저장소, 배포 노트 및 간단한 워크스루. 코드는 귀하의 이름과 라이선스로 제공됩니다.

2주를 넘어서는 경우

처음부터 범위를 솔직하게 파악해야 합니다. 보통 다음 항목들이 시간을 지연시킵니다:

• 아직 공개 API가 없거나, 사용자가 요청하는 기능을 수행할 수 없는 API;
• API에 모델링되지 않은 복잡한 다중 테넌트(multi-tenant) 권한;
• 진행 상황 보고나 웹훅(webhook)이 필요한 장시간 실행 작업(long-running jobs);
• 첫 번째 릴리스에서 자체 호스팅 패키지와 원격 엔드포인트 둘 다 필요함.

이 중 어느 것도 프로젝트를 막는 것은 아닙니다. 이들은 계획과 가격을 고정하기 위해 명세서(spec)에 포함되어야 합니다.

시작 전 체크리스트

• API가 문서화되었고 구축할 만큼 안정적입니다.
• 어시스턴트가 처리해야 할 상위 5가지 사용자 요청을 목록화했습니다.
• 어떤 작업은 반드시 확인(confirmation) 없이는 실행되어서는 안 되는지 알고 있습니다.
• 원격, 로컬 또는 둘 다 결정했습니다.
• 팀원 중 누군가가 인계 후 서버를 소유할 것입니다.

약속이 아닌 증명

저는 제 자신의 제품을 위해 MCP 서버를 구축했고, 이들은 프로덕션 환경에서 실행되고 있습니다:

• Orchestra MCP: 플러그인 호스트 아키텍처를 갖춘 AI 에이전트(AI-agentic) IDE 프레임워크.
• Zekra: OAuth 2.1을 통해 원격 MCP 엔드포인트에서 제공되는 AI 에이전트를 위한 공유 메모리.
• Moharrik: MCP를 통해 완벽하게 작동하는 받은 편지함 및 WhatsApp 기능을 갖춘 CRM.
• Nasaq UI: 자체 MCP 서버를 가진 오픈 소스 디자인 시스템.

귀하의 제품에도 같은 것을 원한다면, MCP 서버 개발(MCP server development)을 확인하세요. 이 과정은 무료의 1페이지 도구 명세서로 시작됩니다.