FastAPI‑MCP(FastApiMCP) LLM, MCP 통합 플랫폼 – FastAPI 엔드포인트를 Model Context Protocol(MCP) 도구로 자동 노출 라이브러리

fastapi‑mcp란 무엇인가?

FastAPI‑MCP는 FastAPI 앱의 모든 엔드포인트를 Model Context Protocol(MCP) 도구로 자동 노출해주는 라이브러리입니다.

  • zero‑config 방식: FastApiMCP(app).mount() 한 줄이면 /mcp 경로에 자동으로 MCP 서버가 세팅됩니다.
  • OpenAPI 스키마 기반으로 엔드포인트의 요청/응답 형태, docstring 등 정보를 그대로 유지합니다 (FastAPI MCP).
  • 내부의 FastAPI 종속성 주입(Dependency‑Inject)이나 인증 로직도 자연스럽게 통합되어 안심하고 사용 가능합니다 (GitHub).
  • ASGI transport 사용: HTTP 요청 없이도 비동기 내부 호출이 가능합니다.

즉, 개발 중인 API를 LLM 또는 AI 에이전트의 도구로 바로 연결할 수 있는 브릿지라고 보면 됩니다.

FastAPI와의 문법 차이점

FastAPI 예시

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class Item(BaseModel):
    name: str
    qty: int

@app.post("/items/", operation_id="create_item")
async def create(item: Item):
    return {"msg": f"Received {item.qty}x {item.name}"}

FastAPI는 경로, HTTP 메서드, Pydantic 모델, 의존성(Depends)를 중심으로 API를 설계합니다.

fastapi‑mcp 핵심 문법

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()
FastApiMCP(app).mount()  # 한 줄로 MCP 서버 추가
  • mount(): FastAPI 앱에 /mcp 엔드포인트 추가.
  • 도구 이름은 FastAPI의 operation_id를 따른다는 점 유의 필요 (Apidog, PyPI).
  • 기본 설정만으로도 사용 가능, 커스터마이징 옵션도 많습니다:
FastApiMCP(
    app,
    name="My MCP",
    describe_all_responses=True,
    describe_full_response_schema=True,
    include_operations=["create_item"],
    exclude_tags=["internal"]
).mount()
  • 필요한 엔드포인트만 노출하거나 응답 문서 설명 수준을 조절할 수 있습니다 .
  • 인증은 FastAPI 의존성 주입 방식 그대로 사용됩니다 .
항목 FastAPI fastapi‑mcp
엔드포인트 정의 경로, HTTP 메서드 중심 기존 FastAPI 엔드포인트 재활용
도구 등록 HTTP + FastAPI MCP 도구로 자동 등록
요청/응답 유효성 Pydantic + OpenAPI 자동 API 스펙 반영
인증 방식 Depends 등 FastAPI 방식 그대로 지원
호출 방식 HTTP 호출 ASGI 내부 호출, optional HTTP (GitHub, fastapi.tiangolo.com)

 

fastapi-mcp로 할 수 있는 일

fastapi-mcp는 단순히 FastAPI 앱을 MCP 서버로 만들어 주는 것 이상으로, 실제로 LLM 에이전트와의 연동을 위한 강력한 도구화 프레임워크로 작동합니다. 아래는 이를 통해 할 수 있는 핵심 기능들입니다.

기존 FastAPI API를 LLM 도구로 자동 노출

기존의 FastAPI 앱이 이미 있다면, 별도 변경 없이 MCP 도구로 연결할 수 있습니다.

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

app = FastAPI()

@app.post("/process", operation_id="process_data")
def process(data: dict):
    return {"result": data["value"] * 2}

FastApiMCP(app).mount()

이 예시는 /process API를 **MCP 도구 process_data**로 자동 노출합니다. Claude, Cursor 등의 LLM 도구 클라이언트에서 바로 사용할 수 있습니다.

Pydantic 스키마 그대로 유지

요청/응답 스키마는 FastAPI와 동일하게 Pydantic 기반이며, MCP 도구 설명으로 그대로 반영됩니다. 예를 들어:

from pydantic import BaseModel

class Input(BaseModel):
    value: int

@app.post("/double", operation_id="double_value")
def double(input: Input):
    return {"result": input.value * 2}

이렇게 하면 LLM 도구 인터페이스에도 value라는 숫자 입력 필드와 result라는 출력 필드가 그대로 반영되어 보여집니다.

인증 및 사용자 권한 제어

FastAPI의 Depends(...) 인증 시스템과 완전히 호환됩니다. 예를 들어:

from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
from fastapi import Depends, HTTPException

auth = HTTPBearer()

def verify_token(credentials: HTTPAuthorizationCredentials = Depends(auth)):
    if credentials.credentials != "secret":
        raise HTTPException(status_code=403, detail="Forbidden")
    return True

@app.get("/secure", operation_id="secure_tool", dependencies=[Depends(verify_token)])
def secure_tool():
    return {"msg": "Authorized access"}

MCP 클라이언트가 이 도구를 사용하려면 적절한 인증 헤더를 포함해야 합니다. LLM도 권한이 있어야 호출할 수 있는 도구만 접근 가능합니다.

노출 도구 필터링

특정 도구만 노출하거나 특정 태그는 제외할 수 있습니다.

FastApiMCP(
    app,
    include_operations=["translate_text"],
    exclude_tags=["internal"],
).mount()

이렇게 하면 translate_text라는 도구만 외부에 보이고, internal 태그가 붙은 API는 MCP에서 감춰집니다.

