MCP 서버 직접 만들기: 처음부터 끝까지 따라하는 튜토리얼

 

공식 Python SDK로 도구 하나짜리 MCP 서버를 만들고, Inspector로 검증한 뒤 Claude에 연결하는 전 과정을 정리합니다.

MCP를 쓰는 글은 많은데, 직접 서버를 만들어 보는 글은 의외로 적습니다. 막상 시작하면 SDK 버전이 바뀌어 예제 코드가 동작하지 않거나, Claude에 연결하는 설정에서 막히는 경우가 흔합니다. 이 글은 2026년 6월 기준 공식 문서를 따라, 도구(tool) 하나를 노출하는 최소 MCP 서버를 만들고 검증해 Claude에 붙이는 과정을 단계별로 보여 줍니다. 파이썬을 주 언어로 쓰되, 타입스크립트 버전도 함께 짚습니다. 따라 하다 막히는 지점과 보안 주의점까지 담았습니다.

MCP가 해결하는 문제

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 LLM 애플리케이션이 외부 데이터와 도구에 연결되는 방식을 표준화한 오픈 프로토콜입니다.

문제의 배경은 이렇습니다. AI 앱마다, 그리고 연결하려는 도구마다 통합 코드를 따로 짜면 조합이 폭발합니다. 앱 M개와 도구 N개가 있으면 M×N개의 연결을 만들어야 합니다. MCP는 이 사이에 표준 규약을 둬서 M+N으로 줄입니다. 공식 문서는 이를 코드 에디터 생태계의 LSP(Language Server Protocol)에 비유합니다. LSP가 언어 도구를 에디터마다 다시 만들지 않게 했듯, MCP는 컨텍스트와 도구 연동을 앱마다 다시 만들지 않게 합니다.

MCP는 JSON-RPC 2.0 메시지를 주고받으며, 세 가지 역할로 구성됩니다. 호스트(LLM 앱), 클라이언트(호스트 안의 연결 주체), 서버(컨텍스트와 기능을 노출하는 쪽)입니다. 우리가 만들 것은 이 중 서버입니다. 현재 안정 스펙 버전은 2025-11-25입니다.

MCP 서버가 노출하는 세 가지

서버가 클라이언트에 제공할 수 있는 기본 구성 요소는 세 가지입니다. 누가 제어하는지를 함께 기억하면 헷갈리지 않습니다.

• 도구(Tools): 모델이 직접 호출하는 함수입니다. DB에 쓰거나 API를 부르거나 파일을 고치는 등 행동을 합니다. 호출 시점은 모델이 판단합니다.
• 리소스(Resources): 읽기 전용 데이터입니다. 파일 내용, DB 스키마, 문서처럼 맥락을 제공합니다. 각 리소스는 고유 URI를 가집니다. 노출 여부는 애플리케이션이 제어합니다.
• 프롬프트(Prompts): 재사용 가능한 지시 템플릿입니다. 슬래시 명령처럼 사용자가 직접 부릅니다.

이번 실습에서는 가장 자주 쓰는 도구 하나를 만들어 봅니다.

실습: 파이썬으로 첫 MCP 서버 만들기

공식 Python SDK 패키지 이름은 mcp입니다. 의존성 관리는 uv를 권장하지만 pip도 됩니다. CLI 도구까지 함께 설치합니다.

uv add "mcp[cli]"
# 또는
pip install "mcp[cli]"

