MCP: FastMCP

https://gofastmcp.com/getting-started/welcome

1. MCP (Model Context Protocol) 란 무엇인가

MCP가 표준화하는 것

MCP(Model Context Protocol)는
LLM이 외부 시스템과 상호작용하는 방식을 표준화한 프로토콜이다.

구체적으로 MCP는 다음을 표준화한다.

• LLM이 사용할 수 있는 외부 기능의 정의 방식
• 해당 기능을 발견(discover) 하는 메커니즘
• 필요 시 기능을 호출(call) 하는 방식

“모델이 무엇을 할 수 있는지”를 서버가 선언하고, 클라이언트가 연결하며, 모델이 선택한다.

2. MCP 아키텍처 개요

구성 요소

구성	역할
MCP Server	Tool / Resource / Prompt를 노출
MCP Client	서버에 연결 (ChatGPT, IDE, Agent 등)
LLM	클라이언트를 통해 기능을 선택/호출

흐름

1. 서버가 제공 가능한 기능 메타데이터 노출

2. 클라이언트가 이를 수집

3. 모델이 필요에 따라 기능 선택

4. 클라이언트가 서버 호출

5. 결과를 모델에게 전달

3. MCP 3대 Primitive

MCP 서버는 3가지 Primitive만 제공한다.

3.1 Tool — 행동(Action)

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b

• 실행 가능한 함수

• 계산, 쓰기, 외부 API 호출 등 사이드 이펙트 허용

특징

• “무언가를 한다”

• 상태 변경 가능

• LLM이 행동을 취해야 할 때 사용

3.2 Resource — 데이터(Fact)

@mcp.resource("config://app/version")
def app_version() -> str:
    return "1.3.2"

• 모델이 읽을 수 있는 데이터 엔드포인트

• REST의 GET과 유사한 개념

특징

• 읽기 전용

• 무거운 계산 ❌

• 사이드 이펙트 ❌

• “사실을 조회한다”

URI 의미

• URI는 식별자

• 실제 네트워크 요청 아님

3.3 Prompt — 사고방식(Instruction)

@mcp.prompt(title="요약")
def summarize(text: str) -> str:
    return f"{text}를 3줄로 요약해라"

• 재사용 가능한 프롬프트 템플릿

• 클라이언트가 선택해서 사용

특징

• 모델이 직접 호출 ❌

• 사용자/클라이언트가 선택

• 팀 단위 프롬프트 표준화 가능

Python 정의 (구조화)

from mcp.types import PromptMessage

@mcp.prompt()
def review(code: str):
    return [
        PromptMessage(role="system", content="너는 시니어 리뷰어다"),
        PromptMessage(role="user", content=code),
    ]

4. FastMCP 핵심 구성요소

4.1 FastMCP

from mcp.server.fastmcp import FastMCP
mcp = FastMCP("example-server")

• MCP 서버의 핵심 클래스

• Tool / Resource / Prompt를 등록·관리

특징

• 타입 힌트 기반 자동 스키마 생성

• Discovery 메타데이터 자동 제공

4.2 Decorator

데코레이터	역할
@mcp.tool()	실행 함수 등록
@mcp.resource()	읽기 전용 데이터 등록
@mcp.prompt()	프롬프트 템플릿 등록

5. Context (런타임 제어 핵심)

Context란?

• Tool / Resource 실행 중에 주입되는 런타임 컨텍스트 객체

from mcp.server.fastmcp import Context

@mcp.tool()
def work(ctx: Context):
    ctx.info("작업 중")

Context로 할 수 있는 것

기능	설명
ctx.info()	진행 상황 전달
ctx.warning()	경고
ctx.error()	오류
ctx.log()	로그
세션 정보	요청 단위 상태

Agent UX에 매우 중요

6. Lifespan (서버 생명주기)

Lifespan이란?

• 서버 시작/종료 시 실행되는 훅

• 전역 리소스 관리 용도

  • DB 커넥션

  • Redis

  • 외부 SDK

실서비스면 사실상 필수

패턴

from contextlib import asynccontextmanager

@asynccontextmanager
async def lifespan(mcp: FastMCP):
    init_db()
    yield
    close_db()

7. Discovery (자동 발견)

MCP 서버는 다음을 자동으로 노출한다.

• Tools

• Resources

• Prompts

• 입력/출력 스키마

• 설명(docstring)

클라이언트는 이를 자동 수집 → 모델이 활용

• OpenAPI / Swagger와 매우 유사

8. Transport (연결 방식)

STDIO

• 로컬 실행

• ChatGPT Desktop / IDE 연동

python server.py

HTTP / SSE

• 원격 서버

• 멀티 클라이언트

FastMCP는 전송 계층과 로직을 분리

9. 에러 처리

Tool 내부 예외

@mcp.tool()
def risky():
    raise ValueError("잘못된 요청")

• 클라이언트 → 모델로 오류 전달

• Context 로그 병행 권장

10. 설계 원칙

• Tool = 행동

• Resource = 조회

• Prompt = 사고방식

• 하지 말 것

  • ❌ Resource에서 계산

  • ❌ Prompt에 비즈니스 로직

  • ❌ Tool에 프롬프트 하드코딩

  • ❌ 전역 상태 남용

• Tool → “한다”
• Resource → “읽는다”
• Prompt → “어떻게 생각한다”
• Context → “지금 상황”
• Lifespan → “서버의 생과 사”

11. 전형적인 프로젝트 구조

mcp_server/
 ├─ server.py
 ├─ tools/
 ├─ resources/
 ├─ prompts/
 └─ lifespan.py