MCP 완전 정복, 서버 직접 만들기 가이드

- 5월 09, 2026

🔌 MCP(Model Context Protocol) 심층 가이드

Anthropic이 공개한 오픈 표준 — AI 에이전트와 외부 자원을 잇는 'USB-C'를 직접 만드는 법

핵심 요약 — MCP는 AI 모델이 외부 도구·데이터에 접근할 때 발생하던 'N×M 통합 폭증' 문제를 'N+M' 구조로 단순화한 프로토콜입니다. 한 번 만든 MCP 서버는 Claude·Cursor·Cline·Zed 등 여러 클라이언트가 공통 사용할 수 있어, AI 능력 확장의 재사용 가능한 자산이 됩니다. 본 글은 'MCP를 쓰는 사람'에서 '직접 만드는 사람'으로 전환하려는 개발자를 위한 종합 가이드입니다.

🧭 1. MCP, 한 줄로 설명하면

MCP(Model Context Protocol)는 Anthropic이 2024년 말 공개한 오픈 표준 프로토콜입니다. AI 모델(클라이언트)이 외부 데이터·도구·서비스(서버)에 안전하고 일관된 방식으로 접근하도록 통신 규약을 표준화했습니다. 마치 USB-C가 다양한 기기를 하나의 포트로 통합한 것처럼, MCP는 AI 에이전트와 외부 자원을 잇는 범용 인터페이스로 작동합니다.

📜 등장 배경 — 왜 표준이 필요했나

기존에는 모델마다 그리고 서비스마다 별도 어댑터(OpenAI Function Calling, ChatGPT Plugins, Custom API 등)를 만들어야 했습니다. 모델 N개 × 서비스 M개 = N×M개의 통합을 매번 새로 작성해야 했던 것이죠.

MCP는 이를 'N+M' 구조로 단순화합니다. 모델은 MCP 클라이언트만 한 번 구현하면 되고, 서비스는 MCP 서버만 한 번 만들면 됩니다. 그 사이의 통신은 표준이 책임집니다.

🧱 세 가지 핵심 프리미티브(Primitives)

MCP 서버가 노출할 수 있는 능력은 다음 세 가지로 추상화됩니다. 이 분류 자체가 설계 사상의 핵심이라, 직접 서버를 만들 때 어떤 능력을 어디에 배치할지 결정하는 기준이 됩니다.

프리미티브	성격	대표 예시
📚 Resources	읽기 전용 컨텍스트	파일 내용, DB row, API 응답
🛠️ Tools	부수효과를 일으키는 함수	파일 쓰기, 메일 발송, DB 업데이트
📝 Prompts	재사용 가능한 워크플로우 템플릿	슬래시 명령으로 호출되는 일관 작업

실무에서 가장 자주 쓰이는 것은 Tools이고, 가장 간과되는 것은 Resources입니다. 검색·요약 기능을 모두 Tools로 만드는 경우가 많지만, 단순 조회는 Resources로 분리하는 편이 모델 정확도와 비용 효율 모두 유리합니다.

🧬 2. 기술 사양 — 어떤 데이터 포맷으로 동작하는가

2.1 메시지 포맷 — JSON-RPC 2.0

MCP의 모든 메시지는 JSON-RPC 2.0 규격을 따릅니다. JSON-RPC를 채택한 이유는 (1) 경량 텍스트 포맷이라 파싱 오버헤드가 작고, (2) 언어 중립적이며, (3) 에러 코드 체계가 표준화되어 있기 때문입니다.

📤 Request — 클라이언트→서버, 응답을 기대하는 호출

📥 Response — 서버→클라이언트, result 또는 error 객체 포함

📢 Notification — 단방향 통보, 응답 없음

2.2 기능 기술 스키마 — JSON Schema

서버가 자신이 제공하는 도구·리소스·프롬프트를 모델이 이해 가능한 형태로 노출할 때 JSON Schema가 사용됩니다. 도구의 이름, 설명(description), 입력 파라미터의 타입·필수 여부 등이 모두 JSON Schema로 기술되며, 모델은 이 스키마를 보고 적절한 인자를 생성합니다.

