FastMCP 사용을 위한 초보자 가이드

대규모 언어 모델(LLM)의 환경은 빠르게 변화하고 있으며, 단순한 텍스트 생성에서 외부 시스템 및 데이터 소스와의 복잡한 상호작용으로 넘어가고 있습니다. 이러한 상호작용을 촉진하려면 표준화된 접근 방식이 필요하며, LLM이 정보를 요청하고 작업을 트리거하는 데 사용할 수 있는 공통 언어가 필요합니다. 여기에서 모델 컨텍스트 프로토콜(MCP)이 등장하며, 이는 보편적인 표준으로 설계되었습니다 - 종종 "AI를 위한 USB-C 포트"에 비유되며 - LLM과 필요한 자원 간의 원활한 통신을 가능하게 합니다.

MCP는 사양을 제공하지만, 이를 준수하는 서버와 클라이언트를 구축하는 데는 상당한 보일러플레이트 코드와 프로토콜 관리가 필요할 수 있습니다. 바로 여기에서 FastMCP의 장점이 빛을 발합니다. FastMCP는 MCP 서버와 클라이언트를 간단하게 생성할 수 있도록 설계된 고수준의 Pythonic 프레임워크입니다. 프로토콜의 기본 복잡성을 처리하여 개발자가 LLM에 노출할 가치 있는 도구, 데이터 리소스 및 상호작용 패턴을 정의하는 데 집중할 수 있습니다.

💡

아름다운 API 문서를 생성하는 훌륭한 API 테스트 도구가 필요하신가요?

최대 생산성으로 개발 팀이 협력할 수 있는 통합된 올인원 플랫폼이 필요하신가요?

Apidog은 귀하의 모든 요구를 충족시키며, 보다 저렴한 가격으로 Postman을 대체합니다!

버튼

모델 컨텍스트 프로토콜(MCP)란?

FastMCP에 대해 더 깊이 파고들기 전에 MCP 자체의 핵심 개념을 이해하는 것이 중요합니다. MCP는 LLM 애플리케이션(클라이언트)과 외부 시스템(서버) 간의 상호작용을 위한 표준화된 방법을 정의합니다. MCP 서버는 여러 주요 구성 요소를 노출할 수 있습니다:

도구: 이는 LLM이 서버에 실행을 요청할 수 있는 기본적인 기능입니다. 전통적인 API의 POST 엔드포인트와 비슷하게 생각할 수 있습니다. 작업을 수행하고, 다른 시스템(데이터베이스, API, 하드웨어)과 상호작용하며, 결과를 반환합니다. 예를 들어 도구는 이메일을 보내거나 데이터베이스를 쿼리하거나 계산을 수행할 수 있습니다.
리소스: 이는 LLM이 읽거나 검색할 수 있는 데이터를 노출합니다. GET 엔드포인트와 유사하게, 리소스는 LLM의 컨텍스트를 풍부하게 하는 정보를 제공합니다. 이는 구성 파일, 사용자 프로필에서 실시간 데이터 스트림에 이르기까지 다양할 수 있습니다.
프롬프트: 이는 LLM과의 상호작용 구조화에 대한 재사용 가능한 템플릿입니다. 대화를 안내하고 특정 작업에 대한 일관된 출력을 보장합니다.
컨텍스트: 서버는 사용 가능한 도구 및 리소스와 상호작용하는 방법에 대한 지침을 포함하여 맥락 정보를 제공할 수 있습니다.

MCP는 LLM이 외부 기능에 신뢰할 수 있게 접근하고 활용할 수 있는 강력하고 안전한 생태계를 만드는 것을 목표로 합니다.

왜 FastMCP를 선택해야 할까요?

MCP 사양을 저수준 SDK를 사용하여 직접 구현할 수 있지만, FastMCP는 특히 Python 개발자에게 매력적인 장점을 제공합니다:

