NightWatch/Citadel/Fundamentals/Protocols/JSON-RPC.md

JSON-RPC

JSON-RPC는 원격 함수 호출(RPC, Remote Procedure Call)을 JSON 메시지로 주고받는 규약입니다. "저쪽 프로세스/서버의 함수를 실행해줘"라는 요청을 정해진 JSON 모양으로 표현합니다. 딱 메시지의 생김새만 정의하며, 그 메시지를 어떻게 전달할지(transport)는 정하지 않습니다.

1. RPC란

RPC(Remote Procedure Call)는 다른 프로세스/서버의 함수를 마치 로컬 함수처럼 호출하는 방식입니다. JSON-RPC는 그 호출을 JSON으로, 고정된 필드 구조로 표현한 것입니다.

2. 메시지 세 종류

2.1. Request (응답을 기대하는 호출)

{
  "jsonrpc": "2.0",        // 버전. 항상 "2.0"
  "id": 2,                 // 요청 식별자 (응답과 짝맞춤)
  "method": "tools/list",  // 호출할 함수 이름
  "params": { }            // 인자 (없으면 생략 가능)
}

2.2. Response (요청에 대한 답)

{
  "jsonrpc": "2.0",
  "id": 2,                 // 대응하는 요청의 id
  "result": { }            // 성공 결과
}

실패 시 result 대신 error가 옵니다.

{
  "jsonrpc": "2.0",
  "id": 2,
  "error": { "code": -32601, "message": "Method not found" }
}

2.3. Notification (응답이 없는 통지)

id가 없으면 notification입니다. 받는 쪽은 응답하지 않습니다. 단방향 이벤트 알림에 씁니다.

{ "jsonrpc": "2.0", "method": "notifications/progress", "params": { } }

3. 핵심 4가지

  1. method: 부를 함수 이름.
  2. id: 요청-응답 짝맞춤. 여러 요청을 동시에 날려도 id로 구분하므로 순서가 뒤섞여도 됨.
  3. params: 함수 인자.
  4. transport 무관: 메시지 모양만 정의하므로 stdio·HTTP·WebSocket 등 무엇으로 실어 보내도 됨.

4. REST와의 차이

REST JSON-RPC
인터페이스 URL + HTTP 동사 (GET /tools) 채널 1개 + method 필드 ("method": "tools/list")
함수 늘 때 URL이 늘어남 method 이름만 추가
의미 리소스 중심 함수(동작) 중심
전송 HTTP에 묶임 transport 자유

REST가 "주소(URL)로 무엇을 할지 표현"한다면, JSON-RPC는 "하나의 통로로 보내되 method 이름으로 어떤 함수인지 지정"합니다.

5. 어디서 쓰나

대표적으로 MCP(Model Context Protocol) 가 JSON-RPC 2.0 위에서 동작합니다. tools/list, tools/call 같은 것이 모두 JSON-RPC method입니다. → MCP

6. Reference

Document History

  • 2026-06-19T16:59:20+09:00 - Written by Claude Opus 4.8 (1M context) via Claude Code
🔒 Admin 로그인