공식 Python SDK를 사용하면 MCP 서버를 구축하는 작업이 훨씬 간단해집니다. 복잡한 JSON 스키마를 직접 작성하는 대신, 데코레이터로 도구를 정의하고 SDK가 번거로운 작업을 처리하도록 맡길 수 있습니다.

이 예제에서는 두 가지 핵심 도구를 갖춘 문서 관리 서버를 만듭니다. 하나는 문서를 읽는 도구이고 다른 하나는 문서를 업데이트하는 도구입니다. 모든 문서는 키가 문서 ID이고 값이 콘텐츠인 간단한 딕셔너리 형태로 메모리에 존재합니다.
프로젝트 받기
이 과정의 레슨들은 MCP 클라이언트와 MCP 서버를 갖춘 명령줄 챗봇인 작은 시작 프로젝트를 기반으로 진행됩니다. 이 레슨 끝부분의 다운로드 섹션에서 cli_project.zip을 다운로드하여 원하는 개발 디렉터리에 압축을 풀어주세요. 프로젝트 폴더에서 코드 편집기를 여세요.
프로젝트에는 설정 방법이 담긴 README 파일이 포함되어 있습니다. .env 파일에 Anthropic API 키를 추가하세요. 그런 다음 uv(권장) 또는 pip 중 하나를 사용하여 의존성을 설치하세요. 이 프로젝트는 MCP Python SDK의 버전 1을 사용하며, 설정 과정에서 해당 버전이 자동으로 설치됩니다.
MCP 서버 설정하기
MCP Python SDK를 사용하면 서버 생성이 간단해집니다. mcp_server.py를 여세요. 이미 단 한 줄로 서버가 초기화되어 있습니다. 아래의 도구들에는 Field import도 필요합니다:
from mcp.server.fastmcp import FastMCP
from pydantic import Field
mcp = FastMCP("DocumentMCP", log_level="ERROR")문서는 간단한 딕셔너리 구조로 저장할 수 있습니다:
docs = {
"deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
"report.pdf": "The report details the state of a 20m condenser tower.",
"financials.docx": "These financials outline the project's budget and expenditures",
"outlook.pdf": "This document presents the projected future performance of the system",
"plan.md": "The plan outlines the steps for the project's implementation.",
"spec.txt": "These specifications define the technical requirements for the equipment"
}데코레이터를 사용한 도구 정의
SDK는 데코레이터를 사용하여 도구를 정의합니다. JSON 스키마를 수동으로 작성하는 대신 Python 타입 힌트와 필드 설명을 사용할 수 있습니다. SDK는 Claude가 이해할 수 있는 적절한 스키마를 자동으로 생성합니다.
문서 읽기 도구 만들기
첫 번째 도구는 ID로 문서 내용을 읽습니다. 전체 구현은 다음과 같습니다:
@mcp.tool(
name="read_doc_contents",
description="Read the contents of a document and return it as a string."
)
def read_document(
doc_id: str = Field(description="Id of the document to read")
):
if doc_id not in docs:
raise ValueError(f"Doc with id {doc_id} not found")
return docs[doc_id]데코레이터는 도구 이름과 설명을 지정하며, 함수 매개변수는 필요한 인자를 정의합니다. Pydantic의 Field 클래스는 Claude가 각 매개변수가 무엇을 기대하는지 이해하는 데 도움이 되는 인자 설명을 제공합니다.
문서 편집 도구 구축하기
두 번째 도구는 문서에 대해 간단한 찾기 및 바꾸기 작업을 수행합니다:
@mcp.tool(
name="edit_document",
description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
doc_id: str = Field(description="Id of the document that will be edited"),
old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
new_str: str = Field(description="The new text to insert in place of the old text.")
):
if doc_id not in docs:
raise ValueError(f"Doc with id {doc_id} not found")
docs[doc_id] = docs[doc_id].replace(old_str, new_str)이 도구는 문서 ID, 찾을 텍스트, 대체할 텍스트라는 세 가지 매개변수를 받습니다. 구현에는 문서가 없는 경우에 대한 오류 처리와 간단한 문자열 대체 작업이 포함되어 있습니다.
SDK 방식의 주요 이점
- JSON 스키마를 수동으로 작성할 필요가 없습니다
- 타입 힌트가 자동 검증을 제공합니다
- 명확한 매개변수 설명이 Claude가 도구 사용법을 이해하는 데 도움이 됩니다
- 오류 처리가 Python 예외와 자연스럽게 통합됩니다
- 도구 등록이 데코레이터를 통해 자동으로 이루어집니다
MCP Python SDK는 도구 생성을 복잡한 스키마 작성 작업에서 간단한 Python 함수 정의로 바꿔줍니다. 이 접근 방식을 사용하면 Claude가 올바른 형식의 도구 사양을 받도록 보장하면서도 MCP 서버를 훨씬 쉽게 구축하고 유지 관리할 수 있습니다.