🚀 빠른 개발: 높은 수준의 인터페이스는 필요한 코드의 양을 크게 줄여 개발 프로세스를 가속화합니다. 종종 도구나 리소스를 정의하는 것은 표준 Python 함수를 장식하는 것만큼 간단합니다.
🍀 단순성: FastMCP는 서버 설정, 프로토콜 처리, 콘텐츠 유형 및 오류 관리를 복잡하게 하는 세부적인 부분을 추상화하여 보일러플레이트를 최소화합니다.
🐍 Pythonic: Python의 모범 사례를 염두에 두고 설계되어 언어에 익숙한 개발자에게 자연스럽고 직관적입니다. 타입 힌트(type hints) 및 데코레이터(decorators)와 같은 기능을 활용합니다.
🔍 완전성: FastMCP는 핵심 MCP 사양의 포괄적인 구현을 제공하여 호환성과 프로토콜의 전체 잠재력에 대한 접근을 보장합니다.

FastMCP 버전 1은 매우 성공적이었으며 현재 공식 MCP Python SDK에 통합되어 있습니다. 버전 2는 이 기반 위에서 발전되어 서버 상호작용을 간소화하는 데 중점을 두고 유연한 클라이언트, 서버 프록시 및 조합 패턴과 같은 고급 기능을 도입합니다.

FastMCP 설치 방법

Python 환경에 FastMCP를 설정하는 것은 간단합니다. 권장 방법은 빠른 Python 패키지 설치 및 해결 도구인 uv를 사용하는 것입니다.

1. uv 사용(권장):

프로젝트의 종속성을 관리하는 경우, 다음과 같이 FastMCP를 추가합니다:

uv add fastmcp

또는 환경에 직접 설치할 수 있습니다:

uv pip install fastmcp

2. pip 사용:

pip을 사용하는 경우, FastMCP를 다음과 같이 설치할 수 있습니다:

pip install fastmcp

3. 설치 확인:

설치 후, FastMCP가 올바르게 설치되었는지 확인하고 버전, 기본 MCP SDK 버전 및 Python 환경 세부정보를 확인하려면 다음을 실행하십시오:

fastmcp version

다음과 유사한 출력을 볼 수 있어야 합니다:

$ fastmcp version

FastMCP버전:   0.4.2.dev41+ga077727.d20250410
MCP버전:                                1.6.0
Python버전:                            3.12.2
Platform:            macOS-15.3.1-arm64-arm-64bit
FastMCP 루트 경로:            ~/Developer/fastmcp

4. 개발을 위한 설치:

FastMCP 프로젝트에 기여할 의도가 있는 경우, 개발 환경을 설정해야 합니다:

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
uv sync

이 명령은 저장소를 클론하고, 디렉토리로 이동한 다음, uv sync를 사용하여 개발 도구를 포함한 모든 필요한 종속성을 가상 환경 내에서 설치합니다. 그런 다음 pytest를 사용하여 테스트를 실행할 수 있습니다.

FastMCP 사용 방법: 첫 번째 서버 빌딩

이제 FastMCP 사용의 실용적인 측면을 살펴보겠습니다.

1. 기본 서버 인스턴스 생성:

모든 FastMCP 애플리케이션의 핵심은 FastMCP 클래스입니다. 이 클래스를 인스턴스화 하여 시작합니다.

my_server.py라는 파일을 생성하십시오:

# my_server.py
from fastmcp import FastMCP
import asyncio # 클라이언트에 나중에 사용할 것입니다.

# 서버의 이름을 지정하여 인스턴스화합니다.
mcp = FastMCP(name="내 첫 MCP 서버")

print("FastMCP 서버 객체가 생성되었습니다.")

FastMCP 생성자는 유용한 여러 인수를 허용합니다:

name (str, 선택 사항): 서버에 대한 사람이 읽을 수 있는 이름(기본값은 "FastMCP"). 로그나 클라이언트 애플리케이션에서 식별하는 데 유용합니다.
instructions (str, 선택 사항): 클라이언트가 서버와 상호작용하는 방법에 대한 설명으로, 목적을 설명하거나 주요 기능을 강조합니다.
lifespan (callable, 선택 사항): 서버 시작 및 종료 논리를 처리하기 위한 비동기 컨텍스트 관리자(예: 데이터베이스 연결 초기화).
tags (set[str], 선택 사항): 서버를 분류하기 위한 태그입니다.
**settings: ServerSettings에 해당하는 키워드 인수를 생성자에 직접 전달하여 구성할 수 있습니다(예: port, host, log_level).

