홈 / 학습 코스 / MCP 심화 안내서
L3 심화

MCP 심화 안내서

모델·도구를 잇는 표준 프로토콜 MCP를 깊이 있게.

28챕터
1부(部)
4시간총 분량
첫 챕터 시작 →

챕터

01왜 MCP인가 — M×N 통합 문제와 해법 02핵심 구성요소: Host · Client · Server 03다른 접근과의 비교, 그리고 생태계 04JSON-RPC 2.0 위에서 — 메시지 구조 05초기화 핸드셰이크와 capability 협상 06버전(날짜 리비전)과 버전 협상, 생명주기 07stdio — 로컬의 기본 08Streamable HTTP — 원격의 표준 09무엇을 언제 쓰나 + 구(舊) SSE 호환 10Tools — 모델이 호출하는 행동 11Resources — 읽을 수 있는 데이터/컨텍스트 12Prompts — 재사용 프롬프트 템플릿 13알림·구독·로깅 등 부가 기능 14첫 서버: FastMCP로 처음부터 15도구/리소스/프롬프트 등록과 입력 스키마·검증 16에러 처리·로깅·테스트와 Inspector 디버깅 17클라이언트가 서버를 발견·연결·사용하는 법 18호스트 통합과 컨텍스트 비용, 여러 서버 다루기 19원격 서버 인증 (OAuth 2.1 기반) 20권한·동의·human-in-the-loop 21공격 표면: 프롬프트 주입·도구 중독·혼동된 대리인·공급망 22패키징·배포·버전 관리 23원격 호스팅·관측성·레이트리밋·성능 24테스트 전략과 실제 사례 패턴 ·부록 A. JSON-RPC 메서드 치트시트 ·부록 B. Python SDK 빠른 참조 ·부록 C. 용어집 · 디버깅 체크리스트 · 추가 학습 링크 ·부록 D. 기초 기술 용어 사전

개요

MCP(Model Context Protocol) 를 소비자로 써본 개발자가, 프로토콜의 동작 원리를 이해하고 자기 서버·클라이언트를 직접 설계·구현·배포·운영하는 데까지 나아가기 위한 학습 안내서입니다.

이 안내서가 기준으로 삼는 버전

기술이 빠르게 바뀌는 영역이라, 변할 수 있는 사실은 모두 공식 출처(스펙 사이트·공식 SDK 저장소)를 확인해 작성했습니다. 본문에서 버전에 따라 달라지는 내용은 그때그때 명시합니다.

대상기준 버전비고
프로토콜 스펙 리비전2025-11-25 (안정/Latest)1주년 릴리스. OAuth 강화·elicitation·sampling tool calling 등 포함
다음 리비전2026-07-28 (RC, 초안)아직 확정 전 — 단정하지 않음
Python 공식 SDKmcp 1.28.xFastMCP 1.0을 내장. from mcp.server.fastmcp import FastMCP
standalone FastMCPfastmcp 3.4.x별도 프로젝트(from fastmcp import FastMCP). 공식 SDK와 다름 — 본문에서 구분
디버깅 도구MCP Inspector공식 인스펙터
⚠️ 흔한 실수
가장 자주 바뀌는 두 영역은 전송 방식(transport) 과 인증(auth) 입니다. 이 안내서의 코드를 실제로 돌리기 전에 공식 스펙과 사용하는 SDK 버전의 릴리스 노트를 꼭 한 번 확인하세요.
📌 핵심
Python 두 갈래 주의: "FastMCP"라는 이름이 두 곳에서 쓰입니다. 하나는 공식 mcp 패키지에 들어간 버전, 다른 하나는 Prefect가 유지하는 standalone fastmcp 3.x입니다. import 경로(mcp.server.fastmcp vs fastmcp)와 API가 다를 수 있으니, 코드 예시마다 어느 쪽인지 표시합니다. 이 안내서의 기본은 공식 mcp SDK 내장 FastMCP이며, standalone이 유리한 지점에서는 따로 언급합니다.

MCP 한눈에 보기

flowchart LR
    subgraph HOST["호스트 애플리케이션 (예: Claude Desktop, IDE)"]
        LLM["LLM"]
        C1["MCP Client A"]
        C2["MCP Client B"]
    end
    S1["MCP Server\n(파일시스템)"]
    S2["MCP Server\n(DB·API)"]
    DATA1[("로컬 파일")]
    DATA2[("외부 API·DB")]

    LLM --- C1
    LLM --- C2
    C1 <-->|"JSON-RPC 2.0\n(stdio)"| S1
    C2 <-->|"JSON-RPC 2.0\n(Streamable HTTP)"| S2
    S1 --- DATA1
    S2 --- DATA2

    classDef client fill:#fde68a,stroke:#b45309,color:#000;
    classDef server fill:#5eead4,stroke:#0f766e,color:#000;
    classDef data fill:#ddd6fe,stroke:#6d28d9,color:#000;
    classDef host fill:#fef3c7,stroke:#a16207,color:#000;
    class C1,C2 client;
    class S1,S2 server;
    class DATA1,DATA2 data;
    class LLM host;

호스트 안의 클라이언트가 각각 하나의 서버와 1:1로 연결되고, 서버는 외부 데이터·도구를 표준화된 형태로 노출합니다. 클라이언트와 서버는 JSON-RPC 2.0 메시지를 주고받으며, 그 메시지가 흐르는 통로가 전송 방식(stdio / Streamable HTTP) 입니다.

연결의 시작은 항상 초기화 핸드셰이크입니다:

sequenceDiagram
    participant C as Client
    participant S as Server
    C->>S: initialize (protocolVersion, capabilities, clientInfo)
    S-->>C: InitializeResult (protocolVersion, capabilities, serverInfo)
    C->>S: notifications/initialized
    Note over C,S: 이제 정상 동작 단계 — tools/list, tools/call 등
    C->>S: tools/list
    S-->>C: 도구 목록
    C->>S: tools/call (name, arguments)
    S-->>C: 결과

목차

1부 · MCP란 무엇인가

2부 · 프로토콜 기초

3부 · 전송 방식 (Transport)

4부 · 서버의 세 가지 핵심 능력

5부 · 서버 직접 만들기 (Python)

6부 · 클라이언트·호스트 관점

7부 · 인증과 보안

8부 · 실전과 배포

부록

이 안내서 활용법

  • 순서대로 읽는 것을 권합니다. 2부(프로토콜)와 3부(전송)를 이해해야 5부(서버 제작)의 코드가 "왜 그렇게 생겼는지" 보입니다.
  • 각 장은 목표 → 비유로 개념 도입 → 정확한 정의·동작 → 실제 메시지/코드 → 표·콜아웃 → 요약 → 확인 문제 순서입니다.
  • 콜아웃 기호: 💡 팁 · ⚠️ 흔한 실수 · 📌 핵심 · 🔒 보안.
  • 처음 보는 약어가 나오면 본문에 짧은 풀이를 달아 두었고, 한데 모은 부록 D. 기초 기술 용어 사전에서 JSON-RPC·OAuth·base64·PKCE 등을 입문자 눈높이로 찾아볼 수 있습니다. MCP 고유 용어는 부록 C에 있습니다.
  • 코드 예시는 Python 위주이며, 어느 SDK·어느 버전 기준인지 표시합니다. API 시그니처는 SDK 버전에 따라 달라질 수 있습니다.
▶ 시작하기: 01. 왜 MCP인가