FastMCP란? Python 함수가 MCP 서버가 되는 과정
FastMCP는 평범한 Python 함수를 모델 컨텍스트 프로토콜(Model Context Protocol, MCP) 서버의 도구로 바꿔 주는 프레임워크입니다. 함수에 데코레이터를 붙이면 입력 스키마 생성, 값 검증, 프로토콜 통신 같은 반복 작업을 맡아 주므로 개발자는 실제 기능에 집중할 수 있습니다. 다만 서버를 쉽게 만드는 것과 안전하게 운영하는 것은 다른 문제라서 인증·권한·배포 설계는 따로 챙겨야 합니다.
30초 요약
- FastMCP는 Python 함수·데이터·메시지 템플릿을 MCP의 도구·리소스·프롬프트로 노출합니다.
- 설치는
uv add fastmcp가 권장되며pip install fastmcp도 지원합니다.- 로컬 연동은 기본 STDIO, 네트워크 서비스는 Streamable HTTP가 알맞습니다.
- 2026년 9월 9일 확인 기준 최신 안정판은 v4.0.3이며, v4는 MCP 2026-07-28 사양과 Python SDK v2를 토대로 바뀌었습니다.
- 자동 스키마가 권한 통제까지 대신하지는 않으며, 운영에서는 정확한 버전 고정과 업그레이드 검토가 필요합니다.
FastMCP는 MCP에서 무슨 일을 하나요?
MCP는 대규모 언어 모델(LLM) 애플리케이션과 외부 데이터·도구를 일정한 방식으로 연결하는 공개 프로토콜입니다. 공식 사양은 호스트, 클라이언트, 서버가 JSON-RPC 2.0 메시지로 통신하도록 정의합니다.
FastMCP는 MCP 애플리케이션을 Python으로 만드는 상위 프레임워크입니다. 프로토콜 자체를 대체하지 않고, 개발자가 매번 작성해야 할 스키마·검증·전송·수명주기 코드를 감싸 줍니다.
식당에 비유하면 MCP는 주문서를 주고받는 규칙이고, FastMCP는 주방의 Python 함수를 그 주문서에 맞는 메뉴로 정리하는 매니저에 가깝습니다. 메뉴 이름과 재료 표기는 자동화해도, 누가 주방에 들어갈 수 있는지까지 저절로 정해지지는 않습니다.
FastMCP 서버가 내놓는 핵심 구성 요소는 세 가지입니다.
| 구성 요소 | 하는 일 | 간단한 예 |
|---|---|---|
| Tool | 클라이언트가 실행하는 함수 | 두 수 더하기, API 호출 |
| Resource | 클라이언트가 읽는 데이터 | 설정값, 문서 내용 |
| Prompt | 재사용할 메시지 템플릿 | 분석 요청 형식 |
Python 함수는 어떻게 MCP 도구가 되나요?
핵심은 함수의 타입 힌트와 설명입니다. @mcp.tool로 함수를 등록하면 FastMCP가 매개변수와 반환형을 읽어 도구 스키마를 만들고, 클라이언트가 보낸 값을 검증한 뒤 함수를 호출합니다.
흐름을 줄이면 다음과 같습니다.
- 개발자가
greet(name: str)같은 Python 함수를 작성합니다. - FastMCP가 함수 이름, 매개변수 타입, 설명에서 도구 정의를 만듭니다.
- MCP 클라이언트가
greet와{"name": "Mina"}를 보냅니다. - 서버가 입력을 검증하고 함수를 실행한 뒤 결과를 MCP 응답으로 돌려줍니다.
덕분에 기능 하나를 공개할 때마다 JSON Schema와 JSON-RPC 처리 코드를 손으로 맞추는 일이 줄어듭니다. 반대로 함수 이름과 타입 힌트가 부정확하면 모델과 클라이언트도 도구를 잘못 이해할 수 있으니, 짧더라도 설명과 타입은 명확해야 합니다.
설치하고 최소 서버를 만드는 순서는?
공식 저장소 main 브랜치 설정은 Python 3.10 이상을 요구합니다. 새 프로젝트라면 FastMCP 문서가 권장하는 uv로 추가하고, 설치된 버전을 바로 확인하는 편이 단순합니다.
uv add fastmcp
fastmcp version
pip를 쓰는 환경이라면 아래처럼 설치할 수 있습니다.
pip install fastmcp
fastmcp version
다음 코드는 공식 Quickstart를 바탕으로 단순화한 문서 기반 예제입니다. 이 글을 만들면서 패키지를 설치하거나 서버를 실행한 결과는 아닙니다.
from fastmcp import FastMCP
mcp = FastMCP("Greeting Server")
@mcp.tool
def greet(name: str) -> str:
"""이름을 받아 인사말을 반환합니다."""
return f"Hello, {name}!"
if __name__ == "__main__":
mcp.run()
python my_server.py로 실행하면 기본 전송은 STDIO(Standard Input/Output)입니다. 데스크톱 앱이나 CLI가 서버 프로세스를 직접 띄우는 로컬 연동에 잘 맞습니다.
같은 서버를 네트워크에서 호출하려면 실행부를 HTTP로 바꿀 수 있습니다.
if __name__ == "__main__":
mcp.run(transport="http", host="127.0.0.1", port=8000)
FastMCP CLI로 소스 변경 없이 전송 방식을 고르는 방법도 있습니다.
fastmcp run my_server.py:mcp --transport http --port 8000
입력과 출력은 실제로 어떻게 이어지나요?
HTTP 서버가 http://localhost:8000/mcp에서 실행 중이라는 전제로, 공식 Quickstart의 클라이언트 형태는 아래와 같습니다. FastMCP 클라이언트는 비동기 방식이므로 연결 컨텍스트 안에서 도구를 호출합니다.
import asyncio
from fastmcp import Client
client = Client("http://localhost:8000/mcp")
async def main() -> None:
async with client:
result = await client.call_tool(
"greet",
{"name": "Mina"},
)
print(result)
asyncio.run(main())
문서상 요청의 핵심 입력은 도구 이름 greet와 인자 {"name": "Mina"}입니다. 서버 함수가 만드는 핵심 텍스트는 Hello, Mina!이며, 클라이언트에서 출력되는 객체 모양은 설치 버전과 호출 API에 따라 감싸진 결과 형식으로 보일 수 있습니다.
여기서 확인해야 할 것은 출력 화면의 모양보다 경계입니다. 클라이언트는 Python 함수를 직접 부르는 대신 MCP 요청을 보내고, FastMCP가 그 요청을 함수 호출로 연결합니다.
STDIO와 HTTP 중 무엇을 골라야 하나요?
한 컴퓨터에서 개인용 도구를 붙인다면 기본 STDIO로 시작하는 편이 가볍습니다. 클라이언트가 서버 프로세스를 필요할 때 실행하고 수명주기도 함께 관리합니다.
여러 클라이언트가 네트워크로 접근하거나 중앙 서비스를 운영한다면 Streamable HTTP가 맞습니다. 기존 SSE(Server-Sent Events) 전송도 호환 목적으로 남아 있지만, 공식 문서는 새 프로젝트에 HTTP를 권장합니다.
| 상황 | 우선 선택 | 이유 |
|---|---|---|
| 로컬 CLI·데스크톱 연동 | STDIO | 별도 네트워크 서버 없이 프로세스 단위 연결 |
| 원격 서비스·다중 클라이언트 | Streamable HTTP | URL 접근과 웹 인프라 연동 |
| 오래된 클라이언트 유지 | SSE | 레거시 호환용이며 신규 권장 아님 |
HTTP로 바꾸는 순간 인증, 접근 통제, 비밀 관리, 로그와 장애 대응이 따라옵니다. host="0.0.0.0"으로 열기 전에 누가 어떤 도구를 호출할 수 있는지부터 정해야 합니다.
FastMCP 4의 최신 기능은 무엇인가요?
공식 GitHub Releases에서 2026년 9월 9일 확인한 최신 안정판은 v4.0.3이며 공개일은 2026년 9월 5일입니다. 문서 화면의 버전 배지는 main 브랜치 상태를 반영해 안정 릴리스와 어긋날 수 있으므로, 설치 버전 판단에는 Releases의 Latest 표시를 기준으로 삼았습니다.
큰 변화는 2026년 8월 31일 나온 v4.0.0에 들어 있습니다. FastMCP 4는 MCP 2026-07-28 사양과 MCP Python SDK v2를 기반으로 하며, 새 클라이언트와 구형 클라이언트가 각 연결에서 맞는 프로토콜 버전을 협상하도록 설계됐습니다.
릴리스 노트에서 초보 개발자가 먼저 볼 변화는 다음과 같습니다.
- interactive tools는 실행 도중 필요한 입력이나 승인을 요청하고 답을 받아 다시 진행하는 흐름을 지원합니다.
- background tasks는 선택 패키지
fastmcp-tasks의 확장으로 분리됐습니다. ClientGroup은 여러 서버의 클라이언트를 관리하며 이름 충돌을 검사합니다.- 프롬프트와 리소스 템플릿 인자 자동 완성, 서버 응답 캐시 힌트, 역할 검사와 클라이언트 자격 증명 인증 같은 기능이 추가됐습니다.
- v4.0.3은 구형 백엔드가 섞인 다중 서버 클라이언트의 불필요한 재시도, 일부 출력 스키마와 이미지 중복, 작업 시간 직렬화 문제를 다듬은 패치입니다.
확장 기능은 클라이언트와 서버가 함께 지원하고 협상해야 동작합니다. 라이브러리에 기능이 있다는 사실만으로 현재 쓰는 호스트에서 바로 사용할 수 있다고 보면 곤란합니다.
FastMCP가 잘 맞는 경우와 아닌 경우는?
기존 Python 함수나 API를 AI 클라이언트에 빠르게 노출하고 싶거나, 도구·리소스·프롬프트를 한 프레임워크에서 관리하려는 팀에는 잘 맞습니다. 타입 힌트와 Pydantic 모델을 이미 쓰고 있다면 스키마와 검증을 연결하기도 수월합니다.
다른 언어가 중심이거나 MCP 메시지의 세부 동작을 직접 통제해야 한다면 공식 저수준 SDK가 더 나은 선택입니다. 함수 하나를 애플리케이션 내부에서만 부르면 된다면 MCP 서버 자체가 불필요합니다. 문 하나 열려고 안내 데스크부터 세울 필요는 없으니까요.
운영 전에는 편의성보다 아래 경계를 먼저 보세요.
- 버전: 공식 문서는 빠르게 바뀌므로 운영 의존성은
fastmcp==4.0.3처럼 정확히 고정하고 릴리스 노트를 확인합니다. - 업그레이드: v4는 Python 모델 필드를 camelCase에서 snake_case로 옮겼고, 일부 3.x API를 제거했습니다. 기존 프로젝트는 호환 경고와 제거 목록을 먼저 점검해야 합니다.
- 의존성: v4 업그레이드 문서는 Pydantic 2.12 이상과 서버 구성의 Starlette 1.0.1 이상 등 높아진 하한을 안내합니다. FastAPI를 함께 고정한 프로젝트는 의존성 충돌을 먼저 확인해야 합니다.
- 프로토콜 변화: 현대식 무상태 요청에서는 서버가 실행 중간에 클라이언트로 되돌아가 호출하는 방식에 제약이 있습니다. 기존
ctx.elicit()흐름과 서버 주도 sampling·roots 사용 코드는 마이그레이션 대상입니다. - 보안: 자동 입력 검증은 인증·인가가 아닙니다. MCP 도구는 외부 데이터 접근과 코드 실행 경로가 될 수 있으므로 사용자 동의, 최소 권한, 비밀 분리, 오류 정보 차단을 별도로 설계합니다.
어디서부터 시작하면 될까요?
처음에는 부작용 없는 함수 하나를 STDIO 도구로 등록해 보세요. 도구 목록, 정상 입력, 잘못된 입력까지 확인한 뒤 실제로 여러 사용자가 필요할 때만 HTTP·인증·관측성으로 넓히는 편이 문제를 찾기 쉽습니다.
기존 FastMCP 3 프로젝트라면 새 기능부터 붙이지 말고 공식 v4 업그레이드 문서를 먼저 대조하세요. 특히 제거된 API, httpx2 전환, snake_case 필드, background tasks 확장 분리를 확인한 뒤 테스트 환경에서 올리는 순서가 안전합니다.
핵심 정리: 다섯 가지 질문과 답
Q. FastMCP는 MCP 자체인가요?
아닙니다. MCP는 연결 규칙을 정의한 공개 프로토콜이고, FastMCP는 그 규칙에 맞는 서버·클라이언트·앱을 Python으로 만들기 쉽게 해 주는 프레임워크입니다.
Q. Python 함수가 어떻게 MCP 도구가 되나요?
함수에 @mcp.tool을 붙이면 FastMCP가 타입 힌트와 설명에서 스키마를 만들고, 입력 검증과 호출·응답 변환을 맡습니다.
Q. 처음에는 STDIO와 HTTP 중 무엇이 낫나요?
로컬 도구는 기본 STDIO로 시작하는 편이 단순합니다. 여러 클라이언트가 네트워크로 접근해야 할 때 Streamable HTTP와 인증·운영 설계를 함께 검토하세요.
Q. 확인일 기준 최신 안정판은 무엇인가요?
2026년 9월 9일 공식 GitHub Releases의 Latest 표시는 v4.0.3이며, 공개일은 2026년 9월 5일입니다. main 브랜치 문서와 배포 버전은 다를 수 있으므로 릴리스 페이지를 함께 확인해야 합니다.
Q. FastMCP가 보안까지 해결해 주나요?
아닙니다. 스키마와 값 검증은 줄여 주지만 사용자 동의, 인증·권한, 비밀 관리와 외부 공개 범위는 개발자가 별도로 설계해야 합니다.
공식 출처
'AI > AI 최신 기술' 카테고리의 다른 글
| Pollinations.AI 가이드, 무료 이미지 URL만 믿으면 왜 막힐까 (0) | 2026.09.09 |
|---|---|
| 맥 미니 24시간 서버, 정전 뒤에도 스스로 복구하게 설정하기 (0) | 2026.09.06 |
| im-not-ai 사용법: AI 글투를 세 경로로 다듬는 원리 (1) | 2026.09.05 |
댓글