2. 구성 요소 추가:

비어있는 서버는 그다지 유용하지 않습니다. 핵심 MCP 구성 요소를 추가해 보겠습니다.

도구 추가: 도구는 클라이언트에 노출된 함수입니다. @mcp.tool() 데코레이터를 사용하십시오. FastMCP는 Python 타입 힌트를 사용하여 클라이언트를 위한 예상 입력 매개변수 및 반환 유형을 정의합니다.

# my_server.py (계속)
@mcp.tool()
def greet(name: str) -> str:
    """간단한 인사 말합니다."""
    return f"안녕하세요, {name}님!"

@mcp.tool()
def add(a: int, b: int) -> int:
    """두 수를 더합니다."""
    return a + b

print("도구 'greet'와 'add'가 추가되었습니다.")

리소스 추가: 리소스는 URI를 통해 데이터를 노출합니다. @mcp.resource() 데코레이터를 사용하고 URI 문자열을 제공하십시오.

# my_server.py (계속)
APP_CONFIG = {"theme": "dark", "version": "1.1", "feature_flags": ["new_dashboard"]}

@mcp.resource("data://config")
def get_config() -> dict:
    """애플리케이션 구성을 제공합니다."""
    return APP_CONFIG

print("리소스 'data://config'가 추가되었습니다.")

리소스 템플릿 추가: 이는 URI의 일부가 매개변수 역할을 하는 동적 리소스와 같습니다.

# my_server.py (계속)
USER_PROFILES = {
    101: {"name": "앨리스", "status": "active"},
    102: {"name": "밥", "status": "inactive"},
}

@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: int) -> dict:
    """사용자의 ID로 사용자 프로필을 검색합니다."""
    # URI에서의 {user_id}가 자동으로 인수로 전달됩니다.
    return USER_PROFILES.get(user_id, {"error": "사용자를 찾을 수 없습니다."})

print("리소스 템플릿 'users://{user_id}/profile'가 추가되었습니다.")

프롬프트 추가: 프롬프트는 재사용 가능한 상호작용 패턴을 정의합니다.

# my_server.py (계속)
@mcp.prompt("summarize")
async def summarize_prompt(text: str) -> list[dict]:
    """제공된 텍스트를 요약하는 프롬프트를 생성합니다."""
    return [
        {"role": "system", "content": "당신은 요약에 능숙한 유용한 조수입니다."},
        {"role": "user", "content": f"다음 텍스트를 요약해 주세요:\n\n{text}"}
    ]

print("프롬프트 'summarize'가 추가되었습니다.")

3. 서버 테스트(프로세스 내):

서버를 외부에서 실행하기 전에, 같은 Python 스크립트 내에서 Client를 사용하여 구성 요소를 직접 테스트할 수 있습니다. 이는 빠른 확인 및 단위 테스트에 유용합니다.

# my_server.py (계속)
from fastmcp import Client # 클라이언트 가져오기

async def test_server_locally():
    print("\n--- 로컬 서버 테스트 중 ---")
    # 클라이언트가 서버 객체를 가리키도록 설정합니다.
    client = Client(mcp)

    # 클라이언트는 비동작적이므로 비동기 컨텍스트 관리자를 사용합니다.
    async with client:
        # 'greet' 도구 호출
        greet_result = await client.call_tool("greet", {"name": "FastMCP 사용자"})
        print(f"greet 결과: {greet_result}")

        # 'add' 도구 호출
        add_result = await client.call_tool("add", {"a": 5, "b": 7})
        print(f"add 결과: {add_result}")

        # 'config' 리소스 읽기
        config_data = await client.read_resource("data://config")
        print(f"config 리소스: {config_data}")

        # 템플릿을 사용하여 사용자 프로필 읽기
        user_profile = await client.read_resource("users://101/profile")
        print(f"사용자 101 프로필: {user_profile}")

        # 'summarize' 프롬프트 구조 얻기(여기서 LLM 호출을 실행하지 않음)
        prompt_messages = await client.get_prompt("summarize", {"text": "이것은 일부 텍스트입니다."})
        print(f"요약 프롬프트 구조: {prompt_messages}")