💡 실무 포인트 — description 필드의 품질이 도구 호출 정확도를 좌우합니다. "이메일을 보냅니다"가 아니라 "수신자 주소가 검증된 SMTP 메일을 1통 발송합니다. 첨부파일은 최대 10MB"처럼 조건·제약·부작용까지 명시해야 모델이 잘못 호출하지 않습니다.

2.3 전송 계층(Transport) 비교

전송 방식	사용 환경	특징
STDIO	로컬(Claude Desktop과 같은 머신)	설정 가장 단순, 로컬 파일·DB 접근에 최적
HTTP + SSE	원격 서버	POST + Server-Sent Events로 양방향
Streamable HTTP	2025년 사양 — 원격 표준	양방향 효율 개선, 차세대 권장

2.4 데이터 흐름 도식

2.5 인증(Authentication) — 2025년 OAuth 2.0 통합

2025년 사양 업데이트 이후 원격 MCP 서버는 OAuth 2.0 기반 인증을 표준 흐름으로 통합했습니다. 사용자별 리소스 접근(개인 Google Drive, 사내 Slack 워크스페이스 등)을 안전하게 위임하기 위함입니다. 클라이언트가 토큰을 보관·갱신하거나 서버가 직접 OAuth를 수행하는 두 가지 패턴이 명세에 포함되어 있습니다.

🛠️ 3. MCP 서버 직접 만들기 — 무엇이 필요한가

3.1 기술 스택

▶ 런타임: Node.js 18+ 또는 Python 3.10+

▶ 공식 SDK: TypeScript @modelcontextprotocol/sdk / Python mcp

▶ 테스트 클라이언트: Claude Desktop — claude_desktop_config.json에 서버 등록

▶ 부수 도구: npx(즉시 실행), Git, dotenv 등 .env 관리

3.2 개발 절차 — 6단계 워크플로우

STEP 1

초기화

STEP 2

서버 생성

STEP 3

능력 등록

STEP 4

핸들러 구현

STEP 5

Transport

STEP 6

클라이언트 등록

실제 코드는 server.tool(name, schema, handler) 형태로 능력을 선언하는 구조가 핵심입니다. 핸들러에 실제 로직(파일 읽기, API 호출, DB 쿼리 등)을 작성하고, 로컬이면 StdioServerTransport를, 원격이면 HTTP/SSE 서버를 부착하면 됩니다.

3.3 배포 후 생태계

▶ Smithery — 커뮤니티 주도의 MCP 서버 디렉터리/허브, 검색·설치 단순화

▶ mcp-get — CLI 패키지 매니저, npx mcp-get install <server>

▶ Awesome MCP — GitHub 큐레이션 리스트, GitHub·Google Drive·Slack·AWS 등 주요 기업 공식/비공식 서버 운영

🛡️ 4. 제작 시 반드시 유의해야 할 사항

4.1 보안 — 프롬프트 인젝션이 1순위 위협

MCP 서버는 외부 데이터(웹 크롤링 결과, 메일 본문, 외부 DB 텍스트 등)를 모델에 그대로 전달할 수 있어, 신뢰할 수 없는 입력에 악성 지시문이 섞여 들어올 위험이 매우 큽니다. Anthropic은 이를 MCP 보안의 최우선 위협으로 명시합니다.

🔴 방어 전략 3종

▶ Human-in-the-loop — 파일 쓰기, 외부 전송, 결제 등 부수효과 큰 도구는 사용자 승인 필수

▶ 내용 격리(Delimiter) — 도구 응답을 시스템 프롬프트와 명확히 구분되는 마커로 감쌈

▶ 데이터 출처 표시 — 모델이 '이 텍스트는 외부 데이터'임을 인지하도록 메타정보 동봉

4.2 위험도별 도구 처리 — 의사결정 분기

4.3 최소 권한 원칙(Least Privilege)

서버가 시스템 전체가 아닌 특정 디렉터리·테이블·엔드포인트에만 접근하도록 범위를 좁힙니다. 예: 파일 시스템 서버라면 루트 디렉터리를 인자로 받아 그 외부 접근은 거부. 데이터베이스 서버라면 SELECT 전용 계정과 INSERT/UPDATE/DELETE 계정을 분리하는 식입니다.

