MCP Server 개발에 Python과 TypeScript 중 무엇을 선택해야 하나요?

Python 공식 SDK mcp와 FastMCP 조합이 가장 빠르게 시작할 수 있어 백엔드·AI 엔지니어에게 적합합니다. TypeScript 공식 SDK @modelcontextprotocol/sdk는 프론트엔드·풀스택 팀에 적합합니다. 두 언어 모두 프로토콜 계층에서 완전히 호환되며, 한 번 작성한 로직을 대조하여 이전할 수 있습니다.

MCP Server의 Tools와 Resources 차이는 무엇인가요?

Tools는 동작 실행자로, AI가 호출하면 외부 상태를 변경하거나 계산을 트리거합니다. Resources는 데이터 제공자로, URI로 주소 지정하여 읽기 전용으로 콘텐츠를 가져옵니다. 예: file://, config://, user://{id}/profile.

원격 MCP Server 7×24 운영에 추천하는 환경은 무엇인가요?

HTTP+SSE 모드는 Railway, Cloud Run 또는 자체 VPS에 배포할 수 있습니다. macOS 네이티브 도구체인, Keychain, Cursor 장기 연동이 필요하다면 Mac Mini M4 클라우드 렌탈 uptime이 더 안정적입니다. 1개월 렌탈로 tools/call 호출 곡선을 먼저 검증하세요.

MCP Server 처음부터 개발하기: AI 도구 호출 능력 구축 완전 가이드

MCP란 무엇인가? 코드 작성 전에 프로토콜부터 이해합니다

대규모 언어 모델의 도구 호출 능력은 Function Calling → Plugins → MCP로 진화해 왔습니다. Anthropic이 MCP를 설계한 핵심 동기는 AI와 외부 도구 간 통신을 개방형 프로토콜로 표준화하여 「Server를 한 번 작성하면 여러 Client에서 재사용」하는 것을 현실로 만드는 것입니다.

MCP 프로토콜 아키텍처: Client ↔ Server ↔ 3대 핵심 능력

MCP Client(Claude Desktop, Cursor, 커스텀 클라이언트)와 MCP Server(개발자가 작성하는 부분)는 JSON-RPC 2.0으로 통신합니다. Server는 아래 3가지 핵심 능력과 연결됩니다. Tools(검색, 계산, DB 쿼리 등 호출 가능한 함수), Resources(파일, URL, 데이터 스트림 등 읽기 가능한 리소스), Prompts(사전 정의된 프롬프트 템플릿)입니다.

전송 방식은 두 가지입니다. stdio(로컬 자식 프로세스, 지연 시간 극히 낮음)와 HTTP + SSE(원격 서비스, 다중 클라이언트 지원)입니다. 생명주기는 초기화 핸드셰이크 → 기능 협상 → 요청/응답 → 종료 순서입니다.

01
모델의 실시간 데이터 부재: 학습 데이터 시점 제한으로 「오늘 주가」나 「최신 티켓 상태」에 답할 수 없으며, 외부 API 연결이 필수입니다.
02
벤더별 도구 형식 불일치: ChatGPT Plugins, OpenAI Function Calling, Claude Tool Use가 각자 다른 방식을 사용해 모델을 바꾸면 통합 계층을 처음부터 다시 작성해야 합니다.
03
IDE 간 도구 자산 재사용 불가: Cursor, VS Code, Claude Desktop마다 연동 방식이 달라 팀이 축적한 도구를 제품 간 이전하기 어렵습니다.
04
Agent 프레임워크 종속: LangChain Tools를 CrewAI에서 바로 쓸 수 없어 오케스트레이션 자산이 팀이 아니라 프레임워크에 묶입니다.
05
N×M 유지보수 비용: N개 모델 × M개 외부 시스템 = 지수급 맞춤 통합이 발생하며, MCP는 이를 「Server 한 번, 어디서나 사용」으로 수렴시킵니다.

비교 항목	MCP	OpenAI Function Calling	LangChain Tools
표준화 수준	개방형 프로토콜 표준	벤더 독점	프레임워크 종속
전송 방식	stdio / HTTP	HTTP	HTTP
크로스 모델 지원	예	아니오	부분적
Resources / Prompts	네이티브 지원	미지원	미지원
생태계 도구	급속 성장(10000+ Server)	성숙	성숙

이 절을 읽고 코드를 작성하세요. MCP는 또 하나의 SDK가 아니라 AI 도구화의 표준 프로토콜입니다. 이를 익히는 것이 2026년 AI 엔지니어의 핵심 경쟁력입니다.

