software

Model Context Protocol (MCP): 포괄적인 기술 보고서

발행: (2025년 12월 3일 오후 01:43 GMT+9)
10 min read
원문: Dev.to

Source: Dev.to

Executive Summary

대규모 언어 모델(LLM)을 프로덕션 소프트웨어에 빠르게 통합하면서 중요한 상호운용성 병목 현상이 드러났습니다. 개발자들이 추론 엔진(예: Claude 3.5 Sonnet, GPT‑4o)과 사유 데이터 소스(PostgreSQL, Slack, GitHub) 사이의 간극을 메우려 할 때, 업계는 “N×M” 통합 문제에 직면합니다. 즉, 새로운 모델마다 모든 데이터 소스에 대한 고유 커넥터가 필요해 생태계가 파편화되고 취약해지는 것입니다. 2024년 말 Anthropic이 발표한 Model Context Protocol (MCP) 은 AI용 “USB‑C”로 부상하며, 지능과 데이터를 분리하는 표준화된 오픈소스 사양을 제시합니다.

이 보고서는 MCP 솔루션을 구현·배포·전파하기 위한 포괄적인 기술 자료입니다. JSON‑RPC 메시지 레이어의 이론적 구조부터 Python·TypeScript 구현 예시까지 MCP 서버 개발 전 과정을 다룹니다. 또한 Cloudflare Workers와 Google Cloud Run 같은 클라우드 네이티브 인프라에 대한 배포 전략과 에이전트 접근을 위한 엄격한 보안 프레임워크를 제시합니다. 더불어 기술 문서 플랫폼(Dev.to, Medium, Hashnode) 분석과 고충격 영상 시연을 제작하기 위한 구조화된 가이드를 포함해 팀원들이 출판 목표를 달성하도록 돕습니다.

1. The Architectural Paradigm of the Model Context Protocol

Model Context Protocol은 AI 시스템이 세상과 상호작용하는 방식을 근본적으로 바꿉니다. 기존에 “툴”을 프롬프트에 직접 주입하거나 독점적인 함수 호출 API를 통해 다루던 방식과 달리, MCP는 연결 방식을 표준화합니다.

1.1 The Interoperability Crisis: The N×M Problem

MCP가 등장하기 전, 통합 환경은 벤더 종속으로 정의되었습니다. OpenAI Assistant API용 “Chat with PDF” 툴을 만든 개발자는 동일한 툴을 Anthropic Claude나 Ollama에서 실행되는 로컬 Llama 3 모델에 쉽게 포팅할 수 없었습니다.

  • “N” 모델: 각 모델 제공업체(OpenAI, Google, Anthropic, Meta)가 자체 툴 스키마를 정의합니다.
  • “M” 데이터 소스: 각 데이터 소스(Salesforce, Zendesk, 로컬 파일)는 모델마다 맞춤형 어댑터가 필요합니다.

이러한 조합 폭발적인 유지보수 작업은 MCP가 제공하는 표준 인터페이스를 통해 해결됩니다. 하나의 MCP 서버가 범용 어댑터 역할을 하여, 리소스(데이터)와 툴(함수)을 어떤 MCP‑준수 클라이언트(Host)라도 발견하고 활용할 수 있는 형식으로 노출합니다.

1.2 Core Primitives: Resources, Prompts, and Tools

프로토콜은 에이전트 워크플로우의 다양한 요구를 충족시키는 세 가지 기본 원시 타입을 정의합니다.

PrimitiveFunctionAnalogyAgentic Use Case
Resources데이터를 읽기 전용으로 노출HTTP GET 또는 파일 읽기로그, 코드 파일, 데이터베이스 행 등에 LLM이 코드를 실행하지 않고 접근하도록 함
Prompts재사용 가능한 상호작용 템플릿슬래시 명령어 (/fix)복잡한 시스템 지시문을 미리 패키징 (예: “이 코드를 보안 취약점 관점에서 검토해줘”)
Tools실행 가능한 함수HTTP POST 또는 RPC 호출데이터베이스 수정, 이메일 전송, 계산 수행 등 LLM이 실제 작업을 수행하도록 함

1.3 The Transport Layer: JSON‑RPC 2.0

전송 계층에서는 MCP가 JSON‑RPC 2.0을 사용합니다. 이는 언어에 구애받지 않으며 사람이 읽기 쉬운 프로토콜입니다.

  • Statelessness: 각 요청에 메서드, 파라미터, ID 등 필요한 모든 컨텍스트가 포함됩니다.
  • Asynchrony: 비동기 메시지 전달을 지원해, 모델 추론이나 툴 실행에 시간이 많이 걸리는 경우에도 적합합니다.