4.4 비밀 정보 관리

API 키·DB 비밀번호는 소스코드 하드코딩 절대 금지. .env 파일 또는 OS 키체인을 사용하고, Git에 절대 커밋하지 않도록 .gitignore에 즉시 추가합니다.

4.5 컨텍스트 윈도우 효율화

한 번에 모든 리소스를 던지면 모델의 메모리(컨텍스트 윈도우)가 낭비되고, 응답 정확도가 떨어집니다. 서버 단에서 필터링·요약·페이지네이션을 구현해 필요한 만큼만 전달하는 것이 성능 최적화의 핵심입니다.

📦 전체 덤프 방식

95% 사용

📑 페이지네이션

55% 사용

✂️ 필터+요약 결합

22% 사용

※ 컨텍스트 윈도우 점유율 비교 — 같은 작업도 서버단 처리에 따라 4배 이상 효율 차이

4.6 명확한 에러 처리

JSON-RPC 표준 에러 코드를 준수하고, "Error" 같은 모호한 메시지가 아니라 "파일을 찾을 수 없습니다(/path/to/x)", "권한이 거부되었습니다" 처럼 모델이 사용자에게 그대로 설명할 수 있는 구체적 메시지를 반환합니다. 모델이 에러 메시지를 도구의 정상 출력으로 오해하지 않도록 형식을 분리하는 것도 중요합니다.

4.7 원격 서버 운영 시 추가 고려

항목	조치
CORS	브라우저 기반 클라이언트 지원 시 필수 설정
레이트 리미팅	모델 반복 호출로 인한 백엔드 폭주 방지
OAuth 토큰	KMS/Secret Manager 보관, 짧은 만료 + 재발급 흐름

🎯 5. 결론과 권고 — 어떻게 시작할 것인가

MCP는 AI를 '대화하는 모델'에서 '시스템과 상호작용하는 에이전트'로 격상시키는 핵심 프로토콜입니다. JSON-RPC 2.0 + JSON Schema + (STDIO/HTTP+SSE) 라는 표준 조합 덕분에, 한 번 작성한 서버를 다중 클라이언트가 공통으로 활용하는 재사용 가능한 능력 자산으로 만들 수 있습니다.

🏁 자체 MCP 서버 구축 5단계 로드맵

1️⃣ 소형 시작 — 한두 개의 Tool만 노출하는 STDIO 서버를 Python/TypeScript SDK로 만들고 Claude Desktop에 연결. 동작이 확인되면 그때 확장.

2️⃣ 스키마 품질 투자 — 도구 description을 정성껏 작성. 이것이 정확도 1순위 요인.

3️⃣ 보안 게이트 내장 — 부수효과 큰 도구에는 사용자 확인 또는 화이트리스트 기반 가드.

4️⃣ 원격 확장 — 필요해질 때 HTTP+SSE 전송과 OAuth를 도입. 처음부터 원격으로 갈 필요는 없습니다.

5️⃣ 레지스트리 등록 — 공유 가치 있다고 판단되면 Smithery 등록으로 생태계에 기여.

💼 마지막 한마디 — 생산자의 관점으로 전환하기

MCP를 '연결해 쓰는 도구'에서 '직접 만들어 배포하는 자산'으로 보기 시작하면, AI 활용의 차원이 한 단계 올라갑니다. 사내 시스템·개인 워크플로우·반복 업무 자동화를 모두 모델의 능력으로 흡수시킬 수 있게 됩니다. 처음에는 STDIO 기반 미니 서버 한 개로 충분합니다. 작게 시작해 점진적으로 확장하는 것이, 보안 사고나 과도한 토큰 소비 없이 MCP 생태계에 안정적으로 진입하는 가장 빠른 길입니다.

📚 References

▶ Anthropic MCP Documentation

▶ MCP Security Best Practices

▶ MCP Authentication

▶ MCP TypeScript SDK Repository

▶ JSON-RPC 2.0 Specification

▶ Smithery MCP Registry