이제 서버 코드를 작성합니다. FastMCP를 쓰면 타입 힌트와 독스트링에서 도구 스키마가 자동 생성됩니다. 아래는 숫자 두 개를 더하는 도구 하나를 노출하는 최소 서버입니다.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("demo")

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

    Args:
        a: First number
        b: Second number
    """
    return a + b

def main():
    mcp.run(transport="stdio")

if __name__ == "__main__":
    main()

코드의 핵심은 세 줄입니다. FastMCP("demo")로 서버를 만들고, @mcp.tool() 데코레이터로 함수를 도구로 등록하고, mcp.run(transport="stdio")로 실행합니다. 독스트링의 인자 설명이 그대로 도구 설명이 되므로, 모델이 도구를 이해할 수 있도록 명확히 적는 것이 중요합니다.

실행은 다음과 같습니다.

python server.py

Inspector로 검증하기

서버가 제대로 도구를 노출하는지 확인하지 않고 Claude에 붙이면, 문제가 생겼을 때 원인을 찾기 어렵습니다. 공식 도구인 MCP Inspector를 쓰면 별도 설치 없이 서버를 띄워 볼 수 있습니다.

npx @modelcontextprotocol/inspector python server.py

브라우저에서 도구 목록이 보이고 add를 직접 호출해 결과가 나오면 성공입니다. 여기서 도구가 안 보이면 코드 문제이니, Claude 연결로 넘어가기 전에 먼저 잡아야 합니다.

Claude에 연결하기

검증이 끝났으면 Claude에 붙입니다. Claude Desktop은 설정 파일에 서버를 등록합니다. macOS 기준 경로는 다음과 같습니다.

~/Library/Application Support/Claude/claude_desktop_config.json

파일의 mcpServers 키 아래에 서버를 추가합니다. 경로는 반드시 절대 경로를 씁니다.

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": ["/ABSOLUTE/PATH/TO/server.py"]
    }
  }
}

저장 후 Claude Desktop을 재시작하면 도구가 잡힙니다. Claude Code를 쓴다면 CLI로 등록하는 방법이 더 간단합니다.

claude mcp add demo -- python /ABSOLUTE/PATH/TO/server.py

CLI 플래그는 자주 갱신되므로, 등록 전에 claude mcp add --help로 현재 옵션을 한 번 확인하는 것을 권장합니다.

전송 방식: stdio와 Streamable HTTP

스펙은 두 가지 표준 전송을 정의합니다. 로컬에서 클라이언트가 서버를 하위 프로세스로 띄우고 표준 입출력으로 통신하는 stdio, 그리고 독립 프로세스가 HTTP 엔드포인트로 여러 클라이언트를 받는 Streamable HTTP입니다. 로컬 도구라면 stdio가 가장 간단합니다.

한 가지 주의할 점이 있습니다. 예전 HTTP+SSE 전송은 더 이상 표준이 아닙니다. 공식 스펙은 Streamable HTTP가 2024-11-05 버전의 HTTP+SSE 전송을 대체한다고 명시합니다. 오래된 튜토리얼을 보고 SSE 전송으로 시작하지 마십시오.

보안과 흔한 실수

도구는 곧 코드 실행입니다. 공식 스펙은 호스트가 어떤 도구든 호출 전에 명시적 사용자 동의를 받아야 한다고 규정합니다. 서버를 만드는 입장에서도 다음을 지켜야 합니다.

• 도구 입력을 서버에서 검증하십시오. 모델이나 클라이언트가 보낸 인자가 항상 안전하다고 가정하면 안 됩니다.
• stdio 서버에서는 표준 출력에 MCP 메시지 외의 내용을 쓰면 안 됩니다. 로그는 반드시 표준 에러로 보내십시오. print() 한 줄이 JSON-RPC 스트림을 망가뜨립니다. 타입스크립트 예제가 console.log 대신 console.error를 쓰는 이유입니다.
• HTTP 전송을 쓴다면 DNS 리바인딩 공격을 막기 위해 Origin 헤더를 검증하고, 로컬 실행 시 0.0.0.0이 아니라 127.0.0.1에 바인딩하며, 모든 연결에 인증을 붙이십시오.

타입스크립트로 만들 때는 @modelcontextprotocol/sdk를 쓰고, peer 의존성으로 zod를 함께 설치합니다. 공식 튜토리얼은 zod@3을 고정합니다.

npm install @modelcontextprotocol/sdk zod@3

현재 도구 등록 메서드는 registerTool()입니다. 빌드 후 연결하는 점, inputSchema를 zod 필드의 평범한 객체로 넘기는 점만 기억하면 파이썬 버전과 흐름은 같습니다.

이런 사람에게 추천합니다

사내 API나 데이터베이스를 Claude에 안전하게 노출하고 싶은 개발자, 반복 작업을 도구로 묶어 AI 워크플로우에 붙이려는 팀에게 MCP 서버 제작은 가장 효율적인 출발점입니다. 다만 외부에 HTTP로 공개하는 서버라면 인증과 권한 설계를 충분히 마친 뒤에 배포하십시오. 두 SDK 모두 차세대 버전(v2)이 사전 알파 단계에 있으므로, 지금은 안정 버전인 1.x API로 시작하는 것이 안전합니다.

마치며

MCP 서버 만들기의 핵심은 세 단계로 압축됩니다. FastMCP로 도구를 등록하고, Inspector로 검증하고, 설정 파일이나 CLI로 Claude에 연결하는 것입니다. 처음에는 stdio 로컬 서버로 시작해 도구 하나를 확실히 동작시키고, 그다음에 리소스와 프롬프트, HTTP 전송으로 확장하십시오. 오늘 당장 할 수 있는 한 가지는, 위의 add 서버를 만들어 Inspector에서 호출 결과를 직접 확인하는 것입니다.

참고자료

• MCP Specification: 프로토콜 개요, 호스트·클라이언트·서버 역할, JSON-RPC 기반
• Build an MCP Server - 공식 튜토리얼: FastMCP 서버 코드, 타입스크립트 예제, 실행 방법
• Server Concepts: 도구·리소스·프롬프트의 정의와 제어 주체
• Transports (2025-11-25): stdio·Streamable HTTP 정의, HTTP+SSE 대체, 보안 권고
• Python SDK - GitHub: 설치 명령, FastMCP API, 개발용 CLI
• MCP Inspector: 서버 검증용 도구와 실행 명령
• Connect Local Servers - 공식 문서: Claude Desktop 설정 경로와 JSON 형식