MCP Server 처음부터 개발: 2026 AI 도구 호출 구축 가이드

LLM이 아무리 똑똑해도 「손발」이 없으면 DB 조회, API 호출, 로컬 노트 읽기가 불가능합니다.Model Context Protocol(MCP)는 JSON-RPC로 AI 클라이언트와 외부 역량을 표준화 연결합니다——2026년 생태는 13,000+ Server, OpenAI·Google·Microsoft 전면 지원.페인포인트: Function Calling 각자 구현, 모델 교체 시 전면 재작성.결론: 본문을 마치면 MCP Server를 독립 개발·디버깅·프로덕션 배포할 수 있습니다.구성: 프로토콜 원리 → 환경 구축 → Hello World → Tools/Resources/Prompts → HTTP 원격 → 디버깅·테스트 → Docker 배포 → 개인 KB 실전 → 생태 전망.

1. MCP란? 프로토콜을 이해한 뒤 코드 작성

1.1 MCP 탄생 배경

도구 호출 역량은 3세대 진화를 거쳤습니다: Function Calling(OpenAI 독점 형식) → Plugins(ChatGPT 플러그인 생태, 쇠퇴) → MCP(개방 표준). Anthropic은 2024년 11월 MCP를 오픈소스화했습니다. 핵심 동기: AI 클라이언트를 바꿀 때마다 도구 통합을 재작성하는 N×M 폭발. MCP는 AI와 외부 도구의 통신 프로토콜 표준화를 해결합니다——Server를 한 번 작성하면 Cursor, Claude Desktop, VS Code 모두 사용 가능. 2026년 거버넌스는 Linux Foundation 산하 AAIF로 이관되었습니다.

1.2 MCP 프로토콜 아키텍처 개요

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (개발할 부분)       │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (도구 호출)   (리소스 읽기)  (프롬프트)

Client: AI 모델 측 호스트(Claude Desktop, Cursor, 커스텀 Agent). Server: 개발하는 역량 제공자. 3대 핵심 역량: Tools는 AI가 호출 가능한 함수(검색, 계산, SQL); Resources는 AI가 읽을 수 있는 데이터(파일, 설정, URL); Prompts는 파라미터 주입을 지원하는 사전 정의 프롬프트 템플릿.

1.3 MCP 통신 메커니즘

기반은 JSON-RPC 2.0. 전송 방식: stdio(로컬 자식 프로세스, 네트워크 설정 불필요)와 Streamable HTTP(2025-06-18 규격으로 구 HTTP+SSE 대체, 원격/멀티 클라이언트 적합). 라이프사이클: 초기화 핸드셰이크 → 역량 협상(tools/list) → 요청/응답 → 종료. ⚠️ 로컬 stdio 모드에서 stdout에 비프로토콜 로그 출력 금지, JSON-RPC 파싱 실패.

1.4 MCP vs 기타 솔루션 비교

비교 축	MCP	OpenAI Function Calling	LangChain Tools
표준화 수준	개방 프로토콜 표준	벤더 독점	프레임워크 종속
전송 방식	stdio / Streamable HTTP	HTTP	HTTP
크로스 모델	지원	미지원	부분
리소스/프롬프트	네이티브 지원	미지원	미지원
생태 도구	13,000+ Server(2026)	성숙	성숙

2. 개발 환경 준비

2.1 개발 언어 선택

Python(초보자 추천): 공식 SDK mcp + FastMCP 데코레이터, 간결하고 쉬움. TypeScript(프론트/풀스택): @modelcontextprotocol/sdk + Zod 검증, npm 다운로드 150M+. 본문은 Python 중심, TypeScript는 대조 설명.

2.2 환경 구축

# Python 환경
python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install "mcp[cli]"

# TypeScript 환경(대조)
npm init -y
npm install @modelcontextprotocol/sdk zod

2.3 프로젝트 구조 설계

my-mcp-server/
├── server.py            # 메인 서비스 진입점
├── tools/               # 도구 모듈
│   ├── calculator.py
│   └── web_search.py
├── resources/           # 리소스 모듈
│   └── file_reader.py
├── prompts/             # 프롬프트 템플릿
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

2.4 디버깅 도구 설치

