부록 C. 용어집 · 디버깅 체크리스트 · 추가 학습 링크
용어집
| 용어 | 뜻 | 관련 장 |
|---|---|---|
| MCP | Model Context Protocol. AI 앱과 외부 도구·데이터를 잇는 개방형 표준 | 01 |
| Host | LLM을 품고 사용자를 응대하는 AI 애플리케이션 | 02 |
| Client | 호스트 안에서 서버 하나와 1:1로 말하는 연결 담당 | 02 |
| Server | 도구·리소스·프롬프트를 노출하는 주체 | 02 |
| JSON-RPC 2.0 | MCP 메시지 인코딩 형식(UTF-8). 요청·응답·알림 | 04 |
| 요청/응답/알림 | id 있음(답장 필요)/같은 id(result·error)/id 없음(답장 없음) | 04 |
| capability | 핸드셰이크에서 광고하는 지원 기능. 합의된 것만 사용 | 05 |
| 프로토콜 리비전 | 날짜 기반 버전(예: 2025-11-25). initialize에서 협상 | 06 |
| stdio | 자식 프로세스 stdin/stdout 전송. 로컬 | 07 |
| Streamable HTTP | 단일 엔드포인트 HTTP 전송. 원격 표준 | 08 |
| Mcp-Session-Id | HTTP 전송의 세션 식별 헤더(인증 아님) | 08 |
| primitive | 일급 컨텍스트 타입: Tool·Resource·Prompt | 10 |
| Tool | 모델이 호출하는 행동(모델 제어) | 10 |
| Resource | URI로 식별되는 읽기 전용 데이터(애플리케이션 제어) | 11 |
| Prompt | 사용자가 고르는 재사용 템플릿(사용자 제어) | 12 |
| isError | 도구 실행 실패 표시(프로토콜 에러와 구분) | 10 |
| structuredContent / outputSchema | 구조화 출력과 그 스키마 | 10 |
| URI 템플릿 | users://{id}/profile 식 파라미터화 리소스 | 11 |
| sampling | 서버가 호스트 LLM에 추론을 요청(역방향) | 13 |
| elicitation | 서버가 사용자에게 구조화 입력을 요청(역방향) | 13 |
| roots | 클라이언트가 서버에 알려주는 접근 가능 경로 | 13 |
| human-in-the-loop | 위험 행동에 사람이 거부 가능하도록 두는 통제 | 10·20 |
| FastMCP | 데코레이터 기반 고수준 서버 프레임워크(공식 내장본/standalone 두 갈래) | 03·14 |
| MCP Inspector | 서버를 브라우저에서 테스트·디버깅하는 공식 도구 | 14 |
| Resource Server / Authorization Server | MCP 서버(토큰 검증)/외부 IdP(토큰 발급) | 19 |
| PRM (RFC 9728) | Protected Resource Metadata. 인증 발견 문서 | 19 |
| Resource Indicators (RFC 8707) | 토큰을 특정 서버에 묶음(aud 바인딩) | 19 |
| PKCE | OAuth 2.1 필수. 인가 코드 가로채기 방어 | 19 |
| confused deputy | 토큰 패스스루로 의도치 않은 권한이 새는 공격 | 19·21 |
| 도구 중독(Tool Poisoning) | 도구 설명·스키마에 숨긴 악성 지시 | 21 |
| rug-pull | 깨끗하던 서버가 오염 업데이트를 푸시 | 21 |
| stateless/stateful | 세션 상태 미유지/유지 (확장성 트레이드오프) | 08·23 |
디버깅 체크리스트
서버를 만들다 막히면 위에서 아래로 점검하세요.
| 증상 | 의심 | 확인·해결 | 장 |
|---|---|---|---|
| 연결 자체가 안 됨 | stdout 오염 | 본문 print 제거, 로그를 stderr/ctx.info로 | 07 |
mcp dev 없음 | CLI extra 누락 | pip install "mcp[cli]" 재설치 | 14 |
| 도구가 안 보임 | 데코레이터/객체명 | Inspector "List Tools" 확인, mcp run file:obj | 14 |
| 인자 거부 | inputSchema 불일치 | 타입 힌트·Field 제약 점검 | 15 |
| 호출이 계속 에러 | outputSchema vs structuredContent | 반환이 스키마와 맞나, None 아닌가 | 10 |
| 버전 협상 실패(-32602) | protocolVersion 불일치 | data.supported 확인, 리비전 맞추기 | 06 |
| 원격 401/403 | 인증·스코프 | PRM·토큰 aud·스코프 점검 | 19 |
| 원격 연결 불안정 | 구 SSE/전송 혼동 | Streamable HTTP 사용 확인 | 08·09 |
| 레플리카에서 "session not found" | stateful 세션 | stateless_http=True 고려 | 08·23 |
| 모델이 리소스를 안 씀 | 리소스는 모델이 직접 못 부름 | 도구로 래핑 | 11·18 |
보안 빠른 점검 (제작자)
- ] 모든 도구 입력을 스키마로 검증하고, 셸/SQL/경로에 직결하지 않는다 ([15·21)
- ] 서버가 최소 권한으로 자원에 접근한다(읽기 전용·스코프 키·제한 경로) ([20)
- ] 업스트림 호출에 클라이언트 토큰을 패스스루하지 않는다 ([19)
- ] 에러·로그에서 민감정보를 정화한다 ([16)
- ] 위험·파괴 행동에 human-in-the-loop를 건다 ([20)
- ] 도구 호출을 감사 로깅한다 ([23)
- ] HTTP면 Origin 검증·TLS·audience 검증을 한다 ([08·19)
- ] 업데이트는 투명하게, 큰 변경 시 재동의 ([22)
추가 학습 링크 (공식 우선)
- 공식 스펙: https://modelcontextprotocol.io/specification — 권위 있는 출처. 리비전(예: 2025-11-25) 명시 확인.
- 스펙 블로그: https://blog.modelcontextprotocol.io — 리비전·RC 소식.
- Python SDK: https://github.com/modelcontextprotocol/python-sdk — 공식
mcp패키지·예제. - MCP Inspector: https://modelcontextprotocol.io/docs/tools/inspector — 디버깅 도구.
- 아키텍처 개요: https://modelcontextprotocol.io/docs/learn/architecture — Host·Client·Server, 클라이언트/유틸리티 기능.
- 인증 스펙: https://modelcontextprotocol.io/specification/ (Authorization 섹션) — OAuth 2.1·RFC 9728/8707.
- 보안: OWASP MCP Top 10 (보안 리뷰 표준 참조), OWASP "Secure MCP Server Development" 가이드.
- standalone FastMCP: https://gofastmcp.com — 공식 SDK 내장본과 다른 별개 프로젝트임에 유의.
⚠️ 흔한 실수
MCP는 빠르게 진화합니다. 링크의 내용은 시점에 따라 바뀌며, 특히 전송·인증·SDK API는 개정이 잦습니다. 실제 구현 전 기준 리비전과 SDK 버전을 확인하세요.마치며
이 안내서는 MCP를 소비자로 써본 개발자가 프로토콜의 동작 원리를 이해하고, 자기 서버·클라이언트를 직접 설계·구현·배포·운영하는 데까지 안내하는 것을 목표로 했습니다. 1부에서 "왜 MCP인가"를 잡고, 2~3부에서 프로토콜과 전송을, 4부에서 세 primitive를, 5~6부에서 직접 만들기와 클라이언트를, 7부에서 인증과 보안을, 8부에서 배포·운영을 다뤘습니다.
세 가지를 기억하세요. (1) MCP는 JSON-RPC 위의 표준이고 전송과 무관하게 같은 메시지를 씁니다. (2) 세 primitive는 제어 모델(모델·애플리케이션·사용자)로 갈립니다. (3) MCP는 외부와 잇는 통로라 보안이 1급 주제입니다 — 입력 검증·최소 권한·human-in-the-loop·감사가 늘 함께 가야 합니다.
목차로 돌아가기