커스텀 도구 직접 추가

기존 FastAPI API 외에도 MCP 도구를 코드로 직접 등록할 수 있습니다.

from fastapi_mcp import FastApiMCP

mcp = FastApiMCP(app)

@mcp.tool()
def hello_world(name: str) -> str:
    return f"Hello, {name}!"

mcp.mount()

이렇게 등록한 MCP 도구는 OpenAPI에 나타나지 않지만, LLM 클라이언트에선 hello_world 도구로 호출 가능합니다. 특히 기존 시스템과 LLM만의 전용 기능을 분리하고 싶을 때 유용합니다.

분리된 앱 또는 경로로 MCP 서버 배포

MCP 서버를 원래 FastAPI 앱과 별도의 서브앱으로 마운트할 수 있습니다. 예를 들어:

from fastapi import FastAPI
from fastapi_mcp import FastApiMCP

api_app = FastAPI()
mcp_app = FastAPI()

FastApiMCP(mcp_app).mount()

main_app = FastAPI()
main_app.mount("/api", api_app)
main_app.mount("/mcp", mcp_app)

이 구조는 보안이나 서비스 분리 목적에서 실무적으로 매우 유용합니다.

Claude MCP, OpenAI MCP와의 비교

fastapi‑mcp는 MCP 서버 역할에 특화되어 있고, Claude MCP/OpenAI MCP는 MCP 클라이언트 또는 에이전트 역할에 더 가깝습니다.

기능 fastapi‑mcp Claude MCP / OpenAI MCP
역할 FastAPI 앱 → MCP 서버 LLM/Agent → MCP 클라이언트
목적 API를 LLM 도구로 노출 외부 도구 호출을 통한 작업 수행
사용 예 FastApiMCP(app).mount() client.call_tool("name")
통신 방식 ASGI/SSE 내부 호출 SSE 또는 stdio via mcp-proxy 연결
인증 방식 FastAPI dependency 클라이언트 설정 및 인증 키
유연성 Pydantic/OpenAPI 유지 도구 호출 → LLM 응답 처리

즉, fastapi‑mcp는 서버 측 구조를 담당하며, Claude나 OpenAI MCP는 클라이언트 측 에이전트 구동에 주로 사용됩니다.

정리 및 사용 팁

operation_id를 명확하게 설정하세요

도구 이름은 operation_id로 정해집니다. API 엔드포인트 이름을 자동으로 추론할 수도 있지만, 명확한 ID를 직접 주는 것이 좋습니다.

@app.post("/summarize", operation_id="summarize_text")
def summarize(input: InputText):
    ...

이점: LLM 클라이언트에서 summarize_text라는 이름이 도구로 명확하게 인식됩니다. 문서 자동화 도구에서도 좋습니다.

인증은 FastAPI 방식 그대로 활용하세요

LLM이 도구를 호출할 때에도 API 인증을 요구할 수 있습니다. 예를 들어 Claude Desktop 같은 앱에서 Authorization: Bearer <token> 헤더를 붙이면 인증 로직을 그대로 활용할 수 있습니다.

def get_user(token: str = Depends(auth_scheme)):
    return decode_token(token)

불필요한 도구는 꼭 필터링하세요

MCP는 외부 호출을 전제로 하므로, 내부용 엔드포인트는 MCP에서 제외하는 것이 보안상 좋습니다.

FastApiMCP(
    app,
    exclude_tags=["admin", "private"],
    include_operations=["public_tool"]
).mount()

MCP Inspector 또는 Claude에서 실제로 테스트하세요

로컬에서 MCP 서버를 띄우고 Claude Desktop 앱을 사용해 도구를 클릭하고 테스트해보면 가장 직관적입니다. 또 다른 방법은 mcp dev app.py 명령어로 MCP 개발 서버를 실행하는 것입니다 (MCP Python SDK 설치 필요).

내부 도구 또는 외부 MCP 서버와 조합하세요

  • 하나의 LangGraph 또는 MCP 서버에서 외부 MCP 서버의 도구도 호출할 수 있습니다 (mcp.Client()).
  • 이를 통해 마스터 MCP 서버 → 서브 MCP 서버의 Agent-to-Agent 구조도 구축할 수 있습니다.

이러한 실전 팁을 잘 활용하면, fastapi-mcp는 단순한 API 도구화를 넘어선 강력한 LLM 통합 플랫폼 역할을 하게 됩니다. 다음 글에서는 이를 기반으로 LangGraph, Claude, Ollama 등과 통합하여 에이전트 네트워크 전체를 만드는 법도 소개해 보겠습니다^^

끝맺음

fastapi‑mcp는 FastAPI 기반 API를 즉시 LLM 도구화할 수 있는 혁신적인 솔루션입니다. 최소한의 설정으로 자동 도구 노출, 완전한 스키마 보존, 인증·배포 설정까지 포함되어 있어 MCP 도구화의 표준 툴로 자리 잡고 있습니다.

Claude, OpenAI 클라이언트는 이 도구들을 활용해 작업하는 주체로, fastapi‑mcp는 그 기반을 제공하는 서버 사이드 구성 요소입니다. LLM 에이전트 환경을 구축하고자 한다면, “fastapi‑mcp + LLM 클라이언트”의 조합을 강력히 추천드립니다.

Claude MCP를 활용한 RAG 애플리케이션 – LangChain과 LangGraph 통합 전략

생성형 AI 문서 파싱 최신 트렌드와 오픈소스 솔루션 가이드 2025

Leave a Comment