1) MCP Inspector: npx @modelcontextprotocol/inspector python server.py, 브라우저 UI localhost:6274에서 Tools/Resources/Prompts 디버깅. 2) Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json 편집. 3) Cursor: Settings → MCP → mcpServers 설정 추가. 자세한 내용은 MCP 프로토콜 심층 해설 참조.

3. 첫 MCP Server: Hello World

3.1 가장 단순한 MCP Server

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """지정된 사람에게 인사"""
    return f"Hello, {name}! 첫 MCP 도구입니다."

if __name__ == "__main__":
    mcp.run()

3.2 실행 및 검증

python server.py
# 또는 MCP Inspector로 디버깅
npx @modelcontextprotocol/inspector python server.py

3.3 Cursor / Claude Desktop 연동

// claude_desktop_config.json 또는 Cursor MCP 설정
{
  "mcpServers": {
    "my-first-server": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

⚠️ Python 인터프리터와 스크립트에 절대 경로 필수. 클라이언트 재시작 후 대화에서 say_hello 도구가 컨텍스트에 표시되어야 합니다.

4. Tools: AI가 호출 가능한 도구 개발

4.1 도구 기본 구조

함수 시그니처가 문서: 파라미터 타입, 반환 타입, docstring이 SDK에 의해 JSON Schema로 자동 변환되어 LLM이 이해. 명명 규칙: 소문자+언더스코어, 의미 명확(web_search가 ws보다 우수). 에러 처리: 미처리 예외보다 구조화 에러 문자열 반환이 Server 전체 크래시 방지.

4.2 입력 파라미터 타입 지원

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색 키워드")
    max_results: int = Field(default=5, description="최대 반환 결과 수")
    language: str = Field(default="ko", description="결과 언어")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """네트워크 검색 실행, 관련 결과 목록 반환"""
  # 검색 로직 구현
    return [{"title": "예시", "url": "https://example.com"}]

4.3 실전: 5가지 실용 도구

도구	용도	핵심 구현
계산기	수식 평가	`eval`은 샌드박스 또는 `ast` 안전 파싱 필요
파일 읽기/쓰기	로컬 파일 R/W	허용 디렉터리 제한, 경로 탐색 방지
HTTP 요청	외부 API 호출	`httpx` + 30s 타임아웃
DB 쿼리	읽기 전용 SQL 실행	파라미터화 쿼리, DDL 금지
시간 도구	현재 시간/타임존 변환	`zoneinfo` 표준 라이브러리

4.4 비동기 도구 개발

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """지정 URL 콘텐츠 가져오기"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text[:10000]  # 토큰 폭발 방지 절단

4.5 도구 에러 처리 모범 사례

1) 구조화 에러: {"error": "...", "code": "TIMEOUT"} 문자열 반환. 2) 타임아웃: 모든 I/O에 30s 상한. 3) 권한 검증: Tool 계층에서 디렉터리/API 화이트리스트, LLM 「자각」에 의존 금지.

5. Resources: AI가 동적 콘텐츠 읽기

5.1 Resource vs Tool 차이

Resource는 데이터 제공자(주로 읽기 전용), Tool은 액션 실행자. URI 주소: file://, http://, custom:// 커스텀 scheme.

5.2 정적 vs 동적 리소스

import json

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """앱 설정 반환"""
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """사용자 ID 기반 프로필 반환"""
    return json.dumps({"user_id": user_id, "name": "Demo"})

5.3 리소스 타입

텍스트 리소스(text/plain, application/json), 바이너리(이미지/PDF, base64 반환), 스트리밍(실시간 시세, Streamable HTTP 필요).

5.4 실전: 파일시스템 리소스 서버

디렉터리 나열, 파일 내용 읽기, 파일 변경 구독(resources/subscribe) 가능. 프로덕션에서 루트 디렉터리 반드시 제한, 공식 mcp-server-filesystem allowlist 설계 참고.

6. Prompts: 재사용 가능한 프롬프트 템플릿 정의

6.1 MCP Prompt란?

사전 정의 프롬프트 조각, AI가 직접 재사용; 동적 파라미터 주입 지원; 팀 Prompt 일관성·유지보수 향상. Cursor Agent Skills와 보완: MCP Prompt = 프로토콜 계층 템플릿, Skill = 조작 매뉴얼.

6.2 프롬프트 템플릿 생성

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    """코드 리뷰 프롬프트 템플릿"""
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"""다음 {language} 코드를 리뷰해 주세요:
1. 코드 품질과 가독성
2. 잠재 Bug와 보안 위험
3. 성능 최적화 제안

```{language}
{code}
```"""
            )
        )
    ]

6.3 멀티턴 대화 프롬프트

user와 assistant를 포함한 멀티턴 템플릿 정의 가능. 시나리오: 면접 시뮬레이션(assistant가 면접관), 코드 디버깅 어시스턴트(assistant가 먼저 확인 질문).

7. 고급: HTTP 전송 모드(원격 MCP Server)

7.1 stdio vs Streamable HTTP

특성	stdio	Streamable HTTP
배포 방식	로컬 프로세스	원격 서버
지연	극저(<5ms)	네트워크 의존(50–200ms)
멀티 클라이언트	미지원	지원
적용 시나리오	로컬 도구, IDE 플러그인	SaaS/팀 공유/7×24

⚠️ 구 HTTP+SSE는 2025-06-18 규격에서 폐기, 신규 프로젝트는 Streamable HTTP 사용.

7.2 HTTP 전송 구현

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote-server")

if __name__ == "__main__":
    mcp.run(transport="streamable-http", host="127.0.0.1", port=8000)

프로덕션 배포는 uvicorn/gunicorn 리버스 프록시. Serverless(Cloud Run/Lambda)는 stateless_http=True 필요, 메모리 session이 콜드 스타트 시 소실.

7.3 인증 및 보안

Bearer Token 인증, API Key 미들웨어, CORS 화이트리스트, 요청 빈도 제한(권장 100 req/min/IP). 로컬 개발은 127.0.0.1 바인딩, 0.0.0.0 무인증 노출 금지. 2026년 30+ MCP 관련 CVE 공개, CVSS 9.6 mcp-remote RCE 포함.

8. 디버깅 및 테스트

8.1 MCP Inspector 디버깅

시작 후 UI에서: Tools 나열 → 수동 호출 → JSON-RPC 원문 확인 → 타임아웃/에러 시나리오 시뮬레이션. LLM 직접 연결 디버깅 대비 10× 효율.

8.2 단위 테스트 작성

import pytest
from mcp.client.session import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(
        command="python", args=["server.py"]
    )
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert "4" in result.content[0].text

8.3 흔한 에러 트러블슈팅

에러	원인	해결
도구가 AI에 미표시	설정 경로 오류	config.json 절대 경로 확인
JSON 직렬화 실패	미지원 반환 타입	str 또는 dict로 변환
타임아웃 끊김	도구 실행 지연	비동기 + 30s 타임아웃
권한 거부	파일 경로 제한	allowlist 디렉터리 설정

9. 프로덕션 배포

9.1 Docker 컨테이너화

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

9.2 클라우드 서비스 배포

Railway / Render: 원클릭 배포, 개인 프로젝트(월 $5–20). AWS Lambda / Google Cloud Run: Serverless, 호출 과금. 자체 VPS: Nginx 리버스 프록시 + Let's Encrypt + systemd/launchd 상시 실행.

9.3 모니터링 및 관측성

구조화 로그(JSON Lines), Prometheus 메트릭(mcp_tool_calls_total), Sentry 에러 알림, /health 헬스체크 엔드포인트. P99 지연 알림 임계값 5s 권장.

9.4 버전 관리 및 호환성

핸드셰이크 시 MCP 프로토콜 버전 선언; 도구 업그레이드 하위 호환(필수 파라미터 변경 대신 선택 파라미터 추가); capabilities 협상으로 Client가 없는 Tool 호출 방지.

10. 실전 프로젝트: 개인 지식베이스 MCP Server

10.1 프로젝트 요구사항

AI가 로컬 Markdown 노트 검색, 시맨틱 검색, 노트 생성/업데이트. Cursor에서 「지난주 MCP 관련 노트에 뭐 적었지?」 질문.

10.2 기술 선정

컴포넌트	선정	이유
벡터 DB	ChromaDB / Qdrant	로컬 경량, 무운영
임베딩 모델	text-embedding-3-small	1536차원, 저비용
파일 감시	watchfiles	노트 변경 자동 재인덱스

10.3 핵심 코드 구현

4개 모듈: index_notes 도구(디렉터리 스캔 인덱스), semantic_search 도구(벡터 검색 Top-K), write_note 도구(Markdown 생성/추가), notes://{path} 리소스(단일 파일 직접 읽기). 약 1000편 인덱스 2–5분(M4 Pro).

10.4 효과 데모

사용자 Cursor 입력: 「지난주 MCP 배포 노트에 뭐라고 적었지?」→ Agent semantic_search(query="MCP 배포", days=7) 호출 → 3개 관련 조각(유사도 0.82–0.91) 반환 → LLM 종합 답변 및 원문 인용. 전체 노트를 Context Window에 넣을 필요 없음.

11. MCP 생태 및 미래 전망

11.1 우수 MCP Server 추천

mcp-server-filesystem(파일시스템), mcp-server-github(저장소), mcp-server-brave-search(웹 검색), mcp-server-postgres(DB), mcp-server-slack(메시지). 공식 레지스트리 13,000+ Server 추적.

11.2 MCP 생태 트렌드(2026)

4대 벤더 전면 지원; MCP Marketplace 부상; 엔터프라이즈 OAuth 2.1 인증 로드맵; Google A2A 프로토콜 보완(MCP = 수직 도구 계층, A2A = Agent 가로 오케스트레이션).

11.3 다음 학습 경로

① modelcontextprotocol.io 규격 정독; ② 첫 공개 MCP Server 배포; ③ MCP + Agent 조합 탐색; ④ 오픈소스 생태(Python/TS SDK) 기여.

12. 5단계 도입 체크리스트

Step 1 — FastMCP로 Hello World, Inspector 검증. Step 2 — 3개 비즈니스 Tool + 1개 Resource 등록. Step 3 — Cursor / Claude Desktop 연동(절대 경로 설정). Step 4 — 필요 시 Streamable HTTP 원격 배포. Step 5 — Docker + 모니터링 + 보안 감사 프로덕션.

13. 인용 가능 수치

지표	수치
MCP Server 생태(2026)	13,000+
18개월 성장 배수	7.8×(1,200 → 9,400+)
TS SDK 누적 다운로드	150M+
2026 MCP 관련 CVE	30+
권장 Tool I/O 타임아웃	30s
KB 인덱스(1000편)	2–5 min(M4 Pro)

14. 심층 사례: 로컬 stdio에서 Mac 원격 연산 노드로

한 AI 엔지니어가 MacBook Air에서 Cursor + 5개 stdio MCP Server(filesystem, postgres, brave-search, 커스텀 KB, 브라우저 도구) 동시 실행. 통합 메모리 24GB 상주 19GB, 노트북 발열 클럭 다운, 덮개 닫으면 끊김. 마이그레이션: 로컬은 Cursor Host만; 5 Server를 Streamable HTTP로 원격 Mac mini(64GB 통합 메모리)에 배포, launchd 상시; 로컬은 url: http://node.macgpu.local:8000/mcp 연결. Tool 호출 P99 지연이 로컬 180ms에서 95ms로(원격 노드 클럭 다운 없음)——오히려 안정.

Windows/Linux VPS에서도 MCP Server는 동작하지만, Xcode·ComfyUI·Final Cut과 병행하는 그래픽/멀티미디어 + AI 툴체인 시나리오에서 macOS가 여전히 매끄럽습니다. 로컬 stdio는 개발·검증용; 7×24 프로덕션 상주에는 원격 Apple Silicon 노드가 적합: 통합 메모리를 동시 Tool 호출에 할당, 노트북은 오케스트레이션만.

안정적이고 임대 가능한 환경에서 MCP Server 클러스터와 Agent Gateway를 호스팅하려면 MACGPU 원격 Mac 노드를 고려하세요. 7×24 상주, HTTP 리버스 프록시 구성 완료, 통합 메모리가 다중 자식 프로세스에 잠식되지 않음——「돌아간다」에서 「안정적으로 돈다」까지, 노드 하나면 충분합니다.