4부 16장. 작은 MCP 서버 6개를 90분 안에 만들기

PKM-MCP를 오래 붙들고 있으면 아주 좋은 일이 생긴다. 한 프로젝트를 깊게 파면서 인증, 검색, CRUD, 배포, 로그까지 한 흐름으로 이해하게 된다. 그런데 동시에 한 가지 부작용도 있다. 모든 문제가 PKM처럼 보여서, 새로운 MCP 서버를 만날 때도 괜히 크게 설계하고 싶어진다.

그래서 이번 장은 반대로 간다. 아주 작고 선명한 MCP 서버 여섯 개를 빠르게 만든다. GitHub PR 리뷰, Slack 메시지 발송, Figma 메타데이터 추출, Notion 동기화, SQL Agent, 그리고 한글 문서 자동화까지. 각각은 작지만, 설계 패턴은 아주 진하다.

핵심은 단순하다. 큰 프로젝트 하나를 깊게 만드는 경험과 작은 프로젝트 여러 개를 빨리 만드는 경험은 경쟁 관계가 아니라 협력 관계다. 전자는 체력을 만들고, 후자는 감각을 만든다. PKM-MCP가 마라톤이라면, 이 장의 여섯 서버는 인터벌 훈련이다.

왜 지금 작은 서버를 여섯 개나 만들까

좋은 MCP 서버는 대체로 두 가지 특징을 가진다. 첫째, 목적이 좁고 분명하다. 둘째, 사용자가 하려는 일을 기준으로 도구를 설계한다. 즉, 내부 API를 그대로 내보내는 서버보다 "이 작업을 끝내게 해주는 서버"가 훨씬 잘 작동한다.¹²

이 원칙은 PKM-MCP에도 그대로 적용된다. 우리가 만든 PKM-MCP가 잘 작동했던 이유도, 메모 저장소 전체를 마구 노출해서가 아니라 "메모를 찾는다", "메모를 정리한다", "메모를 요약한다" 같은 작업 단위로 잘라냈기 때문이다.

작은 서버를 여러 개 만들어 보면 이 감각이 훨씬 빨리 몸에 밴다. 무엇을 Tool로 만들지, 무엇을 Resource로 뺄지, 어떤 입력 검증이 필요한지, 어디서 read-only와 destructive를 나눠야 하는지가 반복적으로 눈에 들어온다.

90분 훈련법

이 장에서는 서버 하나당 15분을 쓴다고 가정하자. 완성품을 만드는 시간이 아니라, 문제 정의 → 최소 도구 설계 → 안전장치 추가 → 클라이언트에서 한 번 실행까지 해보는 시간이다.

1. 0~15분: GitHub PR 자동 리뷰 서버

2. 15~30분: Slack 메시지 발송 서버

3. 30~45분: Figma 디자인 메타데이터 추출 서버

4. 45~60분: Notion 동기화 서버

5. 60~75분: SQL Agent 서버

6. 75~90분: 한글 문서 자동화 서버

이 훈련의 규칙은 하나다. 도구 수를 줄이고, 설명은 또렷하게 쓴다. MCP 서버는 REST API 전시장이 아니다. LLM이 읽고 고르는 도구 상자다.²

여섯 서버에 공통으로 적용할 미니 설계 규칙

먼저, 여섯 예제 모두에 통하는 공통 규칙부터 잡아두자.

첫째, 서버 하나에는 역할 하나만 담는다. GitHub 서버는 코드 협업, Slack 서버는 메시지 전달, SQL 서버는 질의와 스키마 탐색처럼 중심 축이 명확해야 한다.¹

둘째, 도구 이름은 내부 시스템 용어보다 사용자 행동을 닮아야 한다. post_message_to_channel보다 send_release_update가 더 낫고, get_pull_request_files보다 review_pull_request_changes가 더 좋을 때가 많다. LLM은 이름과 설명을 읽고 판단하기 때문이다.²

셋째, read-only와 write 도구를 섞지 않는다. 권한 승인 경험이 단순해지고, 사용자가 위험도를 이해하기 쉬워진다.²

넷째, 기본 출력은 가볍게 유지한다. 긴 원문 전체를 반환하기보다 요약, 미리보기, 페이지네이션 힌트를 주는 편이 낫다. LLM의 컨텍스트 창은 넓어 보여도 금방 꽉 찬다.²

이 네 가지만 지켜도 작은 서버는 놀랄 만큼 잘 작동한다.

먼저 만들어 둘 공통 뼈대

여섯 서버 모두 완전히 다른 것처럼 보이지만, 실제로는 뼈대가 거의 같다. 인증 클라이언트 하나, 도구 몇 개, 입력 검증, 구조화된 에러, 그리고 짧고 정확한 docstring이면 된다.

예를 들어 Python으로는 이런 식의 뼈대를 재사용할 수 있다.

from fastmcp import FastMCP
from pydantic import BaseModel, Field

mcp = FastMCP("mini-server")

class ReviewInput(BaseModel):
    repo: str = Field(description="owner/repo 형식의 저장소")
    pr_number: int = Field(description="리뷰할 Pull Request 번호")

@mcp.tool()
async def review_pull_request_changes(repo: str, pr_number: int) -> str:
    """PR의 변경 사항을 읽고 핵심 위험 요약을 반환합니다.
    읽기 전용 도구입니다. 코드를 수정하거나 코멘트를 등록하지 않습니다.
    """
    ...

이런 뼈대를 복사해 두고, 도메인만 바꾸면 된다. 중요한 건 코드보다도 도구의 경계다.

16.1 GitHub PR 자동 리뷰 서버

이 서버의 목표는 명확하다. "코드를 읽고, 위험 신호를 짚어주기." 여기서 가장 흔한 실수는 GitHub REST API의 엔드포인트를 Tool로 하나씩 내보내는 것이다. get_pr, list_files, get_diff, create_review_comment처럼 잘게 쪼개면, LLM은 해야 할 일을 이해하는 대신 배관 공사를 시작한다.

우리가 원하는 것은 이런 사용자 요청을 잘 처리하는 서버다.

"이 PR에서 버그 날 가능성이 높은 부분을 찾아줘. 보안 문제도 같이 봐줘."

이럴 때 최소 도구는 세 개면 충분하다.

• review_pull_request_changes: PR 메타데이터와 diff를 읽고 위험 요약 생성

• list_review_findings: 파일별 이슈 후보를 짧게 정리

• submit_review_comment: 사용자가 승인했을 때만 실제 코멘트 등록

핵심은 첫 두 도구를 read-only로 두고, 마지막 하나만 쓰기 도구로 분리하는 것이다. 이렇게 하면 기본 사용 경험은 안전하고, 실제 코멘트 등록은 명시적 승인을 거치게 된다.

응답 포맷도 중요하다. diff를 통째로 다시 뿌리면 토큰만 낭비한다. 대신 파일별로 이렇게 잘라서 주면 된다.

## 요약
- 인증 로직 변경 있음
- null 처리 누락 가능성 있음
- 테스트 보강 필요

## 파일별 메모
- auth/service.ts: refresh token 만료 분기 확인 필요
- api/users.ts: 입력 검증 없음
- tests/auth.test.ts: 실패 케이스 없음

이 예제에서 배우는 패턴은 읽기 도구와 실행 도구의 분리다. PKM-MCP로 돌아가면 바로 떠오를 것이다. search_notes와 delete_note가 왜 같은 도구면 안 되는지, 몸으로 이해하게 된다.

16.2 Slack 메시지 발송 서버

Slack 서버는 겉보기에는 아주 쉽다. "메시지 하나 보내면 끝 아닌가요?" 그런데 바로 그 지점에서 설계 차이가 난다.

초보 버전은 대개 이렇게 만든다. list_channels, find_user, post_message, upload_file, create_thread_reply. 얼핏 좋아 보이지만, 실제 사용에서는 너무 잘게 나뉜다. 사용자는 "배포 완료 알림 보내기"를 원하지, "채널 찾고, 메시지 포맷 만들고, 스레드 연결하기"를 원하지 않는다.

그래서 MVP는 이렇게 잡는 편이 낫다.

• send_channel_message: 특정 채널에 일반 메시지 발송

• send_release_update: 버전, 변경점, 롤백 링크까지 포함한 배포 알림 발송

• send_incident_alert: 긴급도와 대응 링크가 포함된 장애 알림 발송

세 번째와 두 번째 도구는 사실 내부적으로는 send_channel_message를 감싼 워크플로 도구다. 하지만 LLM 입장에서는 훨씬 고르기 쉽다. 이것이 바로 "API 중심"이 아니라 "업무 중심" 설계다.²

Slack 서버에서 반드시 넣어야 할 안전장치는 두 가지다. 첫째, 허용된 채널 allowlist다. 둘째, 멘션 제한이다. @channel, @here, 대규모 사용자 그룹 멘션은 기본적으로 막아야 한다. 그렇지 않으면 AI가 지나치게 열정적인 사내 방송국이 된다.

이 서버에서 배우는 패턴은 실수의 비용이 큰 쓰기 도구는 더 높은 수준의 의도를 가진 이름으로 묶어야 한다는 점이다. post_message보다 send_incident_alert가 더 안전한 이유는, 입력 형식과 출력 기대가 좁기 때문이다.

16.3 Figma 디자인 메타데이터 추출 서버

Figma 예제는 아주 좋은 read-only 서버 훈련이다. 디자인 파일을 바꾸지 않고, 필요한 정보만 꺼내오는 서버이기 때문이다.

사용자 요청은 보통 이런 식이다.

"로그인 화면 디자인 구조를 설명해줘. 버튼 종류랑 텍스트 스타일도 같이 정리해줘."

이 요청을 위해 굳이 픽셀 단위 데이터를 다 넘길 필요는 없다. 오히려 그러면 LLM이 질식한다. Figma 서버의 MVP는 메타데이터 중심으로 잡아야 한다.

• get_file_outline: 페이지, 프레임, 주요 컴포넌트 트리 반환

• get_component_inventory: 버튼, 입력창, 카드 등 컴포넌트 목록 반환

• get_design_tokens: 컬러, 타이포그래피, 간격 토큰 반환

여기서 중요한 것은 "디자인 자체를 해석하려고 들지 않는 것"이다. 서버는 똑똑한 디자이너가 아니라, 정보를 잘 정리한 조수여야 한다. 즉, "이 화면은 신뢰감을 주는 디자인입니다" 같은 평가를 서버가 하지 말고, 색상, 계층 구조, 반복 패턴, 네이밍 같은 재료를 LLM에게 넘겨야 한다. 해석은 클라이언트의 몫이다.

이 예제에서 배우는 패턴은 스마트 분석기보다 스마트 데이터 공급자가 되라는 것이다. 이 원칙은 PKM-MCP의 Resource 설계와도 정확히 연결된다. 메모 검색 서버가 문서를 대신 해석하려고 들수록, 오히려 범용성이 떨어진다.

16.4 Notion 동기화 서버

Notion은 작은 MCP 서버 예제 중에서도 아주 실전적이다. 문서를 읽고, 페이지를 만들고, 데이터베이스를 갱신하는 일이 자주 일어나기 때문이다. 특히 최근 Notion MCP는 원격 MCP 서버와 OAuth 기반 연결을 제공하고, AI가 쓰기 좋은 형식과 토큰 사용량을 고려한 도구를 제공하는 방향으로 발전했다.³⁴

이 서버를 설계할 때 가장 먼저 결정할 것은 범위다. "Notion 전체"를 만들 생각을 하면 바로 늪에 빠진다. 대신 이번 장에서는 동기화라는 한 가지 목적만 잡자.

예를 들어 PKM-MCP와 연결된 Notion 동기화 서버는 이렇게 설계할 수 있다.

• sync_note_to_notion_page: PKM 노트 하나를 Notion 페이지로 반영

• import_notion_page_to_note: Notion 페이지를 PKM 노트로 가져오기

• sync_project_status: PKM 태그와 Notion 데이터베이스 상태를 맞추기

이 세 도구만으로도 생각보다 많은 일이 된다. 회의 메모를 PKM에 저장한 뒤 Notion 프로젝트 위키로 보내고, 반대로 Notion의 업무 상태를 PKM 일지에 반영하는 식이다.

이때 주의할 점은 "Notion의 객체 모델"을 Tool 이름에 드러내지 않는 것이다. 사용자는 페이지 parent나 data source abstraction을 알고 싶지 않다. 그런 복잡함은 서버 내부에서 처리하면 된다. 외부에 보이는 것은 "동기화한다"는 행동이어야 한다.

또 하나 배울 점은 인증 경험이다. 원격 MCP와 OAuth가 붙는 순간 사용성은 확 달라진다. 예전처럼 토큰을 복사해 설정 파일에 붙여넣는 방식은 빠르게 시작하기엔 좋지만, 팀 배포와 재인증, 권한 회수까지 생각하면 OAuth 흐름이 훨씬 낫다.³

이 예제에서 배우는 패턴은 외부 SaaS의 복잡한 모델을 사용자 행동 중심 도구로 감싸는 법이다. 9장에서 GitHub 이슈를 PKM 노트로 가져왔던 감각이 여기서 다시 살아난다.

16.5 SQL Agent 서버 — 자연어로 DB 질의

SQL Agent 서버는 늘 인기가 많다. 질문이 멋있기 때문이다. "지난달 매출이 떨어진 이유를 찾아줘." 하지만 구현은 생각보다 보수적으로 해야 한다. 데이터베이스는 말 그대로 회사의 장부이기 때문이다.

SQL MCP Server 계열 구현들은 대체로 스키마 탐색, RBAC, 텔레메트리 같은 운영 요소를 중요한 축으로 다룬다.⁵ 이 말은 곧, SQL 서버를 만들 때 가장 먼저 고민할 것이 "질의를 얼마나 똑똑하게 할까"가 아니라 "어디까지 허용할까"라는 뜻이기도 하다.

가장 안전한 MVP는 read-only다.

• list_tables: 테이블 목록과 간단한 설명

• describe_table: 컬럼, 타입, 기본 키, 예시 행 수

• run_select_query: SELECT만 허용하는 질의 실행

여기까지만 있어도 대부분의 분석 질문은 처리할 수 있다. 그리고 이 설계가 좋은 이유는 LLM이 먼저 스키마를 이해한 뒤 질의를 생성하게 만들 수 있기 때문이다. 즉, 곧바로 SQL을 때리는 대신, "지도 보고 길 찾기"를 먼저 시키는 셈이다.

쓰기 도구가 꼭 필요하다면 별도 서버로 분리하는 편이 낫다. 예를 들어 sql-read-mcp와 sql-write-mcp를 나누는 식이다. 같은 서버 안에 run_select_query와 drop_table이 함께 있는 순간, 사용자는 매번 심장이 쫄깃해진다.

응답 형식도 중요하다. SQL 결과를 거대한 JSON 배열로 던지지 말고, 표와 요약을 함께 주는 편이 좋다.

## 결과 요약
- 총 12행 반환
- 매출 하락은 동남권 지점에 집중
- 환불 비율은 전월 대비 18% 증가

## 미리보기
| region | revenue | refund_rate |
|---|---:|---:|
| southeast | 120000 | 0.14 |
| central | 210000 | 0.05 |

이 예제에서 배우는 패턴은 스키마 탐색 → 제한된 실행 → 요약된 반환이라는 순서다. 사실 PKM-MCP에서 RAG를 붙일 때도 비슷했다. 벡터 검색이든 SQL이든, LLM은 먼저 지형을 알아야 덜 헤맨다.

16.6 한글 문서(HWP) 자동화 서버 — 한국 특화의 힘

이 장의 마지막 예제는 아주 한국적이다. 한글 문서 자동화 서버는 "작지만 강한 니치 MCP"가 무엇인지 가장 잘 보여준다.

HWP-MCP 같은 구현은 Windows 환경과 한글 프로그램 설치를 전제로 하고, 새 문서 생성, 텍스트 입력, 표 생성, 저장, 배치 작업 같은 기능을 제공한다.⁶ 이 말을 듣는 순간 감이 올 것이다. 글로벌 범용성은 낮아 보여도, 특정 조직에서는 이 서버 하나가 엄청난 생산성을 만든다.

사용자 요청도 아주 현실적이다.

"지난주 영업 데이터를 바탕으로 월간 보고서 초안을 한글 파일로 만들어줘. 표도 넣고 제목 스타일도 맞춰줘."

이 서버의 MVP는 다음처럼 설계할 수 있다.

• create_report_document: 제목, 본문, 표 데이터로 보고서 초안 생성

• fill_hwp_table: 기존 문서의 표에 행 데이터 채우기

• save_hwp_document: 지정 경로로 저장

