개발자가 MCP Server를 처음부터 구축해 AI 클라이언트와 외부 도구를 연결하는 아키텍처 다이어그램

MCP Server 처음부터 개발하기: AI 도구 호출 완전 가이드

2026년 LLM은 아무리 똑똑해도 사내 DB 조회, 내부 API 호출, 로컬 파일 읽기를 직접 못 합니다. 모델 성능 문제가 아니라 표준화된 도구 호출 채널이 없기 때문입니다. Model Context Protocol(MCP)은 Anthropic이 오픈소스한 해법으로, Claude·Cursor·GPT가 단일 프로토콜로 외부 능력에 접근하게 합니다. 이 글을 끝까지 읽으면 Tools·Resources·Prompts 3대 핵심과 HTTP 원격 전송까지 포함해 프로덕션급 MCP Server를 독립적으로 개발·디버깅·배포할 수 있습니다.

1. 3대 페인포인트: AI에 MCP Server가 필요한 이유

코드 한 줄 쓰기 전에 해결할 실제 문제부터 정리합니다.

  1. 도구 사일로: Function Calling·Plugins·LangChain Tools가 각각 다른 포맷——모델 벤더를 바꿀 때마다 통합층을 다시 짜야 하는 전형적 N×M 딜레마.
  2. 데이터 비접근: 학습 데이터 컷오프로 실시간 설정·내부 문서·DB 상태를 읽을 수 없음.
  3. 액션 불가: 순수 대화형 AI는 HTTP 요청·파일 쓰기·SQL 실행을 대신 못 함——표준화된 도구 계층으로 능력을 노출해야 함.

《2026 MCP 트렌드: AI 시대 HTTP급 표준》을 이미 읽었다면 프로토콜 선정 논쟁은 생략하고 코드 구현으로 바로 들어갑니다. 대상: Python 또는 TypeScript 기초가 있는 백엔드/AI 개발자.

2. MCP란: 프로토콜 원리와 아키텍처 개요

2.1 MCP 탄생 배경과 2026 포지션

LLM 도구 호출은 3세대를 거쳤습니다: Function Calling(OpenAI 독점) → Plugins(ChatGPT 폐쇄 생태) → MCP(2024.11 Anthropic 오픈 프로토콜). 2026년 현재 Cursor·Claude Desktop·VS Code Copilot·Gemini CLI가 네이티브 지원하고, AAIF 거버넌스 하에 10,000+ Server가 등록됐습니다. 핵심 가치: AI↔외부 도구 통신 표준화——한 번 구현, 다중 클라이언트 재사용.

2.2 프로토콜 아키텍처: Client ↔ Server ↔ 3대 능력

┌────────────────────┐         ┌─────────────────────┐
│   MCP Client       │ ◄─────► │   MCP Server        │
│  (Claude / Cursor) │  JSON   │  (당신이 개발)       │
│                    │  -RPC   │                     │
└────────────────────┘         └─────────────────────┘
                                        │
                          ┌─────────────┼─────────────┐
                          ▼             ▼             ▼
                       Tools       Resources      Prompts
                    (도구 호출)    (리소스 읽기)   (프롬프트)
  • Client: AI 모델 측——Claude Desktop, Cursor, VS Code, 커스텀 Agent.
  • Server: 당신이 개발하는 능력 제공층. Tools/Resources/Prompts 노출.
  • Tools: AI 호출 함수(검색, 계산, DB 쿼리, 파일 쓰기).
  • Resources: AI 읽기 리소스(파일, URL, 설정 스트림). URI 주소 지정.
  • Prompts: 사전 정의 프롬프트 템플릿. 동적 파라미터 주입.

2.3 통신 메커니즘

MCP는 JSON-RPC 2.0 기반. 전송 2종:

  • stdio: 로컬 자식 프로세스. Client가 Server를 띄우고 stdin/stdout 통신. 지연 <1ms.
  • HTTP + SSE / Streamable HTTP: 원격 서비스. 다중 클라이언트 동시 연결.

라이프사이클: 초기화 핸드셰이크 → 능력 협상(tools/list, resources/list) → 요청/응답(tools/call) → 종료.

2.4 MCP vs 대안 비교 매트릭스

비교 축 MCP OpenAI Function Calling LangChain Tools
표준화 오픈 프로토콜 벤더 독점 프레임워크 종속
전송 stdio / HTTP HTTP HTTP
크로스 모델 지원(Claude, GPT, Gemini 등) 미지원 부분
Resources / Prompts 네이티브 미지원 미지원
2026 생태 규모 10,000+ Server, AAIF 성숙·폐쇄 성숙·Python 종속

