부록 A. JSON-RPC 메서드 치트시트
기준 리비전: 2025-11-25. 메서드명·필드는 스펙 리비전에 따라 다를 수 있으니, 코드 전 공식 스펙을 확인하세요.
| 메서드 | 방향 | 종류 | 용도 |
|---|
initialize | C → S | 요청 | 핸드셰이크 시작 (protocolVersion, capabilities, clientInfo) |
notifications/initialized | C → S | 알림 | 핸드셰이크 완료 신호 |
ping | 양방향 | 요청 | 연결 생존 확인 |
Tools (10장)
| 메서드 | 방향 | 종류 | 용도 |
|---|
tools/list | C → S | 요청 | 도구 목록 (커서 페이지네이션) |
tools/call | C → S | 요청 | 도구 실행 (name, arguments) → content, isError, structuredContent |
notifications/tools/list_changed | S → C | 알림 | 도구 목록 변경 통지 |
Resources (11장)
| 메서드 | 방향 | 종류 | 용도 |
|---|
resources/list | C → S | 요청 | 구체적 리소스 목록 |
resources/templates/list | C → S | 요청 | URI 템플릿 목록 |
resources/read | C → S | 요청 | URI로 내용 읽기 → contents (text/blob) |
resources/subscribe | C → S | 요청 | 특정 리소스 변경 구독 |
resources/unsubscribe | C → S | 요청 | 구독 해제 |
notifications/resources/list_changed | S → C | 알림 | 리소스 목록 변경 |
notifications/resources/updated | S → C | 알림 | 구독 리소스 변경 |
Prompts (12장)
| 메서드 | 방향 | 종류 | 용도 |
|---|
prompts/list | C → S | 요청 | 프롬프트 목록 |
prompts/get | C → S | 요청 | 프롬프트 가져오기 (arguments) → messages |
notifications/prompts/list_changed | S → C | 알림 | 프롬프트 목록 변경 |
클라이언트 기능 (서버 → 클라이언트, 역방향) (13장)
| 메서드 | 방향 | 종류 | 용도 |
|---|
sampling/createMessage | S → C | 요청 | 서버가 호스트 LLM에 추론 요청 |
elicitation/create | S → C | 요청 | 서버가 사용자에게 구조화 입력 요청 |
roots/list | S → C | 요청 | 클라이언트의 파일 루트 조회 |
notifications/roots/list_changed | C → S | 알림 | 루트 목록 변경 |
⚠️ 흔한 실수
2026-07-28 RC는 위 서버 주도 요청(roots/list·sampling/createMessage·elicitation/create)을 Multi Round-Trip 패턴으로 재편하는 초안을 담고 있습니다. 확정 전이니 단정하지 마세요.
유틸리티 (13장)
| 메서드 | 방향 | 종류 | 용도 |
|---|
notifications/progress | 양방향 | 알림 | 긴 작업 진행률 (progressToken, progress, total) |
notifications/cancelled | 양방향 | 알림 | 진행 중 요청 취소 |
notifications/message | S → C | 알림 | 로그 메시지 (level, data) |
logging/setLevel | C → S | 요청 | 로그 레벨 설정 |
completion/complete | C → S | 요청 | 인자 자동완성 제안 |
표준 JSON-RPC 에러 코드 (04장)
| 코드 | 이름 | 의미 |
|---|
| -32700 | Parse error | JSON 문법 오류 |
| -32600 | Invalid Request | JSON-RPC 구조 오류 |
| -32601 | Method not found | 없는 메서드 (버전 불일치·오타) |
| -32602 | Invalid params | 잘못된 인자 (버전 협상 실패 포함) |
| -32603 | Internal error | 서버 내부 오류 |
| -32002 | (MCP) Resource not found | 리소스 없음 |
| -32003 | (MCP) Invalid/expired session | 세션 무효·만료 |
📌 핵심
두 층위 재확인: 위 에러 코드는
프로토콜 실패용.
도구 실행 실패는
error가 아니라 정상 result의
isError: true로 표현합니다(
10장). isError 응답은 outputSchema 검증을 건너뜁니다.
메시지 봉투 형태 (04장)
JSONC
// 요청 (id 있음)
{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { ... } }
// 성공 응답 (같은 id, result)
{ "jsonrpc": "2.0", "id": 1, "result": { ... } }
// 에러 응답 (같은 id, error)
{ "jsonrpc": "2.0", "id": 1, "error": { "code": -32602, "message": "...", "data": { ... } } }
// 알림 (id 없음, 답장 없음)
{ "jsonrpc": "2.0", "method": "notifications/initialized" }
목차로 · 다음: 부록 B. Python SDK 빠른 참조