MCP는 두 가지 전송 방식을 지원합니다.

  • Stdio (Standard Input/Output): 로컬 연결에 사용됩니다. Host가 Server를 서브프로세스로 실행해 프로세스 격리와 네트워크 지연이 전혀 없는 보안을 제공합니다. 이는 Claude Desktop 같은 데스크톱 클라이언트의 기본 방식입니다.
  • SSE (Server‑Sent Events) / HTTP: 원격 연결에 사용됩니다. Client는 서버‑to‑client 이벤트를 받기 위해 HTTP 연결을 맺고, client‑to‑server 요청은 HTTP POST로 전송합니다. 이를 통해 모델과 툴이 서로 다른 인프라에 배치된 클라우드 환경에서도 동작합니다.

2. Implementation Guide: Building an MCP Server in Python

이 섹션은 Python 구현을 담당하는 팀원을 위한 기술 기반을 제공합니다. “FastMCP로 고성능 MCP 서버 구축”이라는 기사 초안의 토대가 됩니다.

2.1 The Python Ecosystem and FastMCP

Python 생태계에서는 mcp SDK와, 특히 저수준 프로토콜 복잡성을 추상화해 주는 FastMCP 클래스를 활용합니다. FastMCP는 Python 타입 힌트를 이용해 프로토콜에 필요한 JSON 스키마를 자동으로 생성하므로, FastAPI와 유사한 개발 경험을 제공합니다.

2.2 Environment Setup

재현 가능한 환경을 위해 uv라는 최신 Python 패키지 매니저를 사용합니다. uv는 pip와 venv를 하나의 워크플로우로 통합합니다.

Step‑by‑Step Setup

mkdir mcp-calculator-py
cd mcp-calculator-py
uv init
uv add "mcp[cli]"

위 명령은 핵심 MCP 라이브러리와 디버깅에 필요한 CLI 도구를 설치합니다.

2.3 Developing a Calculator Server

아래 코드는 수학 연산을 제공하는 견고한 MCP 서버 예시입니다. @mcp.tool() 데코레이터와 docstring 파싱 활용 방법을 강조합니다.

File: server.py

from mcp.server.fastmcp import FastMCP
import math

# Initialize the FastMCP server with a descriptive name
mcp = FastMCP("Advanced-Calculator")

@mcp.tool()
def add(a: int, b: int) -> int:
    """
    Add two integers together.

    Args:
        a: The first integer.
        b: The second integer.
    """
    return a + b

@mcp.tool()
def calculate_bmi(weight_kg: float, height_m: float) -> float:
    """
    Calculate Body Mass Index (BMI).

    Args:
        weight_kg: Weight in kilograms.
        height_m: Height in meters.
    """
    if height_m  str:
    """
    Retrieve the calculation history (Static Resource Example).
    """
    return "No history available in this session."

if __name__ == "__main__":
    # The run method automatically selects the transport (stdio/sse)
    mcp.run()

Code Analysis

  • Decorator Magic: @mcp.tool()은 함수 시그니처를 검사해 필요한 파라미터를 정의하는 JSON 스키마를 생성하고, 툴을 서버에 등록합니다.
  • Docstrings: 설명문(예: “Calculate Body Mass Index”)은 LLM에 전달돼 모델이 언제 툴을 호출해야 할지 이해하도록 돕습니다.
  • Error Handling: ValueError를 발생시키면 SDK가 이를 잡아 표준화된 JSON‑RPC 오류 형태로 클라이언트에 반환하므로 서버가 크래시되지 않습니다.

2.4 Testing with the MCP Inspector

Claude와 같은 클라이언트에 연결하기 전에 개발자는 MCP Inspector를 이용해 기능을 검증해야 합니다.

mcp dev server.py

위 명령은 서버를 실행하고 웹 인터페이스(http://localhost:5173)를 엽니다. 이 인터페이스에서 개발자는:

  • 로드된 툴 목록을 확인한다.
  • 파라미터를 직접 입력(예: weight_kg=70, height_m=1.75)하고 툴을 실행한다.
  • 원시 JSON 로그를 살펴 스키마와 응답이 올바른지 검증한다.
Back to Blog

관련 글

더 보기 »