3. 개발 환경 준비와 프로젝트 구조

3.1 언어 선택

  • Python(본문 주언어): 공식 SDK mcp, FastMCP 데코레이터로 최소 코드.
  • TypeScript(대조): @modelcontextprotocol/sdk. Node/풀스택 개발자용.

3.2 환경 구축

# Python
python -m venv .venv
source .venv/bin/activate
pip install mcp httpx pydantic

# TypeScript
npm init -y
npm install @modelcontextprotocol/sdk

3.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

3.4 디버깅 도구

  • MCP Inspector: 공식 디버그 UI. Tools/Resources/Prompts 시각 테스트.
  • Claude Desktop: claude_desktop_config.json 편집.
  • Cursor: Settings → MCP 또는 .cursor/mcp.json.

4. 첫 MCP Server: Hello World

4.1 최소 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()

4.2 실행·검증

python server.py
npx @modelcontextprotocol/inspector python server.py

Inspector에서 tools/list에 say_hello 반환 확인 → tools/call에 {"name": "개발자"} 전달해 응답 검증.

4.3 Cursor / Claude Desktop 연결

{
  "mcpServers": {
    "my-first-server": {
      "command": "python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Cursor는 .cursor/mcp.json, Claude Desktop은 macOS ~/Library/Application Support/Claude/claude_desktop_config.json. 클라이언트 재시작 후 Agent 대화에서 say_hello 도구가 컨텍스트에 표시됩니다.

5. Tools: AI가 호출할 도구 개발

5.1 도구 기본 구조

함수 시그니처가 곧 문서. 파라미터·반환 타입·docstring이 자동 JSON Schema 변환. snake_case, 동사 시작(search_web, read_file) 권장.

5.2 입력 파라미터(Pydantic)

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색 키워드")
    max_results: int = Field(default=5)
    language: str = Field(default="ko")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """네트워크 검색 실행"""
    ...

5.3 실전 5대 도구

  1. 계산기: ast.literal_eval 안전 서브셋.
  2. 파일 R/W: 화이트리스트 디렉터리, 경로 탐색 방지.
  3. HTTP 요청: httpx로 외부 API 호출.
  4. DB 쿼리: 읽기 전용 SQL + 파라미터화. DDL 금지.
  5. 시간 도구: datetime.now(timezone.utc)·타임존 변환.

5.4 비동기 도구

@mcp.tool()
async def fetch_url(url: str) -> str:
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        response.raise_for_status()
        return response.text

5.5 에러 처리 베스트 프랙티스

  • 비즈니스 에러는 {"error": "...", "code": 404} 구조화 JSON 반환.
  • 외부 호출 타임아웃 30초 이내.
  • 파일/DB 최소 권한 검증.

6. Resources: 동적 콘텐츠 읽기

6.1 Resource vs Tool

Resource=데이터 제공, Tool=액션 실행. AI는 URI로 Resource를 읽고 부작용 없음.

6.2 정적·동적 리소스

@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:
    return json.dumps(db.query_user(user_id))

6.3 리소스 타입·파일시스템 서버

  • 텍스트: text/plain, application/json
  • 바이너리: 이미지, PDF(Base64/Blob URI)
  • 스트리밍: SSE 실시간 데이터

실전 패턴: 디렉터리 목록 → 파일 읽기 → watchfiles 변경 감지. 루트 화이트리스트 필수.

7. Prompts: 재사용 프롬프트 템플릿

7.1 MCP Prompt란

사전 정의 프롬프트 조각. AI 클라이언트가 직접 재사용. 동적 파라미터 주입으로 팀 일관성·유지보수성 향상.

7.2 템플릿 생성

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [PromptMessage(role="user", content=TextContent(
        type="text",
        text=f"다음 {language} 코드 리뷰: 품질·버그·보안·성능\n```{language}\n{code}\n```"
    ))]

7.3 멀티턴 프롬프트

user/assistant 멀티턴 템플릿으로 면접 시뮬·디버그 어시스턴트 구현. Client가 순서대로 대화 컨텍스트에 주입.

8. HTTP 전송 모드: 원격 MCP Server

8.1 stdio vs HTTP+SSE

특성 stdio HTTP + SSE
배포 로컬 자식 프로세스 원격 서버
지연 <1ms 10–200ms(네트워크)
다중 클라이언트 미지원 지원
시나리오 로컬 개발·개인 도구 SaaS·팀 공유·7×24

8.2 HTTP 구현·인증

mcp = FastMCP("remote-server", transport="streamable-http")
mcp.run(host="0.0.0.0", port=8000)
  • Bearer Token: Authorization: Bearer <token>
  • API Key 미들웨어 + IP 화이트리스트
  • CORS: 신뢰 Origin만
  • 레이트 리밋: 초당 10회 tools/call

9. 디버깅·테스트·흔한 오류

9.1 Inspector 4단계

  1. npx @modelcontextprotocol/inspector python server.py
  2. Tools/Resources/Prompts 목록 확인
  3. tools/call 수동 트리거·JSON 검증
  4. 타임아웃·불법 파라미터 시뮬레이션

9.2 단위 테스트

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 result.content[0].text == "4"

9.3 오류 대응 매트릭스

현상 원인 해결
도구 미표시 경로 오류·Client 미재시작 절대 경로 확인·Cursor/Claude 재시작
JSON 직렬화 실패 datetime 등 비지원 타입 str/dict 변환
타임아웃 Client 기본 한도 초과 async+timeout·장작업 분할
권한 거부 화이트리스트 외 경로 허용 루트 디렉터리 설정

10. 프로덕션 배포: Docker·클라우드·모니터링

10.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"]

10.2 2026 클라우드 옵션

  • Railway/Render: 원클릭. 개인 프로젝트($5–20/월).
  • Lambda/Cloud Run: 서버리스·호출 과금.
  • 자체 VPS/원격 Mac: Nginx + launchd. Apple 생태·7×24 Agent에 최적.

10.3 관측성·버전 관리

  • 구조화 로그: tool명·소요·상태코드
  • Prometheus: 호출수·P99·에러율
  • Sentry: 미처리 예외
  • GET /health 200 + 프로토콜 버전

업그레이드는 하위 호환——필수 필드 삭제 대신 옵션 파라미터 추가. 메이저 변경 시 v1/v2 병행·능력 협상.

11. 실전: 개인 지식베이스 MCP Server

11.1 요구사항·기술 스택

  • 로컬 Markdown 노트 검색·시맨틱 검색(벡터)·생성/갱신
  • 벡터 DB: ChromaDB/Qdrant(임베디드·제로옵스)
  • 임베딩: text-embedding-3-small 또는 nomic-embed-text
  • 파일 감시: watchfiles 자동 인덱스 재구축

11.2 핵심 도구 4종

  1. index_notes: 스캔·청크·임베딩·벡터 DB 기록
  2. search_notes: 시맨틱 Top-K + 소스 경로
  3. write_note: Markdown 생성/추가(화이트리스트 내)
  4. notes://{path} Resource: 전문 읽기

11.3 효과

Cursor에서 「지난주 MCP 관련 노트?」→ search_notes 호출·관련 스니펫 반환. 전체 노트를 Context에 넣는 것보다 Token 90%+ 절약, 실시간 갱신 지원.

12. MCP 생태계와 2026 트렌드

12.1 추천 Server

  • mcp-server-filesystem·github·brave-search·postgres·slack

공식: modelcontextprotocol.io · Python SDK: python-sdk · TS SDK: typescript-sdk

12.2 2026 트렌드

  • 빅4 AI 클라이언트 MCP 네이티브 지원 완료
  • MCP Marketplace·AAIF 품질 인증 가속
  • 엔터프라이즈: OAuth 2.1·세분화 Tool 권한·감사 로그

12.3 다음 학습 경로

13. 요약: 로컬 실험에서 7×24 프로덕션 노드까지

프로토콜 원리 → 환경 → Hello World → Tools/Resources/Prompts → HTTP → Inspector → Docker → 지식베이스 실전까지 MCP Server 개발 전체 체인을 다뤘습니다. MCP는 2026 AI 엔지니어 필수 표준 프로토콜입니다.

로컬 stdio 한계: 노트북 뚜껑 닫으면 끊김, 벡터 DB·임베딩이 로컬 메모리 점유, 다중 Server CPU 경합. 지식베이스 MCP·HTTP 원격 Server·ChromaDB+임베딩 API 장세션은 상시 온라인 Apple Silicon 노드가 안정적——통합 메모리가 벡터 검색에 유리, macOS는 launchd·Cursor/Claude 동형 툴체인 네이티브.

SFTPMAC 원격 Mac 임대는 MCP Server·AI Agent 워크플로용 7×24 Apple Silicon 환경을 제공합니다. 저지연 HTTP+SSE, 네이티브 Python/Node, SFTP/rsync로 노트·설정 동기화. 「집 PC 겸 MCP 호스트」보다 개인 지식베이스·팀 도구 계층을 프로덕션 엔트리로 운영하기에 적합합니다. MCP로 어떤 도구를 만들까요? Hello World부터 오늘 바로 시작하세요.