Model Context Protocol Python 튜토리얼: 첫 번째 MCP 서버 구축하기

대부분의 MCP 콘텐츠는 큰 아이디어에서 멈춥니다. 즉, AI tools를 외부 시스템에 연결하는 표준적인 방법이라는 아이디어입니다. 그것은 유용하지만, Python 프로젝트 앞에 앉아 무엇을 먼저 만들어야 할지 고민할 때는 별로 도움이 되지 않습니다. 이 가이드는 실용적인 길을 택합니다. 무언가를 출시할 수 있을 만큼 Model Context Protocol Python을 잘 이해하고 싶다면, 가장 좋은 출발점은 하나의 tool, 하나의 resource, 그리고 하나의 명확한 사용 사례를 노출하는 작은 서버입니다.

그 관점은 지금 강한 검색 의도를 가지고 있습니다. 왜냐하면 개발자들이 일반적인 “AI agents” 실험을 넘어서, 더 좁혀진 질문을 던지고 있기 때문입니다. 즉, 매번 커스텀 접착 계층을 발명하지 않고서 어떻게 모델을 실제 파일, APIs, 비즈니스 로직에 연결하는가? 라는 질문입니다. 아직 첫 agent를 구축하는 중이라면, 먼저 Building AI Agents with Python 가이드부터 시작하세요.

왜 지금 이 주제가 트렌드인가

MCP는 틈새 프로토콜 이야기에서 주류 개발자 워크플로로 이동했습니다.

Anthropic은 2025년 12월에 MCP가 Anthropic, OpenAI, Microsoft, Google, AWS, Cloudflare, Block, Bloomberg의 지원을 받아 Agentic AI Foundation에 기부된다고 발표했습니다. 같은 발표에서 Anthropic은 MCP에 10,000개가 넘는 활성 퍼블릭 서버가 있으며, ChatGPT, Cursor, Gemini, Microsoft Copilot, VS Code 같은 제품들에 채택되었다고 말했습니다. 이것이 중요한 이유는 MCP를 흥미로운 아이디어에서 유통 채널로 바꾸기 때문입니다.

Python 개발자에게 타이밍은 특히 좋습니다. 공식 SDK 페이지는 Python을 Tier 1 SDK로 표기하고 있는데, 이는 강한 유지보수 약속과 기능의 완성도를 나타냅니다. 다시 말해, Python MCP 스택은 더 이상 투기적인 키워드가 아닙니다. 그것은 이미 공식 문서, 활발한 SDK, 명확한 구현 패턴을 갖춘 툴체인에 대응합니다.

MCP가 Python 개발자에게 실제로 주는 것

MCP를 생각하는 가장 간단한 방법은 이렇습니다. MCP는 AI 애플리케이션과 그것이 사용할 수 있는 context 또는 액션 사이의 경계를 표준화합니다.

공식 Python SDK는 세 가지 핵심 서버 구성 요소를 설명합니다:

• tools: 모델이 호출할 수 있는 액션을 위한 것
• resources: 애플리케이션이 로드할 수 있는 읽기 전용 context를 위한 것
• prompts: 재사용 가능한 상호작용 템플릿을 위한 것

이 구분이 중요합니다.

Tools

tools는 통합의 능동적인 부분입니다. 코드를 실행하거나, APIs를 호출하거나, 데이터를 쓰거나, 부수 효과를 트리거할 수 있습니다. 어시스턴트가 티켓을 생성하거나, weather API에 쿼리하거나, 작업을 시작해야 한다면, 그것은 tool에 속합니다.

Resources

resources는 수동적인 부분입니다. 전통적인 API의 GET 엔드포인트처럼 동작합니다. 아무것도 변경하지 않고 문서, 설정, 참조 데이터 같은 유용한 context를 노출합니다.

Prompts

prompts를 사용하면 재사용 가능한 지침이나 상호작용 패턴을 패키징하여, 클라이언트가 구조화된 방식으로 그것들을 호출할 수 있습니다.