개발 환경 준비: 언어 선택과 프로젝트 구조

Python(공식 SDK mcp + FastMCP)은 초보자에게 권장합니다. TypeScript(@modelcontextprotocol/sdk)는 프론트엔드·풀스택에 적합합니다. 본 글은 Python을 중심으로 설명하고 TypeScript는 대조용으로 다룹니다.

bash · 환경 구축

python -m venv .venv
source .venv/bin/activate
pip install mcp

npm init -y
npm install @modelcontextprotocol/sdk

권장 프로젝트 구조는 다음과 같습니다.

text · 디렉터리 구조

my-mcp-server/
├── server.py
├── tools/
│   ├── calculator.py
│   └── web_search.py
├── resources/
│   └── file_reader.py
├── prompts/
│   └── templates.py
├── tests/
│   └── test_tools.py
├── pyproject.toml
└── README.md

디버깅 도구 3종: MCP Inspector(공식 UI, npx @modelcontextprotocol/inspector), Claude Desktop 로컬 연동(claude_desktop_config.json), Cursor MCP 설정(Settings → MCP Servers)입니다. 공식 문서는 modelcontextprotocol.io에서 확인할 수 있습니다.

첫 MCP Server: Hello World와 Cursor 연동

아래 6단계 Runbook으로 30분 안에 AI가 호출할 수 있는 첫 도구를 실행할 수 있습니다.

python · server.py

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-first-server")

@mcp.tool()
def say_hello(name: str) -> str:
    """지정한 사람에게 인사합니다"""
    return f"Hello, {name}! 이것이 첫 MCP 도구입니다."

if __name__ == "__main__":
    mcp.run()

01
가상 환경 생성 및 mcp 설치: pip install mcp를 실행하고 Python ≥ 3.10을 확인합니다.
02
server.py 작성: @mcp.tool() 데코레이터로 say_hello를 등록합니다. docstring이 곧 도구 설명입니다.
03
Inspector 디버깅: npx @modelcontextprotocol/inspector python server.py로 UI에서 tools/list와 tools/call을 테스트합니다.
04
Cursor 설정: MCP 설정에 {"command":"python","args":["/path/to/server.py"]}를 추가하고 재시작 후 Agent 컨텍스트에 도구가 나타나는지 확인합니다.
05
Claude Desktop 설정: ~/Library/Application Support/Claude/claude_desktop_config.json을 편집합니다. 형식은 Cursor와 동일합니다.
06
호출 검증: Cursor에서 「say_hello로 VpsMesh에게 인사해줘」를 입력하고 Agent가 도구를 자동 선택해 결과를 반환하는지 확인합니다.

ℹ

팁: 함수 시그니처가 곧 문서입니다. 매개변수 타입, 반환 타입, docstring이 LLM에 직접 노출되어 Agent가 도구를 올바르게 선택할 수 있는지를 결정합니다.

Tools 개발: AI가 호출할 다섯 가지 실용 도구

도구는 MCP Server의 핵심입니다. 명명 규칙은 동사로 시작하는 것을 권장합니다(search_web, query_database). 복잡한 매개변수는 Pydantic으로 모델링합니다.

python · Pydantic 입력

from pydantic import BaseModel, Field

class SearchInput(BaseModel):
    query: str = Field(description="검색 키워드")
    max_results: int = Field(default=5, description="최대 반환 결과 수")
    language: str = Field(default="ko", description="결과 언어")

@mcp.tool()
def web_search(input: SearchInput) -> list[dict]:
    """웹 검색을 실행하고 관련 결과 목록을 반환합니다"""
    ...

다섯 가지 실전 도구 목록

계산기: 수학 표현식을 안전하게 평가하며, eval 직접 호출은 금지합니다.
파일 읽기/쓰기: allowlist 디렉터리로 제한하고 로컬 Markdown이나 설정을 읽고 씁니다.
HTTP 요청: GET/POST를 캡슐화하고 타임아웃과 재시도를 통일합니다.
데이터베이스 쿼리: 읽기 전용 SQL과 매개변수화로 인젝션을 방지합니다.
시간 도구: 현재 시각, 시간대 변환, 영업일 계산을 제공합니다.

python · 비동기 도구

import httpx

@mcp.tool()
async def fetch_url(url: str) -> str:
    """지정 URL의 콘텐츠를 가져옵니다"""
    async with httpx.AsyncClient(timeout=30.0) as client:
        response = await client.get(url)
        return response.text

