MCP 서버를 4단계로 만들기: 조사, 구현, 테스트, 평가 문항 작성

mkdir -p ~/.claude/skills/opencurrent-mcp-4 && curl -fsSL https://opencurrent.ai/w/mcp-4/SKILL.md -o ~/.claude/skills/opencurrent-mcp-4/SKILL.md

---
name: opencurrent-mcp-4
description: "외부 API를 LLM이 쓸 수 있게 TypeScript(SDK v2) 또는 Python MCP 서버로 만들고, MCP Inspector로 점검한 뒤 평가 질문 10개를 XML로 작성해요. 이럴 때 사용: 외부 API나 서비스를 LLM 에이전트가 도구로 쓸 수 있게 MCP 서버로 감싸야 할 때 써요. 도구: Claude Code, MCP TypeScript SDK v2, FastMCP, MCP Inspector, Zod."
metadata:
  source: "https://opencurrent.ai/w/mcp-4"
  opencurrent-id: "mcp-4"
  verification: "pending"
  exported-at: "2026-11-10T07:34:19.600Z"
---

# MCP 서버를 4단계로 만들기: 조사, 구현, 테스트, 평가 문항 작성

외부 API를 LLM이 쓸 수 있게 TypeScript(SDK v2) 또는 Python MCP 서버로 만들고, MCP Inspector로 점검한 뒤 평가 질문 10개를 XML로 작성해요.

> OpenCurrent에서 사람들이 다듬는 워크플로. 원문: https://opencurrent.ai/w/mcp-4
> 검증 상태: 검수 대기 (사람 확인 전). 내려받은 뒤에 바뀌었을 수 있으니, 가능하면 원문이나 MCP의 get_workflow("mcp-4")로 최신 상태를 확인할 것.
> 주의: AI 초안 · 사람 확인 전. 사용자에게 이 사실을 알리고, 결과를 함께 확인하면서 진행할 것.

## 따라 하는 방법

1. 입력값(inputs)을 사용자에게 받아 프롬프트의 {{이름}} 자리에 넣을 것. 필수값이 없으면 먼저 물어볼 것.
2. 단계를 순서대로 진행할 것. kind가 "ai"면 프롬프트를 실행하고, "command"면 사용자의 허락을 받고 명령을 실행하고, "human"이면 사용자에게 할 일을 안내하고 끝났는지 물을 것. tool이 있으면 그 도구·모델로 할 것.
3. 단계에 output(결과 이름)이 있으면 그 단계 결과를 뒤 단계 프롬프트의 {{output}} 자리에 넣을 것.
4. 단계마다 expected(기대 결과)와 check(확인 방법)로 제대로 됐는지 확인하고, 다르면 다음 단계로 넘어가지 말고 사용자에게 알릴 것. 끝나면 example.output(있으면)과 비교할 것.
5. 검증 상태가 verified가 아니면 그 사실을 사용자에게 먼저 알릴 것. 답에 url을 출처로 밝힐 것.

## 언제 쓰나

외부 API나 서비스를 LLM 에이전트가 도구로 쓸 수 있게 MCP 서버로 감싸야 할 때 써요.

## 준비물

- 연동할 외부 서비스의 API 문서를 볼 수 있어야 해요
- Node.js와 npm 또는 Python 환경이 필요해요
- 웹 문서를 가져올 수 있는 도구(WebFetch 등)가 있으면 좋아요

## 입력값

시작하기 전에 사용자에게 받아서 프롬프트의 `{{이름}}` 자리에 넣을 것.

- `{{service_name}}` 연동할 서비스 (필수): MCP 서버로 감쌀 외부 API나 서비스 이름이에요.
  - 예: GitHub
- `{{language}}` 구현 언어 (필수): TypeScript(권장) 또는 Python이에요.
  - 예: TypeScript

## 단계

### 1. MCP 설계 원칙 정하기 (사람이)

API 전체를 덮는 도구와 특정 작업용 워크플로 도구 사이에서 균형을 잡아요. 잘 모르겠으면 API 전체를 덮는 쪽을 먼저 고려해요. 도구 이름은 `github_create_issue`처럼 일관된 접두사와 동작 중심으로 짓고, 설명은 짧게 쓰고, 결과는 필터와 페이지 나누기를 지원해요. 오류 메시지에는 다음에 할 일을 구체적으로 넣어요.

기대 결과: 도구 범위, 이름 규칙, 오류 메시지 방침이 정리돼요.

확인 방법: 도구 이름에 공통 접두사가 있고 동작이 드러나는지 봐요.

### 2. MCP 프로토콜 문서 읽기 (사람이 · WebFetch)

`https://modelcontextprotocol.io/sitemap.xml`에서 필요한 페이지를 찾고, 주소 끝에 `.md`를 붙여 마크다운으로 가져와요. 명세 개요와 구조, 전송 방식(streamable HTTP, stdio), 도구·리소스·프롬프트 정의를 확인해요.

기대 결과: 명세 개요, 전송 방식, 도구 정의의 핵심을 파악해요.

확인 방법: 원격 서버는 stateless JSON 기반 Streamable HTTP, 로컬 서버는 stdio를 쓰기로 정했는지 확인해요.

### 3. 프레임워크 문서 불러오기 (사람이 · WebFetch)

언어를 정해요. TypeScript를 권장해요. TypeScript SDK는 새 서버라면 v2(`@modelcontextprotocol/server`)를 쓰고, `package.json`에 이미 `@modelcontextprotocol/sdk`(v1)가 있을 때만 v1을 써요. 한 프로젝트에 둘을 섞지 않아요. Python은 FastMCP를 써요. SDK README와 MCP 모범 사례 문서(`reference/mcp_best_practices.md`), 언어별 가이드를 불러와요.

