나만의 MCP 서버 구축하기 (그리고 배포하기)

LLM API를 MCP 도구로 변환하는 완전하고 작동하는 MCP 서버 — 가르치기 위해 만들어졌습니다. 로컬로는 stdio를 통해 Claude Desktop / Claude Code에서 실행되며, 원격으로는 HTTP를 통해 배포 후 실행됩니다.

Groq 기반 — 빠른 추론, OpenAI 호환 API, 워크숍에서 학생들이 한꺼번에 사용해도 버틸 수 있는 무료 티어.

모든 것이 하나의 파일에 있습니다: server.py. 주석 포함 약 170줄.

파트 0 — MCP가 무엇인지, 1분 안에

MCP(Model Context Protocol)는 AI 클라이언트에 새로운 능력을 부여하는 표준 방법입니다. 서버를 작성하면 모든 MCP 클라이언트가 사용할 수 있습니다.

서버는 세 가지를 노출할 수 있습니다:

두 가지 전송 방식:

• stdio — 클라이언트가 서버를 하위 프로세스로 실행하고 stdin/stdout으로 통신합니다. 로컬 전용. 네트워크 없음. MCP 서버의 90%가 이렇게 실행됩니다.

• streamable HTTP — 서버가 URL의 웹 서비스로 동작합니다. 다른 사람(또는 호스팅된 클라이언트)이 사용할 수 있도록 배포하는 방식입니다.

동일한 server.py가 둘 다 수행합니다. 이것이 핵심입니다.

파트 1 — 우리가 만들 것

llm-toolkit: 어떤 MCP 클라이언트에든 4개의 LLM 기반 도구를 제공하는 MCP 서버입니다.

