NightWatch/Citadel/AI/MCP.md

MCP (Model Context Protocol)

MCP는 AI 애플리케이션을 외부 시스템(데이터 소스, 도구, 워크플로)에 연결하기 위한 오픈 표준 프로토콜입니다. Anthropic이 2024년 11월에 공개했고, 이후 Claude·ChatGPT·VS Code·Cursor 등 여러 클라이언트가 지원하는 생태계로 확산되었습니다. 공식 비유로 "AI를 위한 USB-C 포트" — 제각각이던 연동 방식을 하나의 규격으로 통일한 것입니다.

1. 어떤 문제를 푸는가

MCP 이전에는 AI 앱마다, 도구마다 연동을 1:1로 따로 구현해야 했습니다(M개 앱 × N개 도구 = M×N 통합). MCP는 이 사이에 공통 프로토콜을 끼워, 서버를 한 번 만들면 MCP를 지원하는 모든 클라이언트가 쓸 수 있게 합니다(M+N 구조). "build once, integrate everywhere".

2. 참여자 (client-server 구조)

  • MCP Host: AI 애플리케이션 본체(예: Claude Code, Claude Desktop, VS Code). 여러 MCP 클라이언트를 관리합니다.
  • MCP Client: 호스트가 서버 하나당 하나씩 생성하는 커넥션 관리 컴포넌트. 서버와 전용(dedicated) 연결을 유지합니다.
  • MCP Server: 컨텍스트(데이터·도구)를 제공하는 프로그램. 로컬/원격 어디서 돌든 "서버"라 부릅니다.

즉 호스트가 N개 서버에 붙으면 클라이언트도 N개 생성됩니다(1 client : 1 server).

MCP Host (AI App)
├── MCP Client 1 ── dedicated ── Server A (로컬: Filesystem)
├── MCP Client 2 ── dedicated ── Server B (로컬: Database)
└── MCP Client 3 ── dedicated ── Server C (원격: Sentry)

3. 두 개의 레이어

  • Data layer: JSON-RPC 2.0 기반 프로토콜. 라이프사이클 관리 + 핵심 프리미티브(tools/resources/prompts)와 notification을 정의. (안쪽 레이어)
  • Transport layer: 실제 통신 채널·메시지 프레이밍·인증을 담당. (바깥 레이어)

전송 방식이 달라도 data layer의 JSON-RPC 메시지 포맷은 동일합니다.

4. 전송(Transport)

  • stdio transport: 표준 입출력으로 같은 머신의 로컬 프로세스끼리 통신. 네트워크 오버헤드 없음. 보통 클라이언트 1개를 서빙("로컬 서버").
  • Streamable HTTP transport: 클라이언트→서버는 HTTP POST, 스트리밍이 필요하면 옵션으로 Server-Sent Events(SSE)를 사용. 원격 서버용이며 다수 클라이언트를 서빙. bearer token·API key 등 표준 HTTP 인증을 쓰고, 토큰 획득은 OAuth 권장.

5. 프리미티브(Primitives)

MCP의 핵심 개념. "클라이언트와 서버가 서로에게 무엇을 제공할 수 있는가"를 정의합니다.

5.1. 서버가 노출하는 것

  • Tools: AI가 호출해 행동하는 실행 가능 함수(파일 조작, API 호출, DB 쿼리 등). 발견 tools/list, 실행 tools/call. 각 도구는 name·title·description·inputSchema(JSON Schema)를 가짐.
  • Resources: AI에 컨텍스트 데이터를 제공하는 소스(파일 내용, DB 레코드, API 응답 등). resources/list, resources/read.
  • Prompts: 상호작용을 구조화하는 재사용 템플릿(시스템 프롬프트, few-shot 예시 등).

발견은 */list, 조회는 */get/*/read, 실행은 tools/call. */list가 동적이라 목록이 런타임에 바뀔 수 있습니다.

5.2. 클라이언트가 노출하는 것

서버가 더 풍부한 상호작용을 짤 수 있게 하는 역방향 기능입니다.

  • Sampling (sampling/createMessage): 서버가 클라이언트의 LLM에 추론을 요청. 서버가 자체 LLM SDK를 품지 않고도 모델을 쓸 수 있어 model-independent하게 유지됨.
  • Elicitation (elicitation/create): 서버가 사용자에게 추가 입력/확인을 요청.
  • Logging: 서버가 디버깅·모니터링용 로그를 클라이언트로 전송.