오류 처리 모범 사례: 예상 가능한 실패에는 error_code와 message를 포함한 구조화된 오류 정보를 반환합니다. 네트워크 IO에는 반드시 타임아웃을 설정합니다. 쓰기 작업 전에는 권한 검증과 감사 로그를 수행합니다.

Resources와 Prompts: 데이터 공급과 프롬프트 템플릿

Resources: AI가 읽을 수 있는 동적 콘텐츠

Resource와 Tool의 차이: Resource는 데이터 제공자(읽기 전용)이고, Tool은 동작 실행자입니다. URI로 주소를 지정합니다. file://, http://, custom:// 등입니다.

python · 정적·동적 리소스

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    return json.dumps({"version": "1.0", "env": "production"})

@mcp.resource("user://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    user = db.query_user(user_id)
    return json.dumps(user)

리소스 유형은 텍스트(text/plain, application/json), 바이너리(이미지, PDF), 스트리밍 실시간 데이터를 포함합니다. 파일 시스템 리소스 서버는 디렉터리 나열, 파일 읽기, 변경 감시(리소스 구독)를 구현할 수 있습니다.

Prompts: 재사용 가능한 프롬프트 템플릿

MCP Prompt는 사전 정의된 조각으로, 동적 매개변수 주입을 지원해 일관성과 유지보수성을 높입니다. user와 assistant를 포함한 다중 턴 템플릿을 정의할 수 있으며, 코드 리뷰, 면접 시뮬레이션, 디버깅 어시스턴트 등에 적합합니다.

python · 코드 리뷰 Prompt

from mcp.types import PromptMessage, TextContent

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> list[PromptMessage]:
    return [
        PromptMessage(
            role="user",
            content=TextContent(
                type="text",
                text=f"다음 {language} 코드를 검토해 주세요. 품질, 버그, 성능에 집중합니다.\n```{language}\n{code}\n```"
            )
        )
    ]

HTTP 원격 전송, 디버깅·테스트와 흔한 오류

특성	stdio	HTTP + SSE
배포 방식	로컬 프로세스	원격 서버
지연 시간	극히 낮음	네트워크 의존
다중 클라이언트	미지원	지원
적합 시나리오	로컬 도구	SaaS / 팀 공유

python · streamable-http

mcp = FastMCP("remote-server", transport="streamable-http")

if __name__ == "__main__":
    mcp.run(host="0.0.0.0", port=8000)

원격 배포 보안 요점: Bearer Token 인증, API Key 검증 미들웨어, CORS 설정, 요청 빈도 제한입니다. 프로덕션 환경에서는 tool schema에 비밀키를 넣지 마세요.

MCP Inspector와 단위 테스트

Inspector로 Tools 호출을 테스트하고 JSON-RPC 로그를 확인하며 오류 시나리오를 시뮬레이션할 수 있습니다. 단위 테스트는 공식 Client SDK로 stdio 자식 프로세스를 시작합니다.

python · pytest

@pytest.mark.asyncio
async def test_calculator_tool():
    server_params = StdioServerParameters(command="python", args=["server.py"])
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            result = await session.call_tool("calculate", {"expression": "2 + 2"})
            assert result.content[0].text == "4"

오류	원인	해결 방법
도구가 AI에 나타나지 않음	설정 경로 오류	config.json의 command/args 절대 경로 확인
JSON 직렬화 실패	지원하지 않는 반환 타입	str 또는 dict로 변환
타임아웃으로 연결 끊김	도구 실행이 너무 느림	async로 전환하고 timeout 설정
권한 거부	파일 경로 제한	허용 디렉터리 allowlist 구성

프로덕션 배포, 지식베이스 실전과 MCP 생태계

Docker 컨테이너화와 클라우드 서비스

dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "server.py"]

배포 옵션: Railway / Render(개인 프로젝트 원클릭 배포), AWS Lambda / Google Cloud Run(Serverless), 자체 VPS(Nginx 리버스 프록시)입니다. 모니터링은 구조화 로그, Prometheus 지표, Sentry 알림, 헬스 체크 엔드포인트를 사용합니다. 버전 관리 시 MCP 프로토콜 버전을 선언하고, 도구 업그레이드 시 하위 호환성을 유지합니다.

실전 프로젝트: 개인 지식베이스 MCP Server