게다가 하나의 리소스(config://server-info)와 하나의 프롬프트(code_review)가 있어 학생들이 세 가지 프리미티브를 모두 볼 수 있습니다.

파트 2 — 로컬에서 실행하기

설정

python -m venv .venv

Windows: .\venv\Scripts\activate — macOS/Linux: source .venv/bin/activate

pip install -r requirements.txt

console.groq.com에서 무료 키를 받으세요 → API Keys. 그런 다음 .env.example을 .env로 복사하고 붙여넣으세요:

cp .env.example .env

.env는 gitignore에 있습니다. 서버가 자신의 디렉토리에서 자동으로 로드하므로, 클라이언트가 어디서 실행하든 작동합니다.

연결 전에 검사하기

MCP Inspector는 가장 좋은 교육 도구입니다 — 도구 목록을 보여주고 AI 클라이언트 없이 직접 도구를 호출할 수 있습니다.

npx @modelcontextprotocol/inspector python server.py

출력된 URL을 열고 Connect를 클릭한 다음 List Tools를 클릭하세요. 네 가지 도구가 모두 보입니다.

파트 3 — 클라이언트에 연결하기

Claude Code

claude mcp add llm-toolkit -e GROQ_API_KEY=gsk_... -- python /absolute/path/to/server.py

또는 프로젝트 루트에 .mcp.json을 커밋하여 팀 전체가 사용할 수 있게 하세요 — .mcp.json.example 참고.

Claude Desktop

claude_desktop_config.json을 편집하세요:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

.mcp.json.example에서 mcpServers 블록을 붙여넣은 다음, Claude Desktop을 완전히 종료하고 다시 열어주세요. 도구 아이콘 아래에 도구가 나타납니다.

절대 경로만 사용하세요. 로컬 MCP 서버가 "나타나지 않는" 가장 큰 이유는 상대 경로 때문입니다 — 클라이언트의 작업 디렉토리가 당신의 디렉토리와 다릅니다. python 바이너리(.venv/bin/python)와 server.py 모두 전체 경로를 사용하세요.

파트 4 — 배포하기

하나의 플래그로 HTTP 모드로 전환:

python server.py --http

서버가 이제 http://localhost:8000/mcp에 있습니다. 동일한 명령을 컨테이너에 넣어 배포하세요.

옵션 A — Render, Docker 없음 (권장)

Render는 네이티브 Python 런타임을 제공합니다. Dockerfile이나 컨테이너 빌드가 필요 없습니다. requirements.txt를 설치하고 시작 명령을 직접 실행합니다. 이것이 랩탑에서 공개 URL까지 가장 빠른 경로입니다.

1단계 — 코드를 GitHub에 올리세요.

git init && git add -A && git commit -m "MCP server"

github.com/new에서 빈 저장소를 만든 다음:

git remote add origin https://github.com/<you>/llm-toolkit-mcp.git && git push -u origin main

2단계 — 서비스를 생성하세요.

Render 대시보드 → New → Web Service → 저장소를 연결하세요. Render가 render.yaml을 읽고 자체적으로 구성합니다:

3단계 — 키를 설정하세요. 대시보드 → Environment → GROQ_API_KEY를 추가하세요. render.yaml에서 sync: false로 표시되어 있으므로 대시보드에만 존재하고 git에는 절대 들어가지 않습니다.

4단계 — 배포하세요. 공개 엔드포인트는 https://<your-app>.onrender.com/mcp입니다.

의도적으로 상태 점검 없음. GET /mcp는 설계상 계속 열려 있는 SSE 스트림을 엽니다. 상태 점검을 하면 스트림이 멈추고 Render는 타임아웃을 서비스 중단으로 간주하여 재시작 루프에 빠집니다. healthCheckPath가 생략되면 Render는 프로세스가 $PORT를 바인딩하는지만 확인합니다 — 이 서버에 올바른 검사입니다.

무료 티어 인스턴스는 약 15분 유휴 상태 후 절전 모드로 전환됩니다. 절전 후 첫 번째 호출은 깨어나는 동안 약 30~50초가 걸립니다. 일부 MCP 클라이언트는 그 전에 타임아웃되어 서버가 고장났다고 보고합니다. 수업 시작 전에 curl로 워밍업하세요.

옵션 B — Docker 없는 다른 호스트

옵션 C — Fly.io

fly launch --no-deploy

fly secrets set GROQ_API_KEY=gsk_...

fly deploy

엔드포인트: https://<your-app>.fly.dev/mcp n

옵션 D — 모든 컨테이너 호스트

Dockerfile은 컨테이너를 원하는 호스트를 위해 유지됩니다. Railway, Cloud Run, ECS, VPS에서 작동:

docker build -t llm-toolkit-mcp .

docker run -p 8000:8000 -e GROQ_API_KEY=gsk_... llm-toolkit-mcp

배포 확인

하나의 curl로 서버가 살아 잇고 MC를 말하는 지 확인:

curl -X POST https://your-app.onrender.com/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'

llm-toolkit을 이름으로 하는 serverInfo 블록이 반환되어야 합니다.

배포된 서버에 클라이언트 연결하기

claude mcp add --transport http llm-toolkit https://your-app.onrender.com/mcp

학생들이 그 한 줄을 붙여넣으면 즉시 네 가지 도구를 사용할 수 있습니다. 이것이 워숍 전체의 보람찬 순간입니다 — 설치 없이, 키 없이, 자신의 머신에 Python 없이.

공개적으로 공유하기 — 먼저 읽어보세요

인증 없는 배포된 MCP 서버는 전체 인터넷에 공개되어 있습니다. UR를 알면 누구나 도구를 호출할 수 있과, 모든 호출은 여러분의 Groq 할당량을 사용합니다.

워크숍에서는 보통 찮ㅎ며, Groq의 무로 티어 덕분에 찮습니다: 할당량이 소진되면 요금이 부과되지 않고 HTTP 429 오류만 발생합니다. 실패 모드는 "도구가 응답하지 않음"이지 "깜짝 청구서"가 아닙니다.

유료 키를 넣는 순간 문제가 시작됩니다. 그 때는 UR를 공유하기 전에 인증을 추하세요 — MCP SDK의 auth 매개변수 또는 앞에 API 게이트웨이를 두세요.

어는 쪽으로든 지킬 만한 두 가지 습관:

• UR를 반-비밀로 취급하세요. 수업에서 공유하되, 공개적으로 포스팅하지 마세요.

• 워크숍 후에 키를 로테이션하세요. 대시보드에서 한 번 클릭하면 됩니다.

파트 5 — 명시적으로 가르칠 가치가 있는 것들

독스트링이 API입니다. 모델은 독스트링과 타입 힌트를 읽고 도구를 선택합니다. 모호한 독스트링은 절대 호출되지 않는 도구를 의미합니다. 이는 전체 파일에서 가장 중요도가 높은 요소입니다.

하나의 함수가 공급자를 담당합니다. 모든 도구는 call_llm()을 호출합니다. Groq를 OpenAI, Anthropic, 또는 로컬 Ollma로 교채하는 것은 그 하나의 함수만 편집하면 됩니다 — 네 가지 도구는 절대 변하지 않습니다. 이 것을 라이브로 시연하면 인상적입니다.

에러는 문자열로 반환하고, 발생시키지 마세요.call_llm은 GroqError를 잡아 메시지를 텍스트로 반환합니다. 클라이언트는 죽은 도구 호출 대신 사용자에게 실제 에러를 보여줍니다.

**stateless_http=True**는 스티키 세션이 없음을 의미하므로 서버가 로드 밸런서 뒤에서 확장됩니다. 세션별 상태를 추가하는 경우에만 끄세요.

키를 커밋하지 마세요. .env는 gitignore에 있으며, render.yaml은 sync: false를 사용하고, Fly는 fly secrets를 사용합니다.

공개 HTTP 서버는 기본적으로 열려 있습니다. 이 서버는 인증이 없습니다 — 데모에는 괜찮지만 프로덕션에는 적합하지 않습니다. 실제 배포는 SDK의 auth 매개변수를 통한 OAuth 또는 API 게이트웨 앞에 두어 추가합니다.

버전 드리프트는 현실입니다. MCP Python SDK 2.0에서 FastMCP가 MCPServer로 이릉이 바뀌었습니다. 온라인 튜토리얼의 대부분은 여전히 FastMCP를 보여주며 새로 설치하면 실패합니다. 블로그 포스트를 신뢰하는 대신 설치된 패키지를 읽는 법을 가르치기에 좋은 기회입니다.

파트 6 — 수업 과제

1. sentiment(text) 도구를 추가하세요. (summarize를 복사하고, 시스템 프롬프트를 바꾸세요.) n2. ask_llm이 max_tokens 인자를 받도롣 하고, Inspector에서 스키마가 자동으로 업데이트되는 것을 확인하세요.

2. 어떤 도구도 건드리지 않고 call_llm을 다른 공급자로 바꾸세요.

3. 프로세스가 처리한 도구 호출 수를 보고하는 리소스 config://usage를 추가하세요. (힌트: 모듈 수준 카운터.)

4. 의도적으로 독스트링을 망가뜨리고, 모델이 그 도구를 사용하도록 요청하세요. 도구를 선택하지 못하는 것을 관찰하세요. 이것이 교훈입니다.

파트 7 — 다른 사람들이 사용하게 만들기

도구를 다른 사람에게 전달하는 것은 세 가지 별개의 문제입니다: 접근 가능, 연결 가능, 발견 가능. 이 순서로 해결하세요.

1. 접근 가능. localhost에 있는 서버는 정확히 한 사람만 사용할 수 있습니다. 배포하고(파트 4) 공개 URL을 얻으세요. 이것이 완료되지 않으면 아래의 어떤 것도 작동하지 않습니다.

2. 연결 가능. 사람들에게 USING-IT.md를 제공하세요 — Claude Code, Claude Desktop, Cursor용 복사-붙여넣기 설정과 문제 해결 표가 포함된 독립형 페이지입니다. 워크숍의 경우 원격 경로를 사용하는 것이 좋습니다: 학생들은 한 줄을 붙여넣고 Python, 저장소, 자신의 API 키 없이도 작동하는 도구를 얻습니다.

3. 발견 가능. 수업뿐만 아니라 낯선 사람도 찾길 원하는 경우에만 해당됩니다:

레지스트리 요구 사항은 빠르게 변합니다 — 게시하기 전에 현재 MCP 레지스트리 문서에서 매니페스트 형식을 확인하세요.

솔직한 한계에 대한 참고. 사람들은 이미 할 수 없는 일을 해주는 MCP 서버를 채택합니다. 이 서버는 일반 LLM을 래핑하며, 대부분의 클라이언트에는 이미 내장되어 있습니다 — 프로토콜을 가르치는 데는 완벽하지만 제품으로는 약합니다. 당신의 데이터베이스, 당신의 내부 API, 또는 당신의 독점 데이터에 도달하는 서버가 실제 사용자를 얻습니다. 수업에서 말할 가치가 있습니다.

파트 8 — 프로덕션 준비를 위해 필요한 것

워크숍 버전과 프로덕션 버전은 MCP와 전혀 관련 없는 부분에서 다릅니다. 다음은 목록이며, 각 항목은 이 서버를 구축하는 동안 실제로 발생한 실패 때문에 존재합니다.

키 보호

공개 MCP 엔드포인트는 공개 지출 엔드포인트입니다: 모든 호출은 당신에게 비용이 듭니다.

인증은 기본적으로 꺼져 있어 서버가 무료 키로 워크숍을 위해 열려 있도록 합니다. 유료 키를 공개 URL에 연결하기 전에 켜십시오:

MCP_AUTH_TOKEN=$(python -c "import secrets;print(secrets.token_urlsafe(32))") python server.py --http

그러면 클라이언트는 Authorization: Bearer <token>을 보냅니다.

제공자 대처하기

모델은 예고 없이 폐기됩니다. Groq는 개발 중에 llama-3.3-70b-versatile을 제거했습니다 — 07:15에 작동했고 한 시간 후에 404가 떴습니다. 모든 도구가 한 번에 고장 났고, 404는 "서버가 고장 났다"가 아니라 "벤더가 이동했다"는 의미로 읽힙니다.

MODEL_CHAIN이 이 문제를 해결합니다: 모델을 찾을 수 없는 오류가 발생하면 실패하는 대신 다음 모델로 호출이 넘어갑니다. 잘못된 키, 속도 제한과 같은 다른 오류는 빠르게 실패합니다. 왜냐하면 다섯 모델에 걸쳐 재시도하는 것은 시간 낭비이기 때문입니다.

타임아웃(LLM_TIMEOUT_SECONDS)과 재시도(LLM_MAX_RETRIES)는 이미 백오프를 올바르게 구현한 벤더 SDK에 전달됩니다.

상태 확인

/health는 일반 JSON을 반환합니다. 절대 /mcp를 상태 확인하지 마십시오 — 설계상 열려 있는 SSE 스트림이므로 프로브가 중단되고, 플랫폼이 서비스를 죽은 것으로 간주하여 충돌처럼 보이는 재시작 루프가 발생합니다. 이로 인해 실제 디버깅 사이클이 소모되었습니다.

로깅

모든 것은 stderr로 전송되며, stdout으로는 절대 전송되지 않습니다. stdio 모드에서 stdout은 JSON-RPC 스트림을 전달하므로, 하나의 잘못된 print()가 프로토콜을 손상시킵니다. 이것은 MCP 서버를 디버깅하는 동안 가장 흔히 발생하는 오류입니다.

MCP 수준 미들웨어는 모든 메서드를 지속 시간과 함께 기록하며, 두 전송 방식 모두에서 작동합니다.

테스트 및 CI

pytest tests/는 API 키 없이 오프라인으로 실행되며 비용이 들지 않습니다. 속도 제한기의 윈도우 만료, 입력 제한, 모델 폴백, 도구 스키마 보존, 구성 유효성 검사를 다룹니다.

GitHub Actions는 3.11 및 3.12에서 스위트를 실행하고, 서버를 부팅하며, 전체 git 기록에서 커밋된 API 키를 스캔합니다 — 복구 불가능한 실패입니다. 키가 푸시되는 순간 공개되기 때문입니다.

알려진 한계

수업에 아직 부족한 점에 대해 솔직하게 말할 가치가 있습니다:

• 속도 제한은 프로세스별입니다. N개의 인스턴스로 확장하면 N배의 제한이 허용됩니다. 문제가 되기 전에 Redis로 교체하십시오.

• 사용자별 키가 아닌 하나의 공유 토큰입니다. 수업에는 괜찮지만 고객에게는 적합하지 않습니다.

• 사용량 측정이 없습니다. 누가 무엇을 사용했는지 알 수 없습니다.

• 무료 티어 콜드 스타트는 유휴 상태 후에도 30~50초가 걸립니다.

파일 맵