6. 라이프사이클 (capability negotiation)

MCP는 stateful 프로토콜이라 초기화 핸드셰이크로 양측 capability를 협상합니다.

  1. 클라이언트 → initialize 요청: protocolVersion(예: 2025-06-18), 자신의 capabilities, clientInfo 전송.
  2. 서버 → 응답: 합의된 protocolVersion, 서버 capabilities(예: tools: {listChanged: true}), serverInfo. 호환 버전 협상 실패 시 연결 종료.
  3. 클라이언트 → notifications/initialized 통지(응답 불필요).

이후 tools/list → tools/call 식으로 동작합니다.

// initialize 요청 (발췌)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "elicitation": {} },
    "clientInfo": { "name": "example-client", "version": "1.0.0" }
  }
}

7. Notification (실시간 갱신)

JSON-RPC 2.0 notification(= id 없는 메시지, 응답 없음)으로 상태 변화를 알립니다. 예: 서버의 도구 목록이 바뀌면 notifications/tools/list_changed를 보내고, 클라이언트는 tools/list를 다시 호출해 동기화합니다. 단 이 통지는 초기화 때 listChanged: true를 선언한 서버만 보냅니다(capability 기반). 폴링 없이 최신 상태 유지가 가능합니다.

8. 메시지 포맷

모든 통신은 JSON-RPC 2.0입니다. 요청은 id로 요청-응답을 짝지으며, 응답이 불필요하면 notification(id 생략)을 씁니다. → JSON-RPC

9. 핵심 정리

  • 한 줄: "AI ↔ 외부 시스템 연동의 표준 규격(USB-C)". M×N 통합을 M+N으로 줄임.
  • 구조: Host(앱) → Client(서버당 1개) → Server(컨텍스트 제공).
  • 서버 프리미티브 셋: Tools(행동) / Resources(데이터) / Prompts(템플릿).
  • 클라이언트 프리미티브: Sampling / Elicitation / Logging.
  • JSON-RPC 2.0 위에서 stdio 또는 Streamable HTTP로 전송, 초기화 시 capability 협상.

부록: method 카탈로그

tools/list처럼 보이는 것들은 전부 JSON-RPC method 이름입니다. 핵심은 "고정된 몇 개의 API"가 아니라, 표준 method 집합 중 서버/클라이언트가 켠 기능에 해당하는 것만 유효하다는 점입니다(capability 협상). 안 켠 기능의 method는 없는 셈입니다.

그룹 method 비고
Lifecycle initialize 연결·capability 협상
notifications/initialized 초기화 완료 통지
ping 생존 확인
Tools tools/list 도구 목록
tools/call 도구 실행
notifications/tools/list_changed 목록 변경 통지
Resources resources/list 리소스 목록
resources/read 내용 읽기
resources/templates/list URI 템플릿 목록
resources/subscribe / resources/unsubscribe 변경 구독/해제
notifications/resources/list_changed / notifications/resources/updated 변경 통지
Prompts prompts/list / prompts/get 목록 / 조회
notifications/prompts/list_changed 목록 변경 통지
클라이언트 기능 sampling/createMessage 서버가 클라 LLM에 추론 요청
elicitation/create 서버가 사용자 입력 요청
roots/list / notifications/roots/list_changed 클라가 노출하는 파일 루트
유틸 logging/setLevel / notifications/message 로깅
notifications/cancelled 요청 취소
notifications/progress 진행률
completion/complete 인자 자동완성

패턴만 잡으면 외울 게 적습니다:

  • <프리미티브>/list — 목록 조회
  • /get·/read — 단건 조회
  • /call — 실행 (tools 전용)
  • notifications/<...> — 응답 없는 통지(id 없음)

서버는 이 전부를 구현하지 않습니다. initialize에서 선언한 capability(tools, resources, prompts 등)에 해당하는 method만 응답합니다.

10. Reference

Document History

  • 2026-06-19T12:03:00+09:00 - Written by Claude Opus 4.8 (1M context) via Claude Code
  • 2026-06-19T16:59:20+09:00 - Edited by Claude Opus 4.8 (1M context) via Claude Code: JSON-RPC 링크 추가
  • 2026-06-19T17:02:12+09:00 - Edited by Claude Opus 4.8 (1M context) via Claude Code: method 카탈로그 부록 추가
🔒 Admin 로그인