이 분리가 진정한 가치입니다. MCP 이전에는 많은 팀들이 모든 것을 하나의 비대해진 tool schema에, 또는 prompt engineering에만 밀어 넣었습니다. 이 프로토콜을 사용하면 아키텍처를 추론하기가 더 쉬워지고, 클라이언트 간에 재사용하기가 더 쉬워집니다.

Codiste에서 tool-calling 패턴을 배포한 경험에서, tools와 resources 사이의 이 구분이 있었다면 상당한 리팩터링 시간을 절약했을 것입니다. 파인튜닝된 transformers를 사용해 Document AI 시스템을 구축했을 때, 우리는 처음에 문서 파싱을 동일한 인터페이스를 통해 액션이자 데이터 소스로 노출했고, 이는 모델이 언제 그것을 호출해야 하는지와 언제 context를 미리 로드해야 하는지에 대한 혼란을 만들었습니다. MCP가 강제하는 것과 같은 프로토콜 수준의 분리가 있었다면 그것을 완전히 방지했을 것입니다.

먼저 작은 MCP 서버를 구축하라

공식 Python SDK 퀵스타트는 FastMCP를 사용하는데, 이는 시작하기에 적절한 지점입니다. 프로토콜 세부 사항을 방해되지 않게 해주므로, 노출하고 싶은 실제 기능에 집중할 수 있습니다.

uv 또는 pip 중 하나로 설치하세요:

uv add "mcp[cli]"

또는:

pip install "mcp[cli]"