# 로컬 테스트 함수 실행
# asyncio.run(test_server_locally())
# 지금은 주석 처리하였으며, 다음에는 서버를 실행하는 데 집중할 것입니다.

여기서 async 및 await의 사용에 주목하십시오. FastMCP 클라이언트는 비동기적으로 작동하므로 async 함수가 필요하며 async with client:를 사용하여 클라이언트의 생애 주기를 관리합니다.

4. 서버 실행:

MCP 서버를 외부 클라이언트(LLM 애플리케이션과 같은)에서 접근할 수 있게 하려면 실행해야 합니다. 두 가지 주요 방법이 있습니다:

표준 Python 실행(호환성을 위한 권장 방법):
my_server.py 파일에 다음 if __name__ == "__main__": 블록을 추가합니다. 이는 스크립트를 실행 가능하게 만들기 위한 표준 Python 관행입니다.

# my_server.py (파일 끝에)

if __name__ == "__main__":
    print("\n--- __main__을 통해 FastMCP 서버 시작 중 ---")
    # 이는 서버를 시작합니다. 일반적으로 기본적으로 stdio 전송을 사용합니다.
    mcp.run()

서버를 실행하려면 터미널에서 스크립트를 실행하십시오:

python my_server.py

이 명령은 MCP 서버를 시작하여 기본 stdio(표준 입력/출력) 전송 메커니즘을 사용하여 클라이언트 연결을 수신합니다. 이 방법은 다양한 클라이언트가 Python 스크립트를 실행할 것으로 예상할 때 서버가 일관되게 실행되도록 보장합니다.

FastMCP CLI 사용:
FastMCP는 서버를 실행하기 위한 명령줄 인터페이스를 제공하여, 특히 전송 옵션에 대한 더 많은 유연성과 제어를 제공합니다.

# stdio (기본값)을 사용하여 서버 실행
fastmcp run my_server.py:mcp

# 포트 8080에서 서버 전송 이벤트(SSE)를 사용하여 실행
fastmcp run my_server.py:mcp --transport sse --port 8080 --host 0.0.0.0

# 다른 로그 수준으로 실행
fastmcp run my_server.py:mcp --transport sse --log-level DEBUG

CLI에 대한 주요 사항:

my_server.py:mcp: 파일(my_server.py)과 해당 파일 내의 FastMCP 서버 객체(mcp)를 지정합니다. :mcp를 생략하면 FastMCP가 자동으로 mcp, app, 또는 server라는 이름의 객체를 찾으려고 시도합니다.
fastmcp run을 사용할 때 if __name__ == "__main__": 블록은 필수적이지 않습니다; CLI는 지정된 서버 객체를 직접 찾아 실행합니다.
--transport: 통신 프로토콜을 선택합니다(stdio, sse). SSE는 웹 기반 상호작용에 일반적입니다.
--port, --host, --log-level: 전송 및 로깅 설정을 구성합니다.

5. 실행 중인 서버와 상호작용(클라이언트):

서버가 실행 중인 경우(python my_server.py 또는 fastmcp run를 통해) 별도의 클라이언트 스크립트를 생성하여 상호작용할 수 있습니다.

새 파일 my_client.py를 생성하십시오:

# my_client.py
from fastmcp import Client
import asyncio

async def interact_with_server():
    print("--- 클라이언트 생성 중 ---")

    # 옵션 1: `python my_server.py`를 통해 실행 중인 서버에 연결 (stdio 사용)
    # client = Client("my_server.py")

    # 옵션 2: `fastmcp run ... --transport sse --port 8080`를 통해 실행 중인 서버에 연결
    client = Client("http://localhost:8080") # 정확한 URL/포트를 사용하십시오.

    print(f"클라이언트가 연결될 대상: {client.target}")

    try:
        async with client:
            print("--- 클라이언트 연결됨 ---")
            # 'greet' 도구 호출
            greet_result = await client.call_tool("greet", {"name": "원격 클라이언트"})
            print(f"greet 결과: {greet_result}")

            # 'config' 리소스 읽기
            config_data = await client.read_resource("data://config")
            print(f"config 리소스: {config_data}")

            # 사용자 프로필 102 읽기
            profile_102 = await client.read_resource("users://102/profile")
            print(f"사용자 102 프로필: {profile_102}")

    except Exception as e:
        print(f"오류 발생: {e}")
    finally:
        print("--- 클라이언트 상호작용 완료 ---")

