AI 코딩 에이전트 실전 (3/5) — MCP 서버 만들기: 스펙·예제·디버깅

-
AI 코딩 에이전트 실전 (3/5) — MCP 서버 만들기: 스펙·예제·디버깅

Cursor·Claude Code·VS Code Agent 모두가 채택한 Model Context Protocol. 직접 서버를 짜며 정체를 파악한다.

핵심 요약

  • MCP는 LLM 에이전트가 외부 도구·자원·프롬프트에 표준화된 방식으로 접근하는 프로토콜
  • 1차 자료: modelcontextprotocol.io 공식 spec, Anthropic Claude Code MCP docs
  • 핵심 3가지: Tools (에이전트가 호출하는 함수) / Resources (읽기 전용 데이터) / Prompts (재사용 가능 템플릿)
  • 디버깅은 mcp inspector + stderr 로깅이 사실상 표준
  • 흔한 함정: stdout에 print 한 줄만 잘못 들어가도 JSON-RPC가 깨진다

1. MCP가 풀려는 문제

LLM 에이전트가 외부 세계와 상호작용하는 방식은 도구마다 제각각이었다. Claude Code는 자체 tool spec, Cursor는 자체 확장, VS Code는 별도 API를 썼다. 같은 통합을 도구별로 세 번 짜야 했다.

MCP는 이 문제를 표준화한다: 한 번 MCP 서버를 짜면 MCP를 지원하는 모든 에이전트(Claude Code, Cursor, VS Code Agent, Continue, etc.)에서 그대로 쓸 수 있다. 2026년 기준 사실상 표준이 됐다.

프로토콜 본질: JSON-RPC 2.0 위에 정의된 메시지 규격 + 3가지 능력(Tools / Resources / Prompts) + 3가지 transport(stdio / SSE / Streamable HTTP).

2. 핵심 개념 3가지

2.1 Tools — 에이전트가 호출하는 함수

가장 자주 쓰는 능력이다. 에이전트가 행동을 일으킨다. - 예: search_database(query), create_jira_ticket(title, body), run_shell(cmd). - 정의: 이름 + 인자 스키마(JSON Schema) + 짧은 설명. - 호출 결과는 텍스트 또는 구조화 데이터로 돌아온다.

2.2 Resources — 읽기 전용 데이터

에이전트가 읽지만 변경하지 않는 자원. - 예: 파일 내용, DB 행, 설정 값, API 응답. - URI로 식별: file:///path, db://table/row/123, config://app/setting. - 도구와 달리 부수효과 없음이 보장된다 (에이전트가 안전하게 미리 읽을 수 있음).

2.3 Prompts — 재사용 가능한 템플릿

자주 쓰는 작업 패턴을 프롬프트 템플릿으로 노출한다. - 예: "이 코드 리뷰" / "이 SQL 설명" / "이 변경 PR 메시지 생성". - 슬래시 커맨드처럼 사용자가 직접 트리거 가능.

3. 최소 예제 — Python으로 MCP 서버 짓기

mcp Python SDK 기준. 약 30줄짜리 진짜로 작동하는 MCP 서버.

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("hello-mcp")

@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two integers and return the sum."""
    return a + b

@mcp.tool()
def greet(name: str) -> str:
    """Greet a person by name."""
    return f"Hello, {name}!"

@mcp.resource("config://app/version")
def app_version() -> str:
    """Read-only application version."""
    return "1.0.0"

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

Claude Code에 등록:

claude mcp add hello-mcp --command "python /abs/path/server.py"

이 한 줄로 add, greet 도구와 config://app/version 리소스가 세션 안에서 자동 발견된다.

4. 디버깅 — 보이지 않는 채널을 들여다본다

MCP의 가장 큰 함정은 stdout이 프로토콜 채널이라는 점이다. stdio transport에서는 stdout으로 JSON-RPC 메시지가 오가므로, 거기에 print("debug") 한 줄을 넣으면 즉시 깨진다.

디버깅 룰 4가지: 1. stdout에 절대 인쇄하지 말 것 — 모든 로그는 sys.stderr 또는 파일로. 2. MCP Inspector 사용 — npx @modelcontextprotocol/inspector python server.py로 실행하면 도구·리소스·프롬프트를 GUI로 호출하며 응답을 볼 수 있다. 3. 에러는 raise — try/except로 삼키지 말고 raise하면 클라이언트가 에러를 받는다. 4. JSON Schema 검증 — 인자 스키마는 SDK가 자동 생성하지만, 복잡한 타입은 직접 점검한다.

자주 만나는 오류: - "server disconnected": 프로세스가 시작 직후 죽음. stderr 로그를 본다. - "tool not found": 등록은 됐지만 이름 typo / 시그니처 변경 후 캐시. - "invalid arguments": 클라이언트가 보낸 JSON이 스키마 위반. Inspector로 정확한 인자 형식 확인.

5. Transport 선택

Transport 용도 특징
stdio 로컬 서버, 단일 사용자 가장 단순. 클라이언트가 자식 프로세스로 띄움
SSE / Streamable HTTP 원격 서버, 멀티 사용자 HTTP 기반, 인증 가능. 데이터센터 / 사내 서비스에 적합

처음 작성한다면 stdio부터. 안정화 후 원격이 필요하면 HTTP로 전환한다.

6. 보안 점검 — MCP 서버를 신뢰하기 전에

3rd-party MCP 서버는 임의의 코드 실행 권한을 갖는다. 도구 호출은 곧 함수 실행이고, 함수는 무엇이든 할 수 있다. 외부 서버를 붙이기 전에:

  • 소스 확인: GitHub 저장소를 직접 읽어 어떤 시스템 호출을 하는지 본다.
  • 권한 범위: 파일 시스템 접근, 네트워크, 외부 API 키 — 무엇을 요구하는가.
  • 격리: 가능하면 컨테이너·VM·OS 사용자 분리.
  • 감사 로그: 도구 호출 기록을 남긴다.

awesome-mcp-servers 같은 큐레이션 카탈로그를 시작점으로 쓰되, 프로덕션 연결 전에는 위 4가지를 체크한다.

7. 한눈에 정리

단계 핵심 주의
설계 Tools / Resources / Prompts 분리 부수효과 있는 건 Tool, 없는 건 Resource
구현 mcp SDK + @mcp.tool() 데코레이터 stdout에 print 금지
등록 claude mcp add <name> --command ... 절대 경로 사용
디버깅 MCP Inspector + stderr 로깅 "server disconnected"는 stderr 확인 신호
운영 권한 범위 + 격리 + 감사 로그 외부 MCP는 코드 실행 권한과 같음

다음 편

다음 편(4/5)은 멀티 에이전트 패턴 — 오케스트레이터와 전문가 분리다. MCP 서버가 외부 도구 통합이라면, 멀티 에이전트는 내부 작업 분할 패턴이다.

참고 자료

  • Model Context Protocol, Specification — modelcontextprotocol.io (2026-05-05 확인).
  • Anthropic, Using MCP with Claude Code — code.claude.com/docs/mcp (2026-05-05 확인).
  • awesome-mcp-servers (github.com/punkpeye/awesome-mcp-servers) — 큐레이션 카탈로그.

이 글은 AI 코딩 에이전트 실전 시리즈의 3/5 편입니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »