“Claude Code에 MCP 서버 만들어줘”라고 해봤다면 공감하실 겁니다. 파일이 몇 개 생기고 코드가 나오는데, 막상 연결해보면 오류가 나거나, 도구 설명이 너무 짧아 에이전트가 제대로 활용하지 못하는 경우가 많습니다. MCP 서버는 단순히 코드를 작성하는 게 아닙니다. 프로토콜을 이해하고, 도구 설계를 제대로 해야 LLM이 잘 사용할 수 있습니다.

mcp-builder 스킬은 이 과정 전체를 4단계 체크리스트로 에이전트에 심어줍니다. 어떤 API를 MCP로 감쌀지 연구하는 단계부터, TypeScript·Python 구현 패턴, MCP Inspector로 테스트, 마지막으로 에이전트가 실제로 잘 쓸 수 있는지 검증하는 평가 단계까지 — Anthropic이 자체 개발 경험을 바탕으로 정리한 가이드가 통째로 적용됩니다.

이번 시리즈 여섯 번째 편으로 Anthropic 공식 anthropics/skills 레포에서 MCP 개발에 특화된 스킬을 소개합니다.

mcp-builder란?

mcp-builder는 Anthropic이 공식 배포한 MCP 서버 개발 가이드 스킬입니다. skills.sh 마켓플레이스 기준 주간 37,100회 설치로, Anthropic의 anthropics/skills 레포지토리(GitHub ⭐ 115.8K)에서 관리됩니다.

MCP(Model Context Protocol)는 AI 에이전트가 외부 서비스·데이터베이스·API와 표준화된 방식으로 연결하는 프로토콜입니다. 쉽게 말하면 “AI가 외부 도구를 플러그인처럼 꽂아 쓸 수 있는 표준 인터페이스”입니다. Claude, Cursor, Gemini 같은 에이전트가 GitHub, Slack, Notion 같은 서비스와 연결될 수 있는 이유도 MCP 덕분입니다.

mcp-builder 스킬이 해결하는 핵심 문제는 다음과 같습니다. MCP 서버를 그냥 만드는 것과, LLM이 실제로 잘 활용할 수 있는 MCP 서버를 만드는 것은 다르다. 도구 이름·설명·에러 메시지 하나하나가 에이전트의 활용도를 크게 좌우합니다.

스킬이 해결하는 문제

설치 방법

# Claude Code에 설치 (프로젝트 전용)
npx skills add https://github.com/anthropics/skills --skill mcp-builder -a claude-code

# 전역 설치 (모든 프로젝트에서 사용)
npx skills add https://github.com/anthropics/skills --skill mcp-builder -g -a claude-code

다른 에이전트를 쓰신다면:

# Cursor에 설치
npx skills add https://github.com/anthropics/skills --skill mcp-builder -a cursor

# Codex에 설치
npx skills add https://github.com/anthropics/skills --skill mcp-builder -a codex

# Gemini CLI에 설치
npx skills add https://github.com/anthropics/skills --skill mcp-builder -a antigravity

-g 플래그를 붙이면 한 번 설치로 모든 프로젝트에서 사용할 수 있습니다. MCP 서버를 여러 프로젝트에 걸쳐 개발하신다면 전역 설치를 권장합니다.

실전 데모: Notion API MCP 서버 만들기

설치 후 Claude Code에서 이렇게 요청할 수 있습니다.

# MCP 서버 개발 시작
/mcp-builder Notion API를 MCP 서버로 만들어줘. 페이지 조회·생성·업데이트와 데이터베이스 쿼리를 지원해야 해.

스킬이 적용된 에이전트는 바로 코드를 작성하는 대신 4단계 절차를 따릅니다.

[Phase 1: Deep Research and Planning]

1. MCP 프로토콜 스펙 확인 중...
   → https://modelcontextprotocol.io/specification/draft.md 로드

2. Notion API 문서 분석 중...
   → 주요 엔드포인트: pages, databases, blocks, search
   → 인증: Bearer token (Notion-Version 헤더 필요)

3. 도구 설계 계획:
   notion_get_page         - 단일 페이지 조회
   notion_create_page      - 새 페이지 생성
   notion_update_page      - 페이지 속성 업데이트
   notion_query_database   - 데이터베이스 필터·정렬 조회
   notion_search           - 전체 워크스페이스 검색

[Phase 2: Implementation]
→ TypeScript + Zod 스키마로 구현 시작...