여기서 포인트는 Tool을 한글 프로그램의 메뉴 구조와 1:1로 맞추지 않는 것이다. click_insert_table_menu 같은 발상은 버려야 한다. 사용자가 원하는 것은 메뉴 조작이 아니라 문서 완성이다.

또 하나 배울 점은 배치 작업이다. HWP-MCP는 여러 작업을 한 번에 실행하는 형태도 지원한다.⁶ 이 아이디어는 MCP에서 특히 유용하다. 문서 생성은 대개 "문서 만들기 → 제목 넣기 → 표 넣기 → 저장하기"처럼 단계가 이어지기 때문이다. 이럴 때 개별 도구를 끝없이 호출하는 것보다, create_report_document처럼 워크플로 도구 하나로 묶는 편이 더 안정적이다.

물론 이 서버는 제약도 분명하다. 운영체제 제약이 있고, 로컬 애플리케이션 제어 특성상 원격 배포보다 데스크톱 자동화에 가깝다. 하지만 바로 그 점 때문에 배울 것이 있다. 모든 MCP 서버가 클라우드 SaaS를 향할 필요는 없다. 어떤 서버는 내 PC에서, 특정 업무 문맥 안에서 가장 큰 가치를 만든다.

이 예제에서 배우는 패턴은 지역 특화 도구일수록 추상화 수준을 더 높여야 한다는 점이다. 시스템 세부사항을 감추고, 사용자의 결과물을 중심으로 설계해야 한다.

여섯 예제에서 공통으로 보이는 설계 패턴

이제 여섯 서버를 한 번에 놓고 보면 반복되는 그림이 보인다.

이 표를 보고 있으면 묘하게 PKM-MCP가 떠오른다. 그렇다. 우리가 메인 프로젝트에서 배운 거의 모든 것이 여기에 다시 나온다.

PKM-MCP의 search_notes는 Figma와 SQL의 read-only 감각을 닮아 있고, semantic_search_notes는 응답 포맷을 가볍게 유지해야 하는 원칙과 연결된다. Notion 동기화는 외부 SaaS 감싸기 연습이고, 감사 로그는 Slack이나 HWP 같은 쓰기 도구에서 특히 중요하다. 결국 작은 서버는 메인 프로젝트의 축소판이 아니라, 메인 프로젝트를 더 잘 만들게 해주는 확대경이다.

작은 서버를 빨리 만들수록 큰 프로젝트를 더 잘 만든다

많은 사람이 이렇게 생각한다. "깊게 만들 시간이 없는데, 작은 장난감 서버를 여러 개 만들어서 무슨 도움이 될까?"

그런데 실제로는 반대다. 작은 서버를 빨리 만들어 본 사람일수록, 큰 프로젝트에서 욕심을 줄일 줄 안다. 서버 경계를 더 선명하게 긋고, Tool 이름을 더 조심해서 짓고, 응답 크기를 더 일찍 걱정하고, 권한 분리를 더 자연스럽게 해낸다.

한마디로, 작은 서버는 설계 감각의 헬스장이다.

PKM-MCP를 v1.0까지 끌고 가려면 앞으로도 할 일이 많다. 자체 UI도 붙여야 하고, 레지스트리 등록도 해야 하고, 다른 사용자에게 배포도 해야 한다. 그럴수록 중요한 것은 "한 번에 거대한 걸 완성하겠다"는 태도보다, 작은 문제를 독립적인 MCP 서버로 잘라서 풀 수 있는 감각이다.

이번 장의 여섯 예제는 바로 그 감각을 위한 압축 훈련이다. 오늘은 90분에 여섯 개를 스쳐 지나갔지만, 여기서 얻은 패턴은 이후 열여섯 시간, 아니 열여섯 주짜리 프로젝트에서도 계속 살아남는다.

다음 장에서는 이 감각을 한 단계 더 밀어붙인다. 이제 도구 호출만으로 끝내지 않고, 챗봇 안에 직접 보이는 화면을 심는다. MCP Apps는 서버가 단순한 "보이지 않는 백엔드"를 넘어, 상호작용하는 제품 일부가 되는 순간이다.

참고

¹MCP Best Practices: Architecture & Implementation Guide

²Block's Playbook for Designing MCP Servers

³Notion MCP overview

⁴Notion MCP Server repository

⁵SQL MCP Server documentation

⁶HWP-MCP repository