처음부터 MCP Server 개발:
AI 도구 호출 기능을 단계별로 구축

서론: AI에 MCP가 필요한 이유

대규모 언어 모델이 아무리 강해도 학습 데이터에는 컷오프가 있으며, CRM 고객·어젯밤 로그·사내 API 실시간 상태를 허공에서 알 수 없습니다. 업계 진화 경로는 분명합니다: Function Calling → Plugins → MCP. 앞의 두 방식은 벤더 고유 형식이 많아 모델을 바꿀 때마다 통합층을 다시 작성해야 합니다. MCP는 「AI가 어떤 도구를 발견하고 어떻게 호출하는지」를 개방 프로토콜로 표준화해, 한 번 작성하면 여러 Client에서 재사용할 수 있습니다.

1. 01

   과제: Claude/GPT가 DB 조회·API 호출·파일 조작을 하게 하고 싶지만 형식이 제각각입니다.

2. 02

   시나리오: Cursor에서 Markdown 노트를 읽게 하거나, Claude Desktop에서 GitHub Issue를 조회합니다.

3. 03

   약속: 빈 디렉터리에서 배포 가능한 Server까지, 완전한 코드와 트러블슈팅 표와 함께 안내합니다.

개발 환경 준비

3.1 언어 선택

Python(공식 SDK mcp, FastMCP 데코레이터가 간결)은 초보자 추천. TypeScript(@modelcontextprotocol/sdk)는 프론트엔드/풀스택에 적합합니다. 본 글은 Python 위주, TS는 대조용으로 진행합니다.

# Python
python -m venv .venv && source .venv/bin/activate
pip install mcp httpx pydantic

# TypeScript(대조)
npm init -y && npm install @modelcontextprotocol/sdk

3.2 프로젝트 구조

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.3 디버깅 도구

1. 1

   MCP Inspector: npx @modelcontextprotocol/inspector python server.py

2. 2

   Claude Desktop: claude_desktop_config.json을 편집해 Server를 등록합니다.

3. 3

   Cursor: Settings → MCP → command + args 추가.

Tools: AI가 호출할 수 있는 도구 개발

5.1 기본 구조

함수 시그니처가 곧 문서입니다. 매개변수 타입·반환 타입·docstring은 모델의 도구 선택에 노출됩니다. 이름은 snake_case, 동사로 시작(search_web, read_file)하는 것이 좋습니다. 오류는 예외를 그대로 던지기보다 구조화 JSON을 반환하면 모델이 자기 수정하기 쉽습니다.

5.2 복잡한 매개변수(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]:
    """웹 검색을 실행하고 관련 결과 목록을 반환한다"""
    ...

5.3 실용 5종 도구 목록

5.4 비동기 도구

@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

5.5 오류 처리 모범 사례

• !

  네트워크/IO 작업에 타임아웃 설정(15–30초 권장).

• !

  민감 작업에 권한 검증(API Key, 허용 경로).

• !

  {"error": "...", "hint": "..."} 반환으로 모델 재시도 유도.

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

MCP 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} 코드를 리뷰해 주세요:
1. 품질과 가독성  2. Bug와 보안  3. 성능 최적화

```{language}
{code}
```""")
    )]

user + assistant 다중 턴 템플릿도 정의할 수 있어 면접 시뮬레이션, 디버깅 어시스턴트 등에 쓰입니다. Client는 prompts/get으로 채워진 메시지 체인을 가져옵니다.

디버깅과 테스트

9.1 MCP Inspector

Inspector 실행으로 tools/list, tools/call을 그래픽으로 테스트하고 JSON-RPC 로그 확인, 오류 시나리오 시뮬레이션이 가능합니다.

9.2 단위 테스트(pytest + ClientSession)

@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"

9.3 흔한 오류와 해결

실전: 개인 지식베이스 MCP Server

요구사항: AI가 로컬 Markdown 노트 검색, 의미 검색, 생성/업데이트. Cursor에서 「지난주 MCP에 대해 뭐라고 메모했지?」라고 물을 수 있게 합니다.

기술 선택

핵심 Tools

1. 1

   index_notes: 디렉터리를 스캔해 벡터 인덱스를 구축합니다.

2. 2

   semantic_search: 의미 기반으로 관련 조각을 반환합니다.

3. 3

   write_note: Markdown을 생성하거나추가합니다.

4. 4

   Resource: notes://{path}로 단일 노트 직접 읽기.

효과: AI가 semantic_search로 조각을가져온한 뒤 답을 종합하므로, 노트 전체를 컨텍스트에 넣는 것보다 Token을 절약하고 정확도가 올라갑니다.

FAQ

맺음말

MCP는 AI 도구화의 표준 프로토콜입니다. Hello World에서 프로덕션 배포까지 전 과정을 익히는 것은 2026년 AI 엔지니어의 핵심 역량 중 하나입니다. MCP로 어떤 도구를 만들 계획인가요? 실습 후 Server 설계를 돌아보면 좋습니다.

숨은 비용은 코드 작성보다 실행 환경에 있습니다. Windows 주력 + 클라우드 Mac에서 Cursor MCP를 혼합 운영하면 권한 팝업, Python 가상환경, Inspector 로그를 동일 머신의 데스크톱 세션에서 대조해야 합니다. Mac mini를 직접 구매하면 슬립, OS 업데이트, 감가상각을 떠안고, 8GB 메모리는 벡터 인덱스 + 다중 Server 동시 실행에 쉽게 포화됩니다.

시간 과금으로 MCP 도구체인을 검증하고 Cursor와 동일 기기 그래픽 UI에서 TCC·Inspector 검수를 마치려면 VNCMac 원격 Mac 임대를 이용하세요. 아래 주 버튼에서 요금 플랜으로, 플랜 비교는 홈을 참고하세요.