9개의 SaaS API를 위한 MCP 서버를 구축하며 배운 패턴

저는 지난 몇 주 동안 CoinGecko, Stripe, Jira, PostHog, Plausible, Etherscan, DeFiLlama, Jobber, 그리고 Resend와 같은 다양한 API를 위한 MCP (Model Context Protocol) 서버를 구축하는 데 시간을 보냈습니다. 9개의 서버, 68개의 도구(tools)를 만들었으며, 모두 npm에 게시되고 Glama에 인덱싱되었습니다.

그 과정에서 동일한 아키텍처가 계속해서 유효하다는 것을 발견했습니다. 만약 여러분이 자신의 API를 위한 MCP 서버를 구축하고 있거나, 이를 수행할 사람을 고용할 계획이라면, 여기 그 패턴이 있습니다.

3계층 아키텍처 (The Three-Layer Architecture)

제가 구축하는 모든 MCP 서버는 세 가지 계층을 가집니다:

1. 도구 정의 (Tool Definitions - 계약)

각 API 엔드포인트(endpoint)는 타입이 지정된 입력 스키마(input schema)를 가진 MCP 도구가 됩니다. 저는 검증(validation)을 위해 Zod를 사용하는데, 이는 잘못된 입력이 API에 도달하기 전에 잡아냅니다.

{
  name: "send_email",
  description: "Send a single email via Resend",
...

설명(description)은 생각보다 훨씬 중요합니다. LLM (Large Language Models)은 어떤 도구를 호출할지 결정하기 위해 이 설명을 읽습니다. "send email"과 같이 모호한 설명은 토큰(tokens)을 낭비합니다. "Resend API를 통해 단일 트랜잭션 이메일을 보냅니다. HTML 및 일반 텍스트를 지원합니다. 메시지 ID와 전송 상태를 반환합니다."와 같이 구체적인 설명이 올바르게 사용됩니다.

2. API 클라이언트 (API Client - 배관 작업)

이 계층은 인증(auth), 속도 제한(rate limiting), 그리고 에러 변환(error transformation)을 처리합니다. 핵심 통찰은 다음과 같습니다: HTTP 에러를 LLM에 그대로 노출하지 마세요. 에러를 구조화되고 실행 가능한 메시지로 변환하십시오.

// 나쁜 예: "Error: 429"
// 좋은 예: "Resend API에 의해 속도 제한이 적용되었습니다. 30초 후에 다시 시도하세요. 지난 한 시간 동안 100개의 이메일을 보냈습니다."

3. 출력 포맷터 (Output Formatter - 프레젠테이션)

가공되지 않은 JSON 덤프(raw JSON dumps)는 LLM이 소비하기에 매우 좋지 않습니다. 응답을 마크다운(markdown) 표, 글머리 기호 또는 구조화된 텍스트로 포맷팅하십시오. LLM은 다음에 무엇을 할지 결정하기 위해 이 출력을 읽으므로, 훑어보기 쉽게(scannable) 만드십시오.

## Email Sent Successfully
- **Message ID:** abc123
- **From:** alerts@yourcompany.com
...

계속해서 유효한 패턴들

모의 모드 (Mock Mode)

모든 서버에는 현실적인 가짜 데이터를 반환하는 모의 모드 (Mock Mode)가 포함되어 있습니다. 이를 통해 개발자는 실제 API 인증 정보 없이도 테스트를 진행할 수 있습니다. 저 또한 개발 과정에서 이 방식을 사용하여 API 키 없이 테스트를 수행합니다.

점진적 공개 (Progressive Disclosure)

LLM이 단 3개의 도구만 필요하다면, 18개의 도구를 한꺼번에 쏟아붓지 마세요. 사용 사례(Use case)별로 도구를 그룹화하십시오. Resend 서버에는 이메일, 연락처, 도메인, API 키를 위한 도구들이 있습니다. 이메일을 보내려는 개발자에게 도메인 관리 도구까지 보여줄 필요는 없습니다.

오류 복구 (Error Recovery)

API는 실패할 수 있습니다. 네트워크는 타임아웃(Timeout)이 발생할 수 있고, 속도 제한 (Rate limits)에 걸릴 수도 있습니다. 서버는 내부적으로 재시도 (Retries)를 처리해야 하며, LLM에게 가공되지 않은 스택 트레이스 (Stack traces)를 보여주는 대신 명확한 "다시 시도하십시오"라는 지침을 전달해야 합니다.

제공 사항

누군가 저에게 MCP 서버 제작을 의뢰하면, 다음 항목들을 받게 됩니다:

• 전체 도구 정의가 포함된 TypeScript MCP 서버
• Zod 스키마를 통한 입력 유효성 검사 (Input validation)
• 구조화된 메시지를 포함한 오류 처리 (Error handling)
• LLM 소비에 최적화된 깔끔한 마크다운 출력 (Clean markdown output)
• 인증 정보 없이 테스트 가능한 모의 모드 (Mock mode)
• 해당 조직의 범위 내에서의 npm 배포 (예: `@yourcompany/mcp-server")
• 발견 가능성을 높이기 위한 Glama/디렉토리 리스팅
• 설치 지침 및 도구 카탈로그가 포함된 README

일반적인 REST API의 경우 작업 완료까지 보통 1~3일이 소요됩니다.

이것이 중요한 이유

MCP는 AI 어시스턴트가 외부 서비스에 연결하는 표준 방식으로 자리 잡고 있습니다. Claude Desktop, Cursor, Windsurf 및 기타 클라이언트들이 모두 이를 지원합니다. 하지만 대부분의 SaaS API는 아직 MCP 서버를 갖추고 있지 않습니다. 그 격차는 다음과 같은 의미를 갖습니다:

1. 개발자의 시간 낭비: AI 어시스턴트와 API 대시보드 사이를 번갈아 가며 전환해야 합니다.
2. API의 배포 기회 상실: MCP 디렉토리에 등록되는 것은 앱 스토어에 입점하는 것과 같습니다.
3. 선점 효과: 특정 API에 대한 MCP 서버가 한 번 구축되면, 두 번째 서버를 만들 이유는 거의 없습니다.

연락처

귀하의 API에 MCP 서버가 필요하다면, 제가 구축해 드릴 수 있습니다. 저의 포트폴리오에는 암호화폐 (CoinGecko, Etherscan, DeFiLlama), 분석 (PostHog, Plausible), 프로젝트 관리 (Jira, Jobber), 결제 (Stripe), 그리고 이메일 (Resend)을 위한 서버들이 포함되어 있습니다.

GitHub: github.com/friendlygeorge

연결이 필요한 API가 무엇인지 말씀해 주세요. 범위를 산정하여 24시간 이내에 타임라인을 제공해 드리겠습니다.

이 포스트는 AI 도구 출시를 위한 저의 build-in-public 시리즈의 일부입니다. 이전 포스트에서는 일주일 만에 10개의 MCP 서버 구축하기와 실제로 사용되는 MCP 서버를 구축하는 방법을 다루었습니다.