요구사항: AI가 로컬 Markdown 노트를 검색하고, 의미 검색을 수행하며, 노트를 생성·업데이트하게 합니다. 기술 선택: ChromaDB / Qdrant 벡터 DB, text-embedding-3-small 임베딩, watchfiles로 파일 변경 감시입니다. 핵심 구현: 노트 인덱싱 도구, 의미 검색 도구, 노트 쓰기 도구, 파일 리소스 서비스입니다. 효과: Cursor에서 「지난주 MCP에 대해 기록한 내용이 뭐야?」라고 물으면 Agent가 검색 도구를 호출해 관련 조각을 반환합니다.

우수 MCP Server와 2026 생태계 트렌드

mcp-server-filesystem: 파일 시스템 작업
mcp-server-github: GitHub 저장소 작업
mcp-server-brave-search: 웹 검색
mcp-server-postgres: 데이터베이스 쿼리
mcp-server-slack: Slack 메시지

2026년 주류 AI 클라이언트(Cursor, Claude Desktop, VS Code, OpenAI, Gemini)는 모두 MCP를 지원합니다. MCP Marketplace와 엔터프라이즈 보안 표준이 빠르게 발전하고 있습니다. 다음 단계: 프로토콜 사양 심화 학습, 공개 Server 배포, MCP + Agent 조합 탐색, 오픈소스 생태 기여입니다. 참고 자료: Python SDK, TypeScript SDK, MCP Inspector입니다.

인용 가능한 핵심 데이터

프로토콜 기반: JSON-RPC 2.0, 전송 계층 STDIO 또는 HTTP+SSE, 도구 발견은 tools/list 런타임 풀 방식입니다.
생태 규모: 2026년 기준 MCP 생태에 10,000+ Server가 있으며, 네트워크 효과는 초기 HTTP와 유사합니다.
통합 비용: MCP 인터페이스 통일 후 기업 AI 통합 개발 비용이 38–55% 감소합니다(업계 조사 구간).
벤더 지원: 2026년 Q1–Q2 OpenAI, Google, Microsoft가 전면 참여했으며, 거버넌스는 AAIF로 이전되었습니다.

노트북은 MCP POC에 적합하지만, 뚜껑을 닫으면 슬립되고 macOS 네이티브 도구체인과 장기 프로세스 데몬이 부족해 7×24 경험이 약해집니다. 순수 Linux VPS는 HTTP+SSE를 실행할 수 있지만 Keychain, Xcode 등 macOS 의존 MCP 도구는 어렵습니다. 여러 MCP Server를 「상주 인프라」로 두고 Agent가 주 단위로 도구 호출 복리를 쌓으려는 기술 팀에게 VpsMesh Mac Mini M4 클라우드 렌탈은 uptime, 원격 KVM, 예측 가능한 월 비용을 프로덕션 OpEx로 묶어 개발 머신을 반복 재설치하는 것보다 시간을 절약합니다. 요금은 Mac Mini M4 대여 가격, 배포 문의는 고객 센터, 주문은 주문 페이지에서 확인하실 수 있습니다.

자주 묻는 질문

독자가 가장 많이 묻는 세 가지 질문

Python 공식 SDK mcp와 FastMCP 조합이 가장 빠르게 시작할 수 있어 백엔드·AI 엔지니어에게 적합합니다. TypeScript SDK @modelcontextprotocol/sdk는 프론트엔드·풀스택에 적합합니다. 두 언어 모두 프로토콜 계층에서 완전히 호환되며, 로직을 대조하여 이전할 수 있습니다. 팀이 Node 풀스택이면 TS, 데이터·ML 중심이면 Python을 선택하세요.

Tools는 동작 실행자입니다. AI가 호출하면 외부 상태를 변경하거나 계산을 트리거합니다(검색, 파일 쓰기, 요청 전송). Resources는 데이터 제공자입니다. URI로 읽기 전용 콘텐츠를 가져옵니다. 예: config://app-settings 또는 user://{id}/profile. 간단히 기억하세요. 데이터 읽기는 Resource, 동작 수행은 Tool입니다.

HTTP+SSE 모드는 Railway, Cloud Run 또는 Linux VPS에 배포할 수 있습니다. MCP 도구체인이 macOS 네이티브 기능, Keychain에 의존하거나 Cursor Agent와 여러 Server를 뚜껑을 닫아도 7×24 중단 없이 운영하려면 Mac Mini M4 월 렌탈이 더 편리합니다. 1개월 렌탈로 tools/call 호출 곡선을 먼저 검증하세요. 요금은 Mac Mini M4 대여 가격, 주문은 주문 페이지에서 확인하실 수 있습니다.