단순히 코드를 만들어주는 것이 아니라, 먼저 설계 계획을 잡고 검토할 수 있도록 단계를 나눠줍니다.

생성된 코드 품질 차이

스킬 없이 만든 MCP 서버와 비교해보면 도구 설계 부분이 확연히 다릅니다.

// ❌ 스킬 없이 생성된 코드
server.registerTool("get_page", {
  description: "Get a page",
  inputSchema: { page_id: z.string() }
}, async ({ page_id }) => {
  const data = await notion.pages.retrieve({ page_id });
  return { content: [{ type: "text", text: JSON.stringify(data) }] };
});

// ✅ mcp-builder 스킬 적용 후 생성된 코드
server.registerTool("notion_get_page", {
  description: "Retrieve a Notion page by ID. Returns page properties, metadata, and content blocks. Use notion_query_database to find page IDs first.",
  inputSchema: {
    page_id: z.string().describe("Notion page ID (UUID format, e.g. '12345678-...')"),
  },
  annotations: { readOnlyHint: true, idempotentHint: true }
}, async ({ page_id }) => {
  try {
    const page = await notion.pages.retrieve({ page_id });
    return {
      content: [{ type: "text", text: JSON.stringify(page, null, 2) }],
      structuredContent: page
    };
  } catch (error) {
    if (error.code === 'object_not_found') {
      throw new Error(`Page '${page_id}' not found. Use notion_search to find the correct page ID.`);
    }
    throw error;
  }
});

4단계 워크플로우 상세 설명

mcp-builder 스킬의 핵심은 개발 과정을 4단계로 구조화한다는 점입니다.

Phase 1: 리서치 및 기획

스킬은 코드 작성 전에 먼저 두 가지를 확인하도록 안내합니다.

도구 이름을 잘 짓는 것이 생각보다 중요합니다. get_data 같은 이름은 에이전트가 “이 도구가 어디서 무엇을 가져오는지” 바로 파악하지 못합니다. github_list_repos처럼 서비스명 + 동작 형식이면 에이전트가 필요한 순간 스스로 올바른 도구를 선택할 수 있습니다.

Phase 2: 구현

TypeScript를 권장하는 이유가 스킬 내부에 명시되어 있습니다. SDK 지원이 좋고, Zod로 입력 스키마를 검증할 수 있으며, AI 모델이 TypeScript 코드를 잘 생성하기 때문입니다.

// Zod 스키마로 입력 검증
const QueryDatabaseSchema = z.object({
  database_id: z.string().describe("Notion database ID"),
  filter: z.object({...}).optional().describe("Filter conditions"),
  sorts: z.array(z.object({...})).optional().describe("Sort options"),
  page_size: z.number().min(1).max(100).default(10)
    .describe("Number of results per page (max 100)")
});

스킬은 페이지네이션, 에러 처리, 응답 포맷(JSON vs 마크다운)에 대한 기준도 함께 주입합니다. 특히 에러 메시지에는 반드시 원인 + 다음 조치를 포함하도록 안내합니다.

Phase 3: 테스트

구현이 끝나면 MCP Inspector로 로컬 테스트를 진행합니다.

# TypeScript 빌드 후 Inspector 실행
npm run build
npx @modelcontextprotocol/inspector

# Python이라면
python -m py_compile your_server.py
npx @modelcontextprotocol/inspector

Inspector는 MCP 서버에 연결해 도구 목록을 확인하고, 각 도구를 직접 호출해볼 수 있는 브라우저 UI를 제공합니다. 코드가 컴파일만 되면 끝이 아니라, 실제로 MCP 프로토콜을 통해 도구가 잘 노출되는지를 확인하는 단계입니다.

Phase 4: 평가 (Evaluation)

마지막 단계가 이 스킬에서 가장 독특한 부분입니다. MCP 서버가 완성됐다고 바로 배포하지 않고, LLM이 실제로 이 서버를 활용해 현실적인 질문에 답할 수 있는지 검증합니다.

<!-- 평가 파일 예시 (XML 형식) -->
<evaluation>
  <qa_pair>
    <question>notion_query_database를 사용해 'Projects' 데이터베이스에서
    Status가 'In Progress'인 항목이 몇 개인지 확인해주세요.</question>
    <answer>7</answer>
  </qa_pair>
  <!-- 10개 qa_pair 필요 -->
</evaluation>

내부 동작 원리

이 스킬이 에이전트에 주입하는 내용은 크게 세 가지입니다.