기대 결과: 사용할 SDK 버전과 참고 문서가 정해져요.

확인 방법: v1과 v2 import가 섞여 있지 않은지 확인해요.

### 4. 구현 계획 세우기 (사람이)

대상 서비스의 API 문서에서 주요 엔드포인트, 인증 방식, 데이터 모델을 확인해요. 가장 흔한 작업부터 구현할 엔드포인트 목록을 만들어요.

기대 결과: 구현할 엔드포인트 목록과 인증 요구사항이 정리돼요.

확인 방법: 자주 쓰는 작업이 목록 앞쪽에 있는지 봐요.

### 5. 프로젝트 구조와 공통 기반 만들기 (AI에게 · Claude Code)

언어별 가이드에 따라 프로젝트를 세팅해요. 인증이 들어간 API 클라이언트, 오류 처리 도우미, 응답 포맷(JSON/Markdown), 페이지 나누기 지원을 공통 코드로 만들어요.

기대 결과: 공통 유틸리티를 갖춘 프로젝트 뼈대가 만들어져요.

확인 방법: API 호출과 오류 처리가 한곳에 모여 중복이 없는지 봐요.

### 6. 도구 구현하기 (AI에게 · Claude Code)

도구마다 Zod(TypeScript) 또는 Pydantic(Python)으로 입력 스키마를 정의하고, 제약 조건과 필드 설명, 예시를 넣어요. 가능하면 `outputSchema`와 `structuredContent`로 구조화된 결과도 돌려줘요. I/O는 async/await로 처리하고, 해당하는 곳에는 페이지 나누기를 넣어요. `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` 주석도 달아요.

기대 결과: 엔드포인트별 도구가 스키마, 설명, 주석과 함께 구현돼요.

확인 방법: 모든 도구에 입력 스키마와 4가지 주석이 있는지 봐요.

### 7. 코드 품질 검토하기 (사람이)

중복 코드, 일관된 오류 처리, 전체 타입 적용, 도구 설명의 명확성을 검토해요.

기대 결과: 고칠 점이 정리되고 반영돼요.

확인 방법: 같은 로직이 여러 곳에 복사돼 있지 않은지 봐요.

### 8. 빌드하고 테스트하기 (명령 실행 · MCP Inspector)

TypeScript는 `npm run build`로 컴파일을 확인해요. v2 프로젝트는 v2 가이드의 자체 점검 스크립트를 빌드된 서버에 돌려요. Python은 문법을 확인해요. 둘 다 MCP Inspector로 시험해요.

프롬프트:

```text
npm run build
npx @modelcontextprotocol/inspector
# Python 문법 확인
python -m py_compile your_server.py
```

기대 결과: 빌드가 성공하고 Inspector에서 도구가 호출돼요.

확인 방법: Inspector에서 도구 목록이 보이고 호출이 정상 응답하는지 확인해요.

### 9. 평가 질문 10개 만들기 (AI에게 · Claude Code)

평가 가이드(`reference/evaluation.md`)를 따라요. 먼저 도구 목록을 살피고, 읽기 전용 작업으로 데이터를 탐색해요. 그다음 복잡하고 현실적인 질문 10개를 만들고 직접 풀어 답을 검증해요. 각 질문은 서로 독립적이고 읽기 전용이며, 여러 번 도구를 호출해야 풀리고, 문자열 비교로 확인되는 하나의 답이 있고, 시간이 지나도 답이 변하지 않아야 해요.

기대 결과: 질문과 검증된 답 10쌍이 만들어져요.

확인 방법: 각 질문을 직접 풀어 답이 일치하는지, 답이 시간이 지나도 변하지 않는지 확인해요.

결과 이름: `{{evaluation_questions}}` — 이 결과를 뒤 단계 프롬프트의 같은 자리에 넣을 것.

### 10. 평가 XML 파일로 저장하기 (사람이)

질문과 답을 `<evaluation>` 아래 `<qa_pair>` 구조의 XML 파일로 저장해요.

프롬프트:

```text
<evaluation>
  <qa_pair>
    <question>Find discussions about AI model launches with animal codenames. One model needed a specific safety designation that uses the format ASL-X. What number X was being determined for the model named after a spotted wild cat?</question>
    <answer>3</answer>
  </qa_pair>
<!-- More qa_pairs... -->
</evaluation>
```

기대 결과: qa_pair 10개가 담긴 XML 평가 파일이 생겨요.

확인 방법: XML이 올바른 구조이고 질문 10개가 모두 들어 있는지 확인해요.

## 주의할 점

- v1(`@modelcontextprotocol/sdk`)과 v2(`@modelcontextprotocol/server`) 코드를 한 프로젝트에 섞으면 v1 샘플이 v2에 맞지 않아요.
- 원격 서버를 stateful 세션이나 스트리밍으로 만들면 확장과 유지가 어려워져요. stateless JSON을 권장해요.
- 평가 질문에 쓰기·삭제 같은 파괴적 작업이 들어가면 안 돼요.
- 시간이 지나면 답이 바뀌는 질문은 평가에 맞지 않아요.
- 원본이 가리키는 `reference/` 문서는 이 문서에 없어서, 세부 내용은 원 저장소에서 따로 확인해야 해요.

## 출처

- [mcp-builder](https://github.com/anthropics/skills/blob/2c5958ecac7cee2b583967a2c4981d0f4a75c579/skills/mcp-builder/SKILL.md)
- 원본 라이선스: Apache-2.0 (anthropics/skills · anthropics)

## 끝나면

결과가 좋았거나 단계가 낡았으면 https://opencurrent.ai/w/mcp-4 에서 알릴 것. 다음 사람이 더 정확한 방법을 쓸 수 있도록.