안녕하세요. 저는 사내에서 LLM 기반 자동화 에이전트를 운영하면서 매일 MCP 서버를 만져왔습니다. 처음 MCP를 접했을 때는 "그게 그렇게 특별한가?" 했는데, 직접 도구를 만들어 Claude Code에 등록해 보니 그 진가를 깨달았습니다. 이 글에서는 API 호출 한 번 해본 적 없는 분도 따라 할 수 있도록, 가장 단순한 형태의 MCP 서버를 만들고 Claude Code에 등록하는 전 과정을 스크린샷 대신 텍스트로 자세히 설명드립니다. 마지막에는 HolySheep AI로 Claude Sonnet 4.5를 호출할 때의 비용을 공식 가격과 비교해 보고, 자주 발생하는 오류 4가지의 해결 코드도 함께 정리했습니다.
MCP가 정확히 무엇인가요?
MCP는 "Model Context Protocol"의 약자로, Anthropic이 2024년 말에 오픈소스로 공개한 표준 통신 규격입니다. 쉽게 말해 "AI 모델이 외부 도구(함수)를 호출할 때 사용하는 USB-C 규격"이라고 보시면 됩니다. 기존에는 모델마다 함수 호출 형식(tools, functions, tool_use 등)이 제각각이라 도구를 한 번 만들면 Claude, GPT, Gemini마다 별도 어댑터를 작성해야 했습니다. MCP는 이 문제를 해결하기 위해 도구 서버와 모델 클라이언트 사이의 JSON-RPC 기반 프로토콜을 표준화했습니다.
- 서버: 도구(함수)를 등록하고 JSON-RPC로 응답
- 클라이언트: Claude Code, Cursor, Cline 등이 서버에 연결
- 전송: stdio(표준 입출력) 또는 SSE(서버 전송 이벤트)
사전 준비물 체크리스트
- Python 3.10 이상 설치 (터미널에서
python --version입력해 확인) - pip 패키지 관리자 (Python 설치 시 자동 포함)
- Claude Code CLI 설치 (Anthropic 공식 문서 참고)
- 터미널(명령 프롬프트, PowerShell, iTerm2 등) 사용 경험
- HolySheep AI 계정의 API 키 — 지금 가입하면 무료 크레딧이 즉시 제공됩니다
Step 1: 작업 폴더 만들기
먼저 프로젝트를 담을 폴더를 만듭니다. 터미널을 열고 아래 명령을 한 줄씩 실행하세요. Windows는 PowerShell, macOS/Linux는 그대로 입력하면 됩니다.
mkdir mcp-holysheep-demo
cd mcp-holysheep-demo
python -m venv .venv
source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
pip install --upgrade pipStep 2: 필요한 라이브러리 설치
MCP 공식 파이썬 SDK와 HTTP 호출용 httpx를 설치합니다.
pip install mcp httpx
설치 확인
pip show mcp | grep Version정상이라면 Version: 1.x.x 형태의 출력이 나옵니다. 저는 이 단계에서 pip install mcp만 입력해 SDK가 누락된 채로 실행해 본 적이 있는데, 30분 동안 디버깅한 기억이 있어 강조합니다. 반드시 mcp와 httpx 둘 다 설치하세요.
Step 3: 첫 번째 MCP 서버 작성
이제 메모장을 열어 server.py 파일을 만들고 아래 코드를 그대로 붙여넣으세요. 이 서버는 두 가지 도구를 노출합니다. (1) 도시명을 받아 가상의 날씨를 돌려주는 함수, (2) HolySheep AI의 Claude Sonnet 4.5 모델에 텍스트를 보내 요약하는 함수입니다.
# server.py
import os
import httpx
from mcp.server.fastmcp import FastMCP
MCP 서버 인스턴스 생성
mcp = FastMCP("holysheep-demo-server")
1) 가상의 날씨 조회 도구
@mcp.tool()
async def get_weather(city: str) -> str:
"""입력한 도시의 현재 기온과 날씨 상태를 반환합니다."""
sample = {
"서울": {"temp": 18, "desc": "맑음"},
"부산": {"temp": 21, "desc": "구름 많음"},
"제주": {"temp": 23, "desc": "흐림"},
}
info = sample.get(city, {"temp": 20, "desc": "보통"})
return f"{city}의 기온은 {info['temp']}도, 상태는 {info['desc']}입니다."
2) HolySheep AI Claude Sonnet 4.5 호출 도구
@mcp.tool()
async def summarize_text(text: str, max_words: int = 80) -> str:
"""긴 한국어 텍스트를 Claude Sonnet 4.5로 요약합니다."""
api_key = os.environ.get("HOLYSHEEP_API_KEY", "YOUR_HOLYSHEEP_API_KEY")
base_url = "https://api.holysheep.ai/v1"
payload = {
"model": "claude-sonnet-4.5",
"max_tokens": 512,
"messages": [
{"role": "system", "content": f"다음 텍스트를 {max_words}단어 이내 한국