첫째, 4단계 절차 가이드입니다. 에이전트가 요청을 받으면 바로 코드를 작성하지 않고 리서치 → 기획 → 구현 → 평가 순으로 작업합니다.

둘째, MCP 모범 사례 규칙입니다. 도구 이름 규칙, 응답 형식, 페이지네이션, 보안, 에러 처리 기준이 포함됩니다. 스킬은 필요할 때 GitHub에서 MCP Best Practices 문서를 직접 가져와 참조합니다.

셋째, 언어별 구현 패턴입니다. TypeScript(Zod + server.registerTool)와 Python(Pydantic + @mcp.tool) 각각의 완전한 예제 코드 패턴이 포함되어 있습니다.

허용된 도구

이 스킬은 WebFetch(MCP 스펙·SDK 문서 로드)와 Read(로컬 파일 읽기), Write/Bash(코드 생성 및 빌드)를 사용합니다. 코드 생성·빌드·테스트까지 한 흐름으로 처리합니다.

이럴 때 쓰세요 / 이럴 때는 안 맞아요

잘 맞는 상황	덜 맞는 상황
외부 API를 처음 MCP 서버로 만들 때	이미 완성된 MCP 서버를 단순히 디버깅할 때
도구 이름·설명이 엉성해 에이전트가 잘 못 쓸 때	MCP 개념 자체가 처음인 완전 초보 단계
TypeScript·Python MCP 프로젝트 초기 설정	Claude Code MCP 연결 설정만 도움받고 싶을 때
개발한 MCP 서버를 LLM이 잘 쓰는지 검증할 때	단순 CLI 도구나 REST API 래퍼 개발

Anthropic의 다른 스킬들

anthropics/skills 레포에는 이 스킬 외에도 이 시리즈에서 다룬 스킬이 있습니다.

# 레포에 있는 스킬 목록 확인
npx skills add https://github.com/anthropics/skills --list

이 시리즈에서 이미 다룬 것들:

• frontend-design — AI 냄새 없는 UI를 위한 디자인 감각 주입 스킬 → 4편 보러 가기

같은 레포의 다른 스킬:

• brainstorming — 기능 개발 전 요구사항·설계를 먼저 탐색하는 스킬
• systematic-debugging — 버그를 체계적으로 추적·격리·수정하는 디버깅 스킬
• test-driven-development — 구현 전 테스트를 먼저 작성하는 TDD 가이드 스킬

자주 묻는 질문 (FAQ)

Q1: mcp-builder 스킬은 유료인가요?

npx skills add로 설치되는 스킬 자체는 무료 오픈소스입니다. MIT 라이선스로 공개된 anthropics/skills 레포지토리의 텍스트 파일을 에이전트에 로드하는 방식이라 별도 비용이 없습니다. 스킬이 내부적으로 MCP 스펙 문서를 WebFetch로 가져올 때도 모두 무료 공개 URL입니다.

Q2: MCP를 처음 접하는데 이 스킬이 도움이 될까요?

MCP 개념을 아예 모른다면 이 스킬만으로 처음부터 배우기는 어렵습니다. MCP가 무엇인지 기본 개념을 먼저 파악한 뒤, 실제 서버를 만드는 단계에서 이 스킬을 적용하는 것을 권장합니다. Anthropic MCP 공식 문서에서 15분 정도 개요를 읽으면 충분합니다.

Q3: TypeScript를 모르면 Python으로도 쓸 수 있나요?

네. 스킬은 TypeScript와 Python 두 언어를 모두 지원합니다. 요청할 때 “Python으로 구현해줘”라고 명시하면 Pydantic + FastMCP 패턴으로 가이드합니다. 다만 Anthropic이 TypeScript를 공식 권장하는 이유는 SDK 안정성과 타입 지원이 더 좋기 때문입니다.

Q4: Claude Code 외에도 쓸 수 있나요?

네. Cursor, Codex, Gemini CLI, GitHub Copilot, amp, opencode 등 주요 에이전트 전체를 지원합니다. 특히 opencode(30.3K), gemini-cli(29.5K), codex(29.4K) 등 여러 에이전트에서 주간 수만 건씩 설치되고 있습니다.

Q5: 완성된 MCP 서버를 Claude에 연결하는 방법도 알려주나요?

이 스킬은 MCP 서버 개발 자체에 집중합니다. 완성된 서버를 Claude Desktop이나 Claude Code에 연결하는 방법은 gemini-cli-mcp-server-setup 또는 Anthropic 공식 문서의 “MCP Quickstart”를 참고하시기 바랍니다.

---