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

이 예제에서는 문서를 읽는 도구와 문서를 업데이트하는 도구, 이렇게 두 가지 핵심 도구를 갖춘 문서 관리 서버를 만들고 있습니다. 모든 문서는 메모리 내에서 단순한 딕셔너리 형태로 존재하며, 키는 문서 ID이고 값은 콘텐츠입니다.
MCP 서버 설정하기
이 프로젝트는 MCP Python SDK 버전 1을 사용하며, 프로젝트 설정 시 해당 버전이 자동으로 설치됩니다. 직접 프로젝트를 설정하는 경우에는 "mcp[cli]<2"를 설치하세요. 버전 2에서는 FastMCP가 MCPServer로 이름이 바뀌었기 때문에, 아래의 import 구문은 버전 2에서는 실패합니다.
Python MCP SDK를 사용하면 서버 생성이 매우 간단해집니다. 단 한 줄로 서버를 초기화할 수 있습니다:
from mcp.server.fastmcp import FastMCP
from pydantic import Field
mcp = FastMCP("DocumentMCP", log_level="ERROR")이렇게 하면 도구 정의, 클라이언트 연결, 메시지 라우팅을 처리할 수 있는 완전한 기능을 갖춘 MCP 서버가 만들어집니다.
데코레이터를 이용한 도구 정의

SDK의 데코레이터 방식을 사용하면 수동으로 JSON 스키마를 작성할 필요가 없어집니다. 간단한 도구를 정의하는 방법은 다음과 같습니다:
@mcp.tool(
name="add_ints",
description="Add two integers together",
)
def tool_fn(
a=Field(description="First number to add"),
b=Field(description="Second number to add"),
) -> int:
return a + b보이지 않는 곳에서 MCP는 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]이 함수에는 존재하지 않는 문서에 대한 요청을 잡아내는 기본적인 오류 처리가 포함되어 있습니다. Claude가 유효한 문서 ID로 이 도구를 호출하면, 전체 문서 내용을 문자열로 받게 됩니다.
문서 편집 도구 만들기
두 번째 도구는 문서에 대한 간단한 찾기 및 바꾸기 작업을 수행합니다. 문서 ID, 찾을 텍스트, 대체할 텍스트, 이렇게 세 가지 매개변수가 필요합니다:
@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 white space."),
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)이 구현은 Python의 내장 문자열 replace 메서드를 사용하며, 이는 공백을 포함한 정확한 일치가 필요합니다. 이 도구는 딕셔너리 내의 문서를 직접 수정합니다.
SDK 방식의 주요 이점
- 수동으로 JSON 스키마를 작성할 필요가 없습니다
- 타입 힌트가 자동으로 매개변수 유효성 검사를 제공합니다
- 필드 설명이 Claude가 도구 사용법을 이해하는 데 도움을 줍니다
- 오류 처리가 Python의 예외 처리와 자연스럽게 통합됩니다
- 도구 등록이 데코레이터를 통해 자동으로 이루어집니다
MCP Python SDK는 도구 생성 작업을 복잡한 스키마 작성 과정에서 간단한 Python 함수 정의로 탈바꿈시켜 줍니다. 여러분의 도구는 더 유지 관리하기 쉽고 테스트하기 편해지는 동시에, Claude는 도구를 효과적으로 사용하는 데 필요한 모든 메타데이터를 얻게 됩니다.