if __name__ == "__main__":
    asyncio.run(interact_with_server())

서버가 다른 터미널에서 실행 중일 때 이 클라이언트 스크립트를 실행하십시오:

python my_client.py

클라이언트는 실행 중인 서버에 연결(클라이언트의 Client(...) 대상이 서버 실행 방식과 일치해야 합니다 - stdio의 경우 파일 경로, sse의 경우 URL)하여 도구 호출 및 리소스 읽기를 실행하고 결과를 출력합니다.

6. 서버 구성(ServerSettings):

ServerSettings을 사용하여 서버 동작을 세밀하게 조정할 수 있습니다. 설정은 우선 순위에 따라 적용됩니다:

FastMCP 초기화 중 키워드 인수(최고 우선 순위).
환경 변수(FASTMCP_SERVER_로 접두사가 붙음, 예: FASTMCP_SERVER_PORT=8888).
작업 디렉터리의 .env 파일에서 로드된 값.
기본값(최저 우선 순위).

초기화 중 구성 예시:

from fastmcp import FastMCP

mcp_configured = FastMCP(
    name="구성된 서버",
    port=8080,  # 기본 SSE 포트 설정
    host="127.0.0.1", # 기본 SSE 호스트 설정
    log_level="DEBUG", # 로깅 수준 설정
    on_duplicate_tools="warn" # 같은 이름의 도구가 등록되면 경고 (옵션: 'error', 'warn', 'ignore')
)

# .settings 속성을 통해 설정에 접근
print(f"설정된 포트: {mcp_configured.settings.port}") # 출력: 8080
print(f"중복 도구 정책: {mcp_configured.settings.on_duplicate_tools}") # 출력: warn

주요 구성 옵션에는 host, port, log_level, 및 중복 구성 요소 이름을 처리하는 정책(on_duplicate_tools, on_duplicate_resources, on_duplicate_prompts)이 포함됩니다.

FastMCP로 할 수 있는 다른 일은 무엇인가요?

FastMCP는 더 고급 사용 사례도 지원합니다:

조합: 여러 FastMCP 서버를 결합합니다. main.mount("sub", sub_server)는 라이브 링크를 생성하며, main.import_server(sub_server)는 구성 요소를 복사합니다. 이는 모듈화에 도움이 됩니다.
프록시: FastMCP.from_client(client)를 사용하여 다른 MCP 서버(로컬 또는 원격)의 프록시 역할을 하는 FastMCP 서버 인스턴스를 생성합니다. 이는 전송을 연결하거나(예: 로컬 stdio를 통해 원격 SSE 서버를 노출) 통합된 프런트를 추가하는 데 유용합니다.

결론

FastMCP는 모델 컨텍스트 프로토콜 구현을 간소화하여 강력하고 컨텍스트 인식 LLM 애플리케이션을 구축하는 진입 장벽을 크게 낮춥니다. 그 Pythonic 디자인, 보일러플레이트 줄이기에 중점을 두고 있고, 포괄적인 기능 세트를 제공하므로 개발자들이 LLM에 사용자 정의 도구와 데이터 접근을 안전하고 효율적으로 장착할 수 있는 훌륭한 선택입니다.

위에서 설명한 단계를 따라 FastMCP를 설치하고, 서버 인스턴스를 생성하고, 간단한 데코레이터를 사용하여 도구 및 리소스를 추가하고, 서버를 실행하면, MCP 기능을 갖춘 애플리케이션을 빠르게 구축할 수 있습니다. 단순한 유틸리티 도구를 만들거나 복잡하고 데이터 집약적인 통합을 구축하든, FastMCP는 강력하고 확장 가능한 LLM 상호작용을 위한 기반을 제공합니다.