그런 다음 최소한의 서버로 시작하세요:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("Demo", json_response=True)

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers."""
    return a + b

@mcp.resource("greeting://{name}")
def greeting(name: str) -> str:
    """Return a greeting resource."""
    return f"Hello, {name}!"

@mcp.prompt()
def greet_user(name: str) -> str:
    return f"Write a friendly greeting for {name}."

if __name__ == "__main__":
    mcp.run(transport="streamable-http")

그 작은 예제는 거의 모든 실제 서버에서 따라야 할 모델을 가르쳐 줍니다:

1. 기능을 정의한다
2. 그것을 tool, resource, 또는 prompt로 분류한다
3. 표준 transport로 서버를 실행한다
4. 호스트 애플리케이션이나 inspector에서 연결한다

이것이 Model Context Protocol Python을 타기팅할 가치가 있게 만드는 실용적인 키워드 관점입니다. 검색하는 사람들은 보통 프로토콜 에세이를 원하지 않습니다. 그들은 오늘 바로 적용할 수 있는, 처음으로 작동하는 서버를 원합니다.

MCP가 커스텀 tool 접착제보다 나을 때

하나의 앱을 위한 하나의 프라이빗 헬퍼만 필요하다면, 직접적인 SDK 호출로 충분할 수 있습니다. 하지만 재사용성과 상호운용성이 중요해지는 순간부터 MCP가 이기기 시작합니다.

다음과 같을 때 MCP를 사용하세요:

• 동일한 기능이 여러 AI clients에 걸쳐 작동해야 할 때
• 앱과 tools 사이에 깔끔한 계약을 원할 때
• 팀이 tools, resources, prompts를 구별된 상태로 유지해야 할 때
• 통합 표면이 시간이 지남에 따라 커질 것으로 예상될 때

다음과 같을 때 과도한 엔지니어링을 피하세요:

• 일회용 프로토타입 하나를 테스트하고 있을 때
• 로직이 단일 앱에 강하게 결합되어 있고 재사용되지 않을 때
• 그 기능이 공식적인 인터페이스를 가질 만한지 아직 모를 때

핵심 통찰은 MCP가 단지 모델 접근에 관한 것만이 아니라는 점입니다. 그것은 다른 클라이언트가 이해할 수 있는 방식으로 context와 액션을 패키징하는 것에 관한 것입니다. 그것은 일회성 function calling 래퍼를 계속 반복해서 작성하는 것보다 장기적으로 더 강력한 이야기입니다. 예를 들어, RAG 시스템을 MCP resource로 노출하면 어떤 agent든 당신의 지식 베이스에 쿼리할 수 있습니다.

프로덕션 친화적인 시작을 위한 베스트 프랙티스

공식 SDK README와 서버 개념 문서는 일찍 채택할 가치가 있는 몇 가지 습관을 가리킵니다.

tools를 좁게 유지하라

do_everything이라는 하나의 tool을 만들지 마세요. 더 작은 tools는 모델이 올바르게 선택하기 더 쉽고, 당신이 테스트하기 더 쉽습니다. ControlNet을 사용한 이미지 세그멘테이션을 위한 AI agent 워크플로를 구축했을 때, 나는 이것을 어렵게 배웠습니다 – 광범위한 “process_image” tool은 지속적인 오라우팅을 일으켰지만, 그것을 “segment_image”, “apply_controlnet”, “postprocess_output”으로 분할하자 모델에 명확한 결정 경계가 생겼습니다.

읽기 전용 데이터는 resources에 두라

무언가가 액션으로 실행되기보다 context로 로드되어야 한다면, 그것을 resource로 노출하세요. 그러면 시맨틱이 명확하게 유지됩니다.

context는 도움이 되는 곳에서만 사용하라

Python SDK는 진행 상황 보고와 lifespan으로 관리되는 리소스에 대한 접근을 포함하여, tools에 대한 context 주입을 지원합니다. 그것은 강력하지만, 모든 엔드포인트에 필요한 것은 아닙니다.

하나의 transport와 하나의 클라이언트로 시작하라

SDK는 stdio, SSE, Streamable HTTP 같은 transports를 지원합니다. 하나의 경로를 선택하고, 워크플로를 입증한 다음, 확장하세요. OpenAI Agents SDK는 MCP 서버와 잘 작동하는 하나의 클라이언트입니다.

inspector 스타일의 도구로 테스트하라

퀵스타트는 서버를 완전한 호스트 애플리케이션에 연결하기 전에 테스트하는 방법으로 MCP Inspector를 명시적으로 가리킵니다. 이는 좋은 습관입니다. 왜냐하면 프로토콜 문제를 제품 문제로부터 분리해 주기 때문입니다.

마무리

Model Context Protocol Python이 지금 진정한 SEO 가치를 가지는 이유는 간단합니다. 그것은 트렌드의 추진력과 즉각적인 구현 의도를 결합하기 때문입니다. 개발자들은 주요 AI 제품들 전반에서 MCP에 대해 듣고, 그런 다음 돌아서서 스스로 그것을 사용하기 위한 가장 빠른 Python 경로를 검색합니다.

그것이 당신의 목표라면, 완전한 agent 플랫폼으로 시작하지 마세요. 당신이 이미 이해하고 있는 Python 프로젝트 안에서 하나의 유용한 MCP 서버로 시작하세요. 작은 tool을 노출하고, 하나의 resource를 추가하고, inspector로 테스트하고, 실제로 사용하는 클라이언트에 연결하세요.

그 워크플로는 추상적인 읽기가 가르쳐 줄 수 있는 것보다 더 빠르게 프로토콜을 가르쳐 줍니다. 일단 작동하면, 단일 로컬 서버에서 내부 도구, 문서 시스템, 지원 워크플로, 또는 개발자 자동화를 위한 재사용 가능한 인터페이스로 성장시킬 수 있습니다.

이번 주에 구체적인 다음 단계를 원한다면, 이미 수동으로 반복하고 있는 하나의 작업을 중심으로 작은 MCP 서버를 구축하세요. 그것은 보통 호기심에서 진정으로 유용한 무언가로 가는 가장 짧은 경로입니다.

---

관련 글

• OpenAI Agents SDK Python Tutorial - MCP tools와 resources를 소비하는 멀티 에이전트 워크플로를 구축하기
• Building AI Agents with Python - MCP가 표준화하는 agent loop, tool 사용, memory 패턴을 이해하기
• RAG with Python: Retrieval-Augmented Generation - MCP resource로 노출할 수 있는 지식 검색 시스템을 구축하기

출처

• Build an MCP Server
• MCP SDKs
• MCP Python SDK README
• Understanding MCP Servers
• Anthropic: Donating the Model Context Protocol and establishing the Agentic AI Foundation