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 클라이언트”의 조합을 강력히 추천드립니다.