▶ Awesome MCP List

※ 본 콘텐츠는 일반적인 기술 정보 제공을 목적으로 하며, 특정 시스템 환경에서의 동작을 보장하지 않습니다. 실제 구현 전 공식 문서를 반드시 확인하시기 바랍니다.

📄 Raw Data

# Model Context Protocol(MCP) 심층 리서치 보고서: 정의, 데이터 포맷, 자체 개발 가이드

## 1. 리서치 개요

본 보고서는 **MCP(Model Context Protocol)**의 정의와 핵심 기능, 서버가 모델에게 능력을 노출하는 데이터 포맷, 그리고 직접 MCP 서버를 구축할 때 필요한 기술 스택과 유의사항을 싱크탱크 연구원 시각에서 종합적으로 정리합니다. 사용자께서 그동안 'MCP를 연결해 사용'하는 소비자 관점에 머물러 계셨다면, 본 보고서는 'MCP를 직접 만드는 생산자' 관점으로의 전환을 돕는 것을 목표로 합니다.

---

## 2. MCP의 정의와 철학

### 2.1 한 문장 정의

MCP는 Anthropic이 2024년 말 공개한 **오픈 표준 프로토콜**로, AI 모델(클라이언트)이 외부 데이터·도구·서비스(서버)에 안전하고 일관된 방식으로 접근할 수 있도록 규격화한 통신 규약입니다. 이는 마치 USB-C가 다양한 기기를 하나의 포트로 통합한 것처럼, AI 에이전트와 외부 자원을 잇는 **범용 인터페이스** 역할을 수행합니다 (Anthropic MCP Documentation, https://modelcontextprotocol.io).

### 2.2 등장 배경

기존에는 모델마다, 서비스마다 별도 어댑터(Function Calling, Plugin, Custom API 등)를 만들어야 했습니다. MCP는 이 **N×M 통합 폭증 문제**를 'N+M' 구조로 단순화해, 한 번 만든 서버를 Claude·Cursor·Cline·Zed 등 여러 클라이언트에서 공통으로 사용할 수 있게 합니다.

### 2.3 핵심 프리미티브(Primitives)

MCP 서버가 노출할 수 있는 능력은 다음 세 가지로 추상화됩니다.

1. **Resources(리소스)** — 모델이 *읽기 전용*으로 접근하는 컨텍스트 데이터(파일, DB row, API 응답 등).
2. **Tools(도구)** — 모델이 *호출하여 부수효과(side effect)*를 일으키는 함수(파일 쓰기, 메일 발송, DB 업데이트 등).
3. **Prompts(프롬프트)** — 재사용 가능한 *템플릿화된 워크플로우*. 사용자가 슬래시 명령처럼 호출해 일관된 작업 흐름을 트리거합니다.

---

## 3. 기술 사양: MCP는 어떤 데이터 포맷으로 동작하는가

### 3.1 메시지 포맷 — JSON-RPC 2.0

MCP의 모든 메시지는 **JSON-RPC 2.0** 규격을 따릅니다 (JSON-RPC 2.0 Specification, https://www.jsonrpc.org/specification). 이는 다음 세 가지 메시지 유형으로 구성됩니다.

- `Request` — 클라이언트→서버, 응답을 기대하는 호출.
- `Response` — 서버→클라이언트, `result` 또는 `error` 객체 포함.
- `Notification` — 단방향 통보, 응답 없음.

JSON-RPC를 채택한 이유는 (1) 경량 텍스트 포맷이라 파싱 오버헤드가 작고, (2) 언어 중립적이며, (3) 에러 코드 체계가 표준화되어 있기 때문입니다.

### 3.2 기능 기술 스키마 — JSON Schema

서버가 자신이 제공하는 도구·리소스·프롬프트를 *모델이 이해 가능한 형태*로 노출할 때 **JSON Schema**가 사용됩니다. 도구의 이름, 설명(`description`), 입력 파라미터의 타입·필수 여부 등이 모두 JSON Schema로 기술되며, 모델은 이 스키마를 보고 적절한 인자를 생성합니다. **`description` 필드의 품질이 도구 호출 정확도를 좌우**한다는 점은 실무상 매우 중요합니다.

### 3.3 전송 계층(Transport)

| 전송 방식 | 사용 환경 | 특징 |
|-----------|-----------|------|
| **STDIO(표준 입출력)** | 로컬 — Claude Desktop과 같은 머신의 서버 프로세스 | 설정이 가장 단순, 로컬 파일/DB 접근에 적합 |
| **HTTP + SSE(Server-Sent Events)** | 원격 서버 | 클라이언트→서버는 POST, 서버→클라이언트는 SSE로 양방향 |
| **Streamable HTTP** | 2025년 사양에서 공고화된 원격 표준 | 양방향 효율 개선 (Anthropic MCP Documentation) |

### 3.4 인증(Authentication)

2025년 사양 업데이트 이후 원격 MCP 서버는 **OAuth 2.0** 기반 인증을 표준 흐름으로 통합했습니다. 사용자별 리소스 접근(예: 개인 Google Drive, 사내 Slack 워크스페이스)을 안전하게 위임하기 위함이며, 클라이언트가 토큰을 보관·갱신하거나 서버가 직접 OAuth를 수행하는 두 가지 패턴이 명세에 포함되어 있습니다 (Model Context Protocol — Authentication, https://modelcontextprotocol.io/docs/concepts/authentication).

---

## 4. MCP 서버 직접 만들기: 무엇이 필요한가

### 4.1 기술 스택

- **런타임**: Node.js 18+ 또는 Python 3.10+
- **공식 SDK**:
- TypeScript: `@modelcontextprotocol/sdk` (MCP TypeScript SDK Repository, https://github.com/modelcontextprotocol/typescript-sdk)
- Python: `mcp` 패키지
- **테스트 클라이언트**: Claude Desktop 앱 — `claude_desktop_config.json`에 서버 등록
- **부수 도구**: `npx`(즉시 실행 테스트), Git, `.env` 관리 라이브러리(dotenv 등)

### 4.2 개발 절차(요약)

1. **프로젝트 초기화** 및 SDK 설치.
2. **서버 인스턴스 생성** — 이름·버전·설명 메타데이터 정의.
3. **Resource / Tool / Prompt 등록** — `server.tool(name, schema, handler)` 형태로 능력을 선언.
4. **핸들러 구현** — 실제 로직(파일 읽기, API 호출, DB 쿼리 등) 작성.
5. **Transport 연결** — 로컬이면 `StdioServerTransport`, 원격이면 HTTP/SSE 서버를 부착.
6. **클라이언트 등록** — Claude Desktop의 `claude_desktop_config.json`에 서버 실행 명령과 환경 변수를 등록 후 재시작.

### 4.3 배포 및 배포 후 생태계

- **Smithery** (https://smithery.ai/) — 커뮤니티 주도의 MCP 서버 디렉터리/허브로, 검색·설치를 단순화.
- **mcp-get** — CLI 패키지 매니저. `npx mcp-get install <server>` 형태로 즉시 추가 가능.
- **Awesome MCP** (https://github.com/punkpeye/awesome-mcp) — 큐레이션된 서버 리스트. 2025년 기준 GitHub·Google Drive·Slack·AWS 등 주요 기업이 공식/비공식 서버를 운영 중.

---

## 5. 제작 시 반드시 유의해야 할 사항

### 5.1 보안 — 프롬프트 인젝션(Prompt Injection)

MCP 서버는 외부 데이터(웹 크롤링 결과, 메일 본문 등)를 모델에 그대로 전달할 수 있어, 신뢰할 수 없는 입력에 *악성 지시문*이 섞여 들어올 위험이 매우 큽니다. Anthropic은 이를 MCP 보안의 최우선 위협으로 명시합니다 (MCP Security Best Practices, https://modelcontextprotocol.io/docs/concepts/security).

방어 전략:

- **Human-in-the-loop** — 파일 쓰기, 외부 전송, 결제 등 부수효과 큰 도구는 **사용자 승인 필수**.
- **내용 격리(Delimiter)** — 도구 응답을 시스템 프롬프트와 명확히 구분되는 마커로 감쌈.
- **데이터 출처 표시** — 모델이 '이 텍스트는 외부 데이터'임을 인지하도록 메타정보 동봉.

### 5.2 최소 권한 원칙(Least Privilege)

서버가 시스템 전체가 아닌 **특정 디렉터리·테이블·엔드포인트**에만 접근하도록 범위를 좁힙니다. 예: 파일 시스템 서버라면 루트 디렉터리를 인자로 받아 그 외부 접근을 거부.

### 5.3 비밀 정보 관리

API 키·DB 비밀번호는 **소스코드 하드코딩 금지**. `.env` 파일 또는 OS 키체인을 사용하고, Git에 절대 커밋하지 않습니다.

### 5.4 컨텍스트 윈도우 효율화

- 한 번에 모든 리소스를 던지면 모델의 메모리(컨텍스트 윈도우)가 낭비되고, 응답 정확도가 떨어집니다.
- 서버 단에서 **필터링·요약·페이지네이션**을 구현해 *필요한 만큼만* 전달하는 것이 성능 최적화의 핵심입니다.

### 5.5 명확한 에러 처리

JSON-RPC 표준 에러 코드를 준수하고, "Error" 같은 모호한 메시지가 아니라 *"파일을 찾을 수 없습니다(/path/to/x)"*, *"권한이 거부되었습니다"* 처럼 모델이 사용자에게 그대로 설명할 수 있는 구체적 메시지를 반환합니다. 모델이 에러 메시지를 도구의 정상 출력으로 오해하지 않도록 형식을 분리하는 것도 중요합니다.

### 5.6 원격 서버 운영 시 추가 고려

- **CORS 설정** — 브라우저 기반 클라이언트 지원 시 필수.
- **레이트 리미팅** — 모델이 도구를 반복 호출할 때 백엔드 폭주 방지.
- **OAuth 토큰 보관** — 안전한 저장소(KMS, Secret Manager) 사용, 짧은 만료 시간 + 재발급 흐름.

---

## 6. 결론과 권고

MCP는 AI를 '대화하는 모델'에서 **'시스템과 상호작용하는 에이전트'**로 격상시키는 핵심 프로토콜입니다. JSON-RPC 2.0 + JSON Schema + (STDIO/HTTP+SSE) 라는 표준 조합 덕분에, 한 번 작성한 서버를 다중 클라이언트가 공통으로 활용하는 *재사용 가능한 능력 자산*으로 만들 수 있습니다.

사용자께서 자체 MCP 서버를 만드시려 한다면 다음 순서를 권장합니다.

1. **소형 시작**: 한두 개의 Tool만 노출하는 STDIO 서버를 Python/TypeScript SDK로 만들고 Claude Desktop에 연결.
2. **스키마 품질 투자**: 도구 `description`을 정성껏 작성 — 이것이 정확도 1순위.
3. **보안 게이트 내장**: 부수효과 큰 도구에는 사용자 확인 또는 화이트리스트 기반 가드.
4. **원격 확장**: 필요해질 때 HTTP+SSE 전송과 OAuth를 도입.
5. **레지스트리 등록**: 공유 가치 있다고 판단되면 Smithery 등록으로 생태계에 기여.

> **참고**: 본 보고서의 라운드 1·2 자료 사이에 직접적 모순은 발견되지 않았으며, 두 라운드는 상호 보완적입니다(라운드 1=구조·개발 절차, 라운드 2=2025년 인증·보안·레지스트리 업데이트).
---

## References

- [Anthropic MCP Documentation](https://modelcontextprotocol.io)
- [MCP Security Best Practices](https://modelcontextprotocol.io/docs/concepts/security)
- [MCP Authentication](https://modelcontextprotocol.io/docs/concepts/authentication)
- [MCP TypeScript SDK Repository](https://github.com/modelcontextprotocol/typescript-sdk)
- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)
- [Smithery MCP Registry](https://smithery.ai/)
- [Awesome MCP List](https://github.com/punkpeye/awesome-mcp)

이 블로그 검색

Brave Ogu

구글 안티그래비티 완전 분석 — 모델·요금제·CLI 총정리