MCP 서버 만들기 입문 — 처음부터 Claude에 연결하기까지

MCP란 무엇인가 — AI와 외부 도구를 잇는 공통 언어

MCP(Model Context Protocol)는 Anthropic이 2024년 말 공개한 오픈 표준 프로토콜이다. 한 마디로 “AI 모델이 외부 도구나 데이터를 일관된 방식으로 주고받을 수 있도록 정의한 약속”이다.

기존에는 Claude나 GPT 같은 AI 모델에 외부 기능을 붙이려면 서비스마다 방식이 달랐다. MCP는 이 제각각인 통신 방식을 하나의 표준으로 묶는다. USB 포트처럼, 같은 규격이면 어떤 기기든 연결되는 것과 같은 원리다.

2026년 현재 MCP는 Claude Desktop뿐 아니라 VS Code, Cursor, Zed 같은 코드 에디터와 다양한 AI 에이전트 프레임워크에서 지원한다. 공식 Python SDK는 mcp 패키지로 PyPI에 배포되어 있으며, 1.x 안정 버전과 2.0 알파 버전이 함께 유지 중이다.

MCP 서버의 두 핵심 개념 — tools와 resources

MCP 서버가 AI에게 제공하는 기능은 두 가지로 나뉜다.

tools (도구)는 AI가 직접 호출해 결과를 받는 함수다. 파일 읽기, URL 데이터 조회, DB 검색처럼 능동적인 작업이 여기에 해당한다. Python 함수와 거의 같은 개념이다.

resources (리소스)는 AI가 참조하는 정적 데이터 소스다. 설정 문서나 API 명세처럼 “읽기 전용 배경 정보”가 resources다. tools가 “버튼”이라면 resources는 “참고 자료집”이다.

이 두 개념이 MCP 서버의 전부다. Python 함수에 데코레이터 한 줄을 붙이는 것만으로 tools를 등록할 수 있다.

Python으로 MCP 서버 직접 만들기

텍스트를 받아 글자 수를 반환하는 간단한 MCP 서버 예시다. FastMCP(빠르게 MCP 서버를 만드는 고수준 인터페이스)를 사용하며, Python 3.10 이상과 mcp 패키지가 필요하다.

# server.py
from mcp.server.fastmcp import FastMCP

# MCP 서버 인스턴스 생성
mcp = FastMCP("my-text-tools")

@mcp.tool()
def count_chars(text: str) -> str:
    """
    텍스트의 글자 수(공백 포함/제외)를 반환합니다.
    text: 분석할 텍스트 문자열
    """
    total = len(text)
    without_spaces = len(text.replace(" ", ""))
    return f"전체: {total}자 / 공백 제외: {without_spaces}자"

@mcp.resource("text://help")
def get_help() -> str:
    """도구 사용법을 반환하는 리소스"""
    return "count_chars(text) — 텍스트 글자 수 반환"

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

@mcp.tool()이 붙은 함수가 AI가 호출하는 도구가 된다. 함수 이름, 파라미터 타입, 독스트링(함수 설명 주석)이 자동으로 도구 스펙으로 변환된다. 별도 스키마 정의 없이 Python 타입 힌트만으로 동작하는 것이 FastMCP의 핵심이다. @mcp.resource()는 URI 형식으로 정적 데이터를 등록한다.

Claude Desktop 연결 설정

서버 파일을 만들었으면 Claude Desktop에 연결해야 한다. 설정 파일 claude_desktop_config.json의 위치는 운영체제마다 다르다.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

이 파일에 아래처럼 서버 경로를 추가한다.

{
  "mcpServers": {
    "my-text-tools": {
      "command": "python",
      "args": ["/절대/경로/server.py"]
    }
  }
}

command는 실행 명령(python, node 등), args는 그 인자 배열이다. 여러 서버를 등록하려면 mcpServers 안에 이름을 다르게 해서 항목을 추가한다. 설정 저장 후 Claude Desktop을 완전히 종료하고 재시작하면 연결이 완료된다. 채팅창 좌하단 망치 아이콘에 서버 이름이 보이면 정상이다.

연결이 안 될 때 확인할 것들

Python 경로 문제: 가상환경(virtualenv나 conda)을 쓰고 있다면 claude_desktop_config.json의 command에 해당 환경의 절대 경로를 적어야 한다. "python"만 적으면 시스템 기본 Python이 실행돼 패키지를 못 찾는다.

타입 힌트 누락: FastMCP는 파라미터 타입 힌트(text: str)를 읽어 JSON 스키마를 자동 생성한다. 타입 힌트가 없으면 스키마 생성에 실패하므로 모든 파라미터에 타입을 명시한다.

재시작 습관: 설정 파일을 바꿨다면 Claude Desktop을 트레이에서도 완전히 종료하고 다시 시작해야 반영된다. 오류 원인이 불분명하면 로그 파일(~/Library/Logs/Claude/ macOS, %APPDATA%\Claude\logs\ Windows)을 먼저 살펴본다.

자주 묻는 질문

Q1) MCP 서버를 만들려면 프로그래밍을 꼭 알아야 하나요?

기본적인 Python 문법(함수 선언, 타입 힌트)을 알면 진입이 가능합니다. FastMCP 덕분에 MCP 통신 내부 구조는 몰라도 됩니다. 완전 비프로그래머라면 Claude에게 코드를 대신 작성해달라고 요청하는 방식이 현실적입니다.

Q2) Node.js로도 MCP 서버를 만들 수 있나요?

네. 공식 TypeScript/JavaScript SDK(@modelcontextprotocol/sdk)가 NPM에 배포되어 있습니다. Python SDK와 구조가 유사하며, TypeScript 타입 안전성을 선호한다면 Node.js 쪽이 편할 수 있습니다.

Q3) MCP 서버는 인터넷에 공개해야 동작하나요?

아닙니다. 기본 통신 방식인 stdio(표준 입출력)를 사용하면 서버는 로컬 PC에서만 실행됩니다. Claude Desktop이 서버 프로세스를 직접 띄우는 구조라 외부 포트를 열 필요가 없습니다. 원격 운영이 필요하면 SSE 또는 Streamable HTTP transport를 선택하면 됩니다.

Q4) 서버 하나에 tools를 몇 개까지 등록할 수 있나요?

기술 제한은 없지만 도구가 너무 많으면 AI가 선택에 혼동할 수 있습니다. 실용적으로는 서버 하나에 15~20개 이하로 유지하고 기능 단위로 서버를 분리하는 방식이 권장됩니다.

Q5) mcp 패키지 버전은 어떤 것을 써야 하나요?

2026년 6월 기준으로 1.x가 안정 버전이고, 2.0 알파가 실험적으로 배포 중입니다. 처음이라면 pip install mcp로 안정 버전을 설치하는 것이 무난합니다. 2.0 알파는 API 변경이 잦아 프로덕션에는 아직 권장하지 않습니다.