핵심 요약
- FastMCP로 도구 3개를 만든 Python 파일 하나면 서버가 완성됩니다
- claude mcp add로 stdio 서버를 등록하고 /mcp로 연결을 확인합니다
- 조회 전용 권한, 5초 타임아웃, 환경변수 비밀값 전달을 지킵니다
핵심 요약
Django 사이트 50개의 상태를 Claude Code에서 조회하려면 Python 파일 하나와 명령어 한 줄이면 됩니다. 공식 Python SDK의 FastMCP로 stdio 서버를 만들고, claude mcp add로 등록하세요. MCP 소개 문서에 따르면 MCP는 도구, 리소스, 프롬프트를 표준 방식으로 모델에 노출하는 오픈 프로토콜입니다. 이 글의 예제에서는 그중 "도구"만 씁니다. 사이트마다 헬스 체크 URL을 호출하는 함수를 도구로 노출하는 방식입니다.
설계: 무엇을 도구로 만들까
도구는 두 개면 충분합니다. 하나는 list_sites로, 관리하는 사이트 목록과 URL을 돌려줍니다. 다른 하나는 check_site로, 사이트 이름을 받아 HTTP 상태 코드와 응답 시간을 반환합니다. 50개를 한꺼번에 보고 싶을 때를 위해 check_all도 하나 추가합니다. 이 도구는 비동기로 병렬 호출해서 결과를 요약합니다.
Django 쪽에는 /healthz/ 같은 가벼운 엔드포인트가 있다고 가정합니다. DB 연결 확인 정도만 하는 뷰면 충분합니다. 사이트 목록은 코드에 박지 않고 sites.json으로 분리해 두면 사이트가 늘어도 서버 코드를 건드릴 필요가 없습니다.
{
"blog": "https://blog.example.com/healthz/",
"shop": "https://shop.example.com/healthz/"
}
서버 코드 작성
MCP Python SDK 저장소의 퀵스타트는 mcp.server.fastmcp에서 FastMCP를 가져와 서버 객체를 만듭니다. 함수에 @mcp.tool() 데코레이터를 붙이면 도구가 됩니다. 같은 문서에 따르면 mcp.run()으로 실행합니다. 아래 코드는 이 패턴을 따른 예시입니다. HTTP 호출에는 httpx를 가정했습니다.
import asyncio, json, time
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("django-sites")
SITES = json.load(open("sites.json"))
async def _check(client, name, url):
start = time.perf_counter()
try:
r = await client.get(url, timeout=5)
return {"site": name, "status": r.status_code,
"ms": round((time.perf_counter() - start) * 1000)}
except httpx.HTTPError as e:
return {"site": name, "status": "error", "detail": type(e).__name__}
@mcp.tool()
def list_sites() -> list[str]:
"""등록된 Django 사이트 이름 목록"""
return list(SITES)
@mcp.tool()
async def check_site(name: str) -> dict:
"""사이트 하나의 헬스 체크 결과"""
if name not in SITES:
return {"site": name, "status": "unknown site"}
async with httpx.AsyncClient() as c:
return await _check(c, name, SITES[name])
@mcp.tool()
async def check_all() -> list[dict]:
"""전체 사이트를 병렬로 점검"""
async with httpx.AsyncClient() as c:
return await asyncio.gather(*[_check(c, n, u) for n, u in SITES.items()])
if __name__ == "__main__":
mcp.run()
stdio 서버에서는 print()로 표준 출력에 로그를 남기면 안 됩니다. 표준 출력이 프로토콜 메시지 통로이기 때문입니다. 디버깅 로그는 stderr나 파일로 보내세요. 함수의 독스트링과 타입 힌트는 모델이 도구를 이해하는 단서가 되니 구체적으로 쓰는 편이 좋습니다.
Claude Code에 등록하기
Claude Code 공식 문서에 따르면 로컬 stdio 서버는 claude mcp add [options] <name> -- <command> [args...] 형식으로 추가합니다. 이름 뒤의 --가 Claude Code 옵션과 서버 실행 명령을 구분합니다. 따라서 이 서버는 아래처럼 등록합니다.
claude mcp add --transport stdio django-sites -- python /path/to/server.py
가상환경을 쓴다면 그 환경의 python 절대 경로를 지정하세요. 같은 문서에는 --env 옵션으로 환경변수를 넘기는 예시도 있습니다. 헬스 체크에 토큰이 필요하면 코드에 쓰지 말고 이 옵션으로 전달하는 편이 안전합니다. 등록 후 Claude Code 안에서 /mcp를 실행하면 서버 연결 상태를 볼 수 있습니다.
참고로 같은 문서와 SDK 퀵스타트에는 HTTP 전송 방식도 나옵니다. mcp.run(transport="streamable-http")로 띄우고 claude mcp add --transport http my-server http://localhost:8000/mcp로 등록하는 식입니다. 한 대의 점검용 서버를 팀이 함께 쓴다면 HTTP가, 개인 PC에서 쓴다면 stdio가 간단합니다.
실제로 쓰는 모습과 주의점
등록이 끝나면 Claude Code에 "전체 사이트 상태 알려줘"라고 말하면 됩니다. 그러면 모델이 check_all을 호출하고 결과를 요약합니다. 예를 들어 "응답이 1초 넘는 사이트만 골라줘", "에러 난 사이트의 최근 배포 커밋을 찾아봐"처럼 후속 질문도 이어갈 수 있습니다. 코드 저장소를 이미 다루고 있는 Claude Code라서 점검 결과와 코드 조사를 한 대화 안에서 할 수 있다는 점이 장점입니다.
운영할 때는 다음을 지키세요.
| 항목 | 권장 |
|---|---|
| 권한 | 조회 전용 도구만 노출. 재시작·배포 같은 쓰기 작업은 분리 |
| 타임아웃 | 요청당 5초 안팎으로 제한해 한 사이트가 전체를 막지 않게 함 |
| 비밀값 | 코드나 sites.json에 두지 말고 환경변수로 전달 |
| 출력 크기 | 정상 사이트는 요약하고 이상 사이트만 상세히 반환 |
실천 가이드
pip install "mcp[cli]" httpx로 SDK를 설치합니다. 정확한 설치 방법과 버전은 SDK 저장소에서 확인하세요.- 각 Django 사이트에 가벼운
/healthz/뷰를 추가하고, 사이트 목록을sites.json으로 정리합니다. - 위 코드를
server.py로 저장하고, 먼저mcp dev server.py로 SDK의 인스펙터에서 도구가 동작하는지 확인합니다. 이 명령은 SDK 문서에 안내되어 있습니다. claude mcp add --transport stdio django-sites -- python /path/to/server.py로 등록하고/mcp로 연결을 확인합니다.- 조회 도구가 안정적이면 로그 조회나 최근 배포 이력 같은 도구를 하나씩 늘립니다.
작게 시작해서 도구를 하나씩 늘려가는 방식이 가장 안전합니다. 처음부터 쓰기 권한을 주지 않으면 모델이 잘못 판단해도 피해가 없습니다.
자주 묻는 질문
Q. stdio MCP 서버에서 print()로 로그를 남겨도 되나요?
안 됩니다. 표준 출력이 프로토콜 메시지 통로이기 때문입니다. 디버깅 로그는 stderr나 파일로 보내세요.
Q. Claude Code에 로컬 MCP 서버는 어떻게 등록하나요?
claude mcp add --transport stdio django-sites -- python /path/to/server.py 형식으로 등록합니다. 이름 뒤의 --가 Claude Code 옵션과 서버 실행 명령을 구분합니다. 등록 후 /mcp로 연결 상태를 볼 수 있습니다.
Q. stdio와 HTTP 전송 방식은 어떻게 고르나요?
한 대의 점검용 서버를 팀이 함께 쓴다면 HTTP가, 개인 PC에서 쓴다면 stdio가 간단합니다. HTTP는 mcp.run(transport="streamable-http")로 띄우고 claude mcp add --transport http로 등록합니다.
참고 자료
- Model Context Protocol
- GitHub (modelcontextprotocol/python-sdk)
- Anthropic
- GitHub (modelcontextprotocol/python-sdk)
이 글은 웹 검색으로 확인한 위 출처를 바탕으로 AI(claude-sonnet-5-5)가 작성했습니다. 수치·가격은 출처 원문에서 다시 확인하세요.