FastAPI MCP 서버는 모델 컨텍스트 프로토콜(MCP)을 사용하여 FastAPI 애플리케이션과 AI 에이전트 간의 간극을 연결하는 혁신적인 도구입니다. AI 통합이 점점 더 중요해지고 있는 시대에, 이 제로 구성 솔루션은 기존의 FastAPI 엔드포인트를 AI 모델과 에이전트에 의해 최소한의 노력으로 발견되고 활용될 수 있는 도구로 노출할 수 있게 해줍니다.
FastAPI MCP 소개
모델 컨텍스트 프로토콜(MCP)은 AI 모델이 외부 도구 및 리소스와 상호 작용할 수 있게 해주는 새로운 표준입니다. FastAPI MCP 서버는 기존의 FastAPI 애플리케이션과 Anthropic의 Claude, Cursor IDE 및 기타와 같은 MCP 호환 AI 에이전트 간의 다리를 제공합니다. API를 다시 작성하거나 복잡한 새로운 프레임워크를 배울 필요 없이 말입니다.
FastAPI MCP의 진정한 장점은 제로 구성 접근 방식입니다. 이 솔루션은 기존의 FastAPI 엔드포인트를 MCP 호환 도구로 자동 변환하여 엔드포인트 스키마, 문서 및 기능을 그대로 유지합니다. 즉, AI 에이전트는 최소한의 설정으로 APIs를 발견하고 상호 작용할 수 있습니다.
FastAPI MCP 서버 리포지토리는 다음에서 확인할 수 있습니다: https://github.com/tadata-org/fastapi_mcp
FastAPI MCP 시작하기
설치
FastAPI MCP를 사용하기 전에 설치해야 합니다. 개발자들은 빠른 Python 패키지 설치기인 uv 사용을 권장하지만, 전통적인 pip 방법을 사용할 수도 있습니다:
uv 사용:
uv add fastapi-mcp
pip 사용:
pip install fastapi-mcp
기본 구현
기존 FastAPI 애플리케이션과 FastAPI MCP를 통합하는 것은 매우 간단합니다. 다음은 가장 기본적인 구현입니다:
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 기존 FastAPI 애플리케이션
app = FastAPI()
# MCP 서버 생성
mcp = FastApiMCP(
app,
name="내 API MCP",
description="내 API 설명",
base_url="http://localhost:8000" # 요청 라우팅에 중요
)
# FastAPI 앱에 MCP 서버 마운트
mcp.mount()
그것으로 끝입니다! 이 간단한 코드로 인해 당신의 MCP 서버는 이제 https://app.base.url/mcp에서 이용할 수 있습니다. MCP 호환 클라이언트가 이 엔드포인트에 연결하면, 모든 FastAPI 경로를 사용 가능한 도구로 자동으로 발견하게 됩니다.
MCP 도구 이름 및 운영 ID 이해하기
FastAPI MCP가 엔드포인트를 도구로 노출할 때, FastAPI 경로에서의 operation_id를 MCP 도구 이름으로 사용합니다. FastAPI는 명시적으로 제공되지 않은 경우 이러한 ID를 자동 생성하지만, 이들은 이해하기 어렵고 사용자 친화적이지 않을 수 있습니다.
이 두 가지 접근 방식을 비교해 보십시오:
# 자동 생성된 operation_id (덜 사용자 친화적)
@app.get("/users/{user_id}")
async def read_user(user_id: int):
return {"user_id": user_id}
# 명시적인 operation_id (더 사용자 친화적)
@app.get("/users/{user_id}", operation_id="get_user_info")
async def read_user(user_id: int):
return {"user_id": user_id}
첫 번째 예에서는 도구 이름이 "read_user_users__user_id__get"처럼 될 수 있지만, 두 번째 예에서는 단순히 "get_user_info"가 됩니다. AI 에이전트가 도구와 상호 작용할 때 더 나은 사용성을 위해 명확하고 설명적인 운영 ID를 명시적으로 정의하는 것이 좋습니다.
고급 구성 옵션
FastAPI MCP는 API가 MCP 클라이언트에 어떻게 노출되는지를 조정하기 위한 여러 사용자 정의 옵션을 제공합니다.
스키마 설명 사용자 정의
도구 설명에 포함되는 정보의 양을 제어할 수 있습니다:
mcp = FastApiMCP(
app,
name="내 API MCP",
base_url="http://localhost:8000",
describe_all_responses=True, # 가능한 모든 응답 스키마 포함
describe_full_response_schema=True # 전체 JSON 스키마 세부정보 포함
)
엔드포인트 필터링
어떤 엔드포인트가 MCP 도구로 노출될지 제어하고 싶을 수 있습니다. FastAPI MCP는 여러 필터링 메커니즘을 제공합니다:
# operation ID로 특정 작업만 포함
mcp = FastApiMCP(
app,
include_operations=["get_user", "create_user"]
)
# 특정 작업 제외
mcp = FastApiMCP(
app,
exclude_operations=["delete_user"]
)
# 태그별 필터
mcp = FastApiMCP(
app,
include_tags=["users", "public"]
)
# 태그별 제외
mcp = FastApiMCP(
app,
exclude_tags=["admin", "internal"]
)
# 필터링 전략 결합
mcp = FastApiMCP(
app,
include_operations=["user_login"],
include_tags=["public"]
)
같은 유형(작업 또는 태그)의 포함 및 제외 필터를 결합할 수는 없지만, 작업 필터를 태그 필터와 함께 사용할 수 있습니다.
배포 전략
FastAPI MCP는 MCP 서버를 배포하는 방법에 유연성을 제공합니다.
원래 애플리케이션에 마운트하기
가장 간단한 방법은 기본 예제에서 보여준 것처럼 MCP 서버를 원래 FastAPI 앱에 직접 마운트하는 것입니다. 이렇게 하면 기존 애플리케이션에 /mcp 엔드포인트가 생성됩니다.
별도의 서비스로 배포하기
하나의 FastAPI 앱에서 MCP 서버를 생성하고 다른 앱에 마운트하여 API 및 MCP 인터페이스를 별도로 배포할 수도 있습니다:
from fastapi import FastAPI
from fastapi_mcp import FastApiMCP
# 원래 API 앱
api_app = FastAPI()
# 엔드포인트를 여기 정의합니다...
# MCP 서버를 위한 별도의 앱
mcp_app = FastAPI()
# API 앱에서 MCP 서버 생성
mcp = FastApiMCP(
api_app,
base_url="http://api-host:8001" # API 앱이 실행되는 URL
)
# 별도의 앱에 MCP 서버 마운트
mcp.mount(mcp_app)
# 이제 두 앱을 별도로 실행합니다:
# uvicorn main:api_app --host api-host --port 8001
# uvicorn main:mcp_app --host mcp-host --port 8000
이 분리는 자원 관리, 보안 및 확장성 관리에 유용할 수 있습니다.
새로운 엔드포인트 추가 후 MCP 업데이트하기
MCP 서버를 생성한 후 FastAPI 앱에 엔드포인트를 추가하면 서버를 새로 고쳐야 새 엔드포인트를 포함할 수 있습니다:
# 초기 설정
app = FastAPI()
mcp = FastApiMCP(app)
mcp.mount()
# 나중에 새로운 엔드포인트 추가
@app.get("/new/endpoint/", operation_id="new_endpoint")
async def new_endpoint():
return {"message": "안녕하세요, 세상!"}
# 새로운 엔드포인트를 포함하기 위해 MCP 서버 새로 고침
mcp.setup_server()
MCP 서버에 연결하기
FastAPI 앱에 MCP 통합이 실행되고 나면 클라이언트는 여러 방법으로 연결할 수 있습니다.
서버 전송 이벤트(SSE) 사용하기
Cursor IDE와 같은 많은 MCP 클라이언트는 SSE 연결을 지원합니다:
- 애플리케이션 실행하기
- Cursor → 설정 → MCP에서 MCP 서버 엔드포인트의 URL(예:
http://localhost:8000/mcp)를 SSE URL로 사용 - Cursor는 사용 가능한 모든 도구와 리소스를 자동으로 발견합니다
SSE 지원이 없는 클라이언트를 위한 MCP 프록시 사용하기
SSE를 직접 지원하지 않는 클라이언트(예: Claude Desktop)의 경우:
- 애플리케이션 실행하기
- MCP 프록시 도구 설치:
uv tool install mcp-proxy - 클라이언트를 mcp-proxy를 사용하도록 구성하기
Windows의 Claude Desktop에서는 구성 파일(claude_desktop_config.json)을 생성합니다:
{
"mcpServers": {
"my-api-mcp-proxy": {
"command": "mcp-proxy",
"args": ["http://127.0.0.1:8000/mcp"]
}
}
}
macOS에서는 mcp-proxy 실행 파일의 전체 경로를 지정해야 하며, 이는 which mcp-proxy를 사용하여 찾을 수 있습니다.
실제 사용 사례
FastAPI MCP는 AI 기반 애플리케이션에 대한 수많은 가능성을 열어줍니다:
- 데이터 분석 도구: AI 에이전트가 사용자 데이터를 분석할 수 있도록 데이터 처리 엔드포인트를 노출시켜 각 AI 모델에 대한 맞춤형 통합이 필요하지 않게 합니다.
- 콘텐츠 관리 시스템: AI 도구가 기존 CMS API를 통해 콘텐츠를 가져오고 업데이트할 수 있도록 하여 콘텐츠 생성 및 관리를 더 효율적으로 만듭니다.
- 맞춤형 검색 엔진: AI 어시스턴트가 간단한 API 인터페이스를 통해 전문 데이터베이스 또는 콘텐츠 저장소를 검색할 수 있게 합니다.
- 전자상거래 운영: AI 에이전트가 기존 전자상거래 API 엔드포인트를 통해 재고, 제품 정보 확인 또는 주문을 할 수 있도록 합니다.
- 문서 처리: AI 도구에 백엔드 문서 처리 기능을 이용해 문서를 생성, 변환 또는 분석할 수 있는 기능을 제공합니다.
모범 사례
FastAPI MCP를 최대한 활용하기 위해 다음 모범 사례를 고려하십시오:
- 명확한 운영 ID 사용: 모든 엔드포인트에 대해 명확하고 설명적인 운영 ID를 정의하여 AI 에이전트가 더 쉽게 사용할 수 있도록 합니다.
- 포괄적인 문서 제공: 각 엔드포인트 및 매개변수에 대한 상세한 설명을 포함하여 AI 모델이 도구를 효과적으로 사용하는 데 도움을 줍니다.
- 일관된 매개변수 이름 사용: 서로 다른 엔드포인트 간 유사한 매개변수에 대해 일관된 명명 규칙을 채택합니다.
- 보안적 고려사항 생각하기: MCP를 통해 노출할 엔드포인트를 신중하게 판단하고 필요한 곳에 적절한 인증을 구현합니다.
- 사용 추적: AI 에이전트가 MCP 도구를 사용하는 방식을 추적하여 패턴, 오류 또는 개선이 필요한 부분을 식별합니다.
결론
FastAPI MCP 서버는 백엔드 서비스를 AI 에이전트가 접근할 수 있도록 하는 중요한 진전을 나타냅니다. 기존 FastAPI 엔드포인트를 제로 구성으로 MCP 호환 도구로 자동으로 변환하여, 맞춤형 통합이나 복잡한 API 디자인 조정의 필요성을 없앱니다.
MCP 생태계가 지속적으로 성장하고 더 많은 AI 모델이 이 표준을 수용하게 되면서, FastAPI MCP를 통해 API가 노출되는 것은 다양한 AI 에이전트와 도구가 귀하의 서비스에 쉽게 접근할 수 있도록 위치시킬 것입니다. 내부 도구, 개발자 서비스 또는 공개 API를 구축하든, FastAPI MCP는 귀하의 서비스를 AI 접근 가능하게 만드는 간단한 경로를 제공합니다.
이 문서에서 제시된 가이드를 따르면 기존 FastAPI 애플리케이션에 FastAPI MCP를 빠르게 통합하고 AI 기반 자동화 및 서비스와의 상호 작용 가능성을 탐색할 수 있습니다.