이 레터에서 다루는 것
- MCP 서버가 실제로 하는 일 3가지
- 날씨 정보를 알려주는 서버, 어떻게 만드는가
- Claude Desktop에 연결해서 실제로 받은 응답
MCP는 Anthropic이 공개한 표준으로, AI 모델이 외부 도구나 데이터에 연결되는 방식을 정합니다. 이 표준을 따라 만든 프로그램을 "MCP 서버"라고 부릅니다. MCP 서버를 하나 만들어두면, 그 서버가 제공하는 기능을 Claude 같은 AI 모델이 가져다 씁니다.
MCP 서버가 하는 일 — 3가지 기능
공식 문서에 따르면 MCP 서버는 세 가지 기능을 제공합니다. Resources는 파일처럼 읽어올 수 있는 데이터이고, Tools는 사용자 승인 아래 AI 모델이 호출해서 실행하는 함수이며, Prompts는 특정 작업을 돕는 미리 작성된 템플릿입니다. 공식 튜토리얼은 이 중 Tools에 집중합니다 — AI 모델이 호출해서 결과를 받아오는 함수를 만들어보는 방식입니다.
서버 하나에 세 가지가 전부 들어 있어야 하는 건 아닙니다. 어떤 서버는 Tools만 제공하고, 어떤 서버는 Resources만 제공합니다. 저희가 이번에 만든 날씨 서버도 Tools 두 개만 가진 구성입니다.
무엇을 만드는가 — 날씨 정보를 알려주는 서버
공식 튜토리얼은 "날씨 정보를 알려주는 서버"를 예제로 씁니다.
get_alerts·get_forecast, 두 가지 도구
도구(Tool) 두 개를 만듭니다 — 미국의 주(州)별 기상특보를 조회하는 get_alerts, 위도·경도를 넣으면 그 지점의 예보를 조회하는 get_forecast입니다. 데이터 출처는 미국 국립기상청(NWS)의 공개 API(api.weather.gov)이고, 별도 API 키 없이 호출됩니다.
서버를 만드는 과정
Python 공식 SDK를 쓰려면 Python 3.10 이상, Python MCP SDK 2.0.0 이상이 필요합니다. 저희 컴퓨터의 기본 Python은 3.9.6이라 이 조건에 못 미쳤습니다. 시스템 Python은 그대로 두고, uv(Python 프로젝트·환경을 관리하는 도구)로 별도 가상환경을 만든 뒤 그 안에 mcp[cli]·httpx2·pydantic을 설치했습니다. 터미널(컴퓨터에 명령어를 직접 입력하는 화면)에서 입력한 명령은 이렇습니다.
uv init weather && cd weather
uv venv && source .venv/bin/activate
uv add "mcp[cli]"
touch weather.py # 공식 문서 코드를 그대로 붙여넣는다
uv run weather.py # 서버가 stdio로 대기 시작서버를 켠 뒤, 공식 튜토리얼이 안내하는 순서로 넘어갔습니다.
Claude Desktop에 연결해서 실제로 물어봤습니다
워싱턴 D.C. 날씨를 물어봤습니다
Claude Desktop 설정 파일에 이 서버를 nws-weather-demo라는 이름으로 등록했습니다. 새 대화를 열어 "nws-weather-demo 서버를 써서 워싱턴 D.C.(38.8894, -77.0352) 날씨 알려줘"라고 물었습니다. Claude Desktop이 저희 서버를 불러 이렇게 답했습니다. 오늘 밤은 15°C(59°F)에 흐리고 비 올 확률 50%입니다. 일요일도 흐리고 비 확률 50%(최고 19°C·66°F), 일요일 밤은 비 확률 20%로 줄어들고(최저 16°C·60°F), 월요일부터는 비 소식 없이 최고 22°C(71°F)까지 오른다는 내용입니다.
캘리포니아 기상특보도 물어봤습니다
이어서 캘리포니아에 지금 발효 중인 기상특보가 있는지 물었습니다. 활성 특보 7건이 확인됐습니다. 대부분 남부 해안의 높은 파도·해안 침수 관련이고, 로스앤젤레스·벤투라·말리부·카탈리나섬 일대가 가장 주의할 지역으로 꼽혔습니다. 산타바바라 카운티 남부 해안에도 수요일까지 별도의 해변 위험 정보가 발효 중이었고, 내륙에서는 샌루이스 저수지 일대에 호수 강풍 주의보가 있었습니다. 숫자와 지명은 Claude가 미국 국립기상청 응답을 정리해 보여준 것입니다.
여섯 단계로 움직입니다
질문 하나가 답이 되기까지 — 6단계
공식 문서는 이 전체 과정이 여섯 단계로 움직인다고 설명합니다. ①사용자가 클라이언트(Claude Desktop)에 질문합니다. ②클라이언트가 그 질문을 Claude에 전달합니다. ③Claude는 어떤 도구를 써야 할지 분석해서 결정합니다. ④클라이언트는 MCP 서버를 통해 그 도구를 실행합니다. ⑤실행 결과가 다시 Claude에게 돌아옵니다. ⑥Claude는 그 결과를 자연어 답변으로 만들어 사용자에게 보여줍니다. 저희가 방금 Claude Desktop에서 물어봤을 때도 이 6단계 그대로 움직였습니다.
다른 언어로도 만들 수 있습니다
공식 튜토리얼은 Python을 포함해 TypeScript·Java·Kotlin·C#·Ruby·Rust·Go까지 8개 언어로 같은 예제를 제공합니다. 이번 레터는 Python 기준으로 다뤘습니다.
🔑 핵심
다음 발행에서 또 인사드리겠습니다. swimmingcode 드림.
이 레터에서 다룬 내용에 대해 궁금한 점이 있으시면 답장으로 알려주세요. 확인해서 답해드립니다.
의견을 남겨주세요