아프니까 개발자다

MCP Roots 완전 분해: 서버가 클라이언트에게 먼저 묻는 역방향 설계

타이젠 개발자, 윤진 — Sat, 13 Jun 2026 23:00:19 +0900

MCP를 처음 배울 때 가장 충격적인 발견 중 하나가 있다. 서버가 클라이언트에게 요청을 보낸다는 것이다. 일반적인 클라이언트-서버 모델에서는 클라이언트가 요청하고 서버가 응답한다. 그런데 MCP에는 이 방향이 뒤집힌 메서드가 있다.

roots/list가 그 하나다. 서버가 클라이언트에게 "너는 어떤 파일시스템 경로에 접근 권한이 있니?"를 묻는다. 이 글은 roots/list가 왜 필요한지, 어떻게 동작하는지, 그리고 이 역방향 설계가 MCP 전체에서 어떤 의미를 갖는지를 다룬다.

역방향이 필요한 이유 — 서버는 클라이언트를 모른다

파일시스템을 읽는 MCP 서버를 만든다고 가정하자. resources/list로 파일 목록을 노출하고 resources/read로 내용을 제공한다. 그런데 어느 경로를 노출해야 할까?

하드코딩하면? /home/user/projects라고 박아두면 사용자마다 경로가 다를 수 있다. 설정 파일로 받으면? 서버를 띄울 때 경로를 알아야 하는데, 사용자가 IDE에서 어떤 프로젝트를 열지는 서버가 모른다. 그리고 사용자가 프로젝트를 바꾸면? 서버를 재시작해야 한다.

이 문제의 근본은 클라이언트(IDE)가 파일시스템 범위를 알고 있는데, 서버는 모른다는 것이다. Roots는 이 정보 비대칭을 해결한다 — 서버가 클라이언트에게 물어보면 된다.

▲ 문제: 서버가 클라이언트를 모른다

▲ 해결: roots/list로 동적으로 파악

다이어그램 설명: 위 — 서버가 클라이언트의 파일시스템 범위를 모르는 상태. 각 클라이언트가 다른 경로를 갖고 있어 하드코딩이 불가능하다. 아래 — 서버가 roots/list로 클라이언트에게 직접 물어보고, 응답에 따라 그 범위 내에서만 리소스를 노출한다. 클라이언트가 컨텍스트 범위를 통제하고 서버가 동적으로 따라간다.

그림: MCP의 두 가지 방향 — 대부분은 클라이언트가 요청하지만, roots/list는 서버가 클라이언트에게 요청한다

다이어그램 설명: 위 섹션(파란색)이 일반적인 흐름 — 클라이언트가 요청하고 서버가 응답한다. 아래 섹션(빨간색)이 역방향 — 서버가 요청하고 클라이언트가 응답한다. 역방향이 가능한 이유는 MCP가 양방향 채널(주로 stdio나 SSE)을 쓰기 때문이다. 단방향 HTTP 요청-응답 모델이었다면 구현 불가능하다. roots/list 외에 sampling/createMessage(서버가 클라이언트에게 LLM 호출을 위임)도 같은 역방향 패턴이다.

roots/list — 서버가 클라이언트에게 보내는 요청

Roots는 MCP 명세에서 "클라이언트가 관리하는 파일시스템 경계"를 나타낸다. IDE에서는 현재 열린 워크스페이스 폴더가, Claude Code에서는 현재 작업 디렉토리가 root다.

다이어그램 설명: 서버가 클라이언트에게 roots/list를 보내면 클라이언트가 현재 열린 프로젝트 경로 목록으로 응답한다. 서버는 이 범위를 기반으로 리소스를 노출한다. 프로젝트가 변경되면 클라이언트가 notifications/roots/list_changed를 서버에 보내고, 서버가 다시 roots/list를 요청해서 최신 범위를 파악한다. 이 ping-pong 구조가 서버와 클라이언트의 범위를 동기화된 상태로 유지한다.

// 서버 → 클라이언트: roots/list 요청 (역방향)
{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "roots/list"
  // params 없음 — 단순히 "네 루트 목록을 알려줘"
}

// 클라이언트 → 서버: 응답
{
  "jsonrpc": "2.0",
  "id": 101,
  "result": {
    "roots": [
      {
        "uri":  "file:///home/user/projects/my-app",      // 파일시스템 경로
        "name": "my-app"                                  // 사람이 읽기 좋은 이름 (선택)
      },
      {
        "uri":  "file:///home/user/projects/shared-lib",
        "name": "shared-lib"
      }
    ]
  }
}

// 여러 워크스페이스 폴더가 열린 경우 (VS Code Multi-root Workspace)
{
  "result": {
    "roots": [
      { "uri": "file:///workspace/frontend",  "name": "frontend" },
      { "uri": "file:///workspace/backend",   "name": "backend" },
      { "uri": "file:///workspace/infra",     "name": "infra" }
    ]
  }
}

코드 설명: uri는 file:// 스키마가 일반적이지만 MCP가 강제하지는 않는다. 로컬 파일시스템 경로가 아닌 원격 저장소 URI를 쓰는 서버도 이론적으로 가능하다. name은 선택 필드지만 있으면 서버가 사람이 읽기 좋은 방식으로 리소스를 분류할 수 있다. 목록의 순서는 우선순위를 의미하지 않는다 — 서버가 필요에 따라 해석한다.

capabilities.roots — 핸드셰이크에서 협상한다

roots/list를 사용하려면 초기화 핸드셰이크에서 클라이언트가 지원 의사를 먼저 선언해야 한다. 선언 없이 서버가 roots/list를 보내면 클라이언트는 -32601 Method not found로 거부한다.

// initialize 요청 — 클라이언트가 roots 지원 선언
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "roots": {
        "listChanged": true   // "루트 변경 시 내가 notifications/roots/list_changed를 보낼게"
      },
      "sampling": {}          // 선택 — LLM 위임도 받을 수 있음
    },
    "clientInfo": { "name": "my-ide-plugin", "version": "1.2.0" }
  }
}

// initialize 응답 — 서버가 지원 기능 확인
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "resources": { "subscribe": true, "listChanged": true },
      "tools":     { "listChanged": true }
      // roots 관련 서버 capability는 없음 — roots는 클라이언트의 역할
    },
    "serverInfo": { "name": "filesystem-mcp", "version": "0.5.0" }
  }
}

코드 설명: capabilities.roots.listChanged: true는 "나(클라이언트)는 루트 목록이 바뀔 때 notifications/roots/list_changed를 보낼 수 있다"는 선언이다. 이것이 true여야 서버가 roots/list를 요청하는 게 의미 있다 — 바뀌어도 알림이 안 오면 서버가 언제 다시 물어봐야 할지 모르기 때문이다. listChanged: false거나 아예 roots capabilities가 없으면, 서버는 세션 시작 시 한 번만 roots/list를 요청하고 그 이후엔 변경을 추적하지 않는 방식으로 구현한다.

notifications/roots/list_changed — 클라이언트가 서버에게 보내는 알림

사용자가 IDE에서 새 프로젝트 폴더를 열거나 기존 폴더를 닫으면, 클라이언트가 서버에게 알린다. 이 알림의 방향이 특이하다 — 다른 알림들은 서버가 클라이언트에게 보내는데, 이건 클라이언트가 서버에게 보낸다.

다이어그램 설명: 사용자가 IDE에서 폴더를 추가/제거할 때마다 클라이언트가 notifications/roots/list_changed를 서버에 보낸다. 서버는 이를 받아 roots/list를 재요청하고 범위를 갱신한다. 이 왕복 덕분에 서버의 리소스 범위가 사용자의 워크스페이스 상태와 항상 동기화된다. 사용자가 모르는 사이에 서버는 자동으로 "지금 열린 프로젝트들만"을 커버한다.

// 클라이언트 → 서버: 루트 목록 변경 알림 (id 없음 = 알림)
{
  "jsonrpc": "2.0",
  "method": "notifications/roots/list_changed"
  // params 없음 — "바뀌었으니 다시 물어봐"라는 신호만
}

// 이 알림을 받은 서버가 roots/list를 다시 보낸다
{
  "jsonrpc": "2.0",
  "id": 102,
  "method": "roots/list"
}

// 클라이언트 응답 — 최신 상태
{
  "jsonrpc": "2.0",
  "id": 102,
  "result": {
    "roots": [
      { "uri": "file:///workspace/project-b", "name": "project-b" }
    ]
  }
}

코드 설명: notifications/roots/list_changed도 params가 없다 — "어떤 루트가 추가/제거됐는지" 알려주지 않는다. invalidation 신호만이다. 서버가 roots/list를 다시 요청해서 전체 최신 상태를 받아간다. 이 패턴은 Resources의 notifications/resources/list_changed와 동일한 "push invalidation + pull data" 설계다. MCP 전반에 걸쳐 일관되게 쓰이는 패턴이다.

Roots → Resources 연동 — 서버가 범위를 동적으로 결정한다

Roots의 진짜 가치는 resources/list와의 연동에서 나온다. 서버가 roots를 파악하면, 그 범위 내의 파일들을 resources/list로 노출할 수 있다. roots가 바뀌면 노출되는 리소스 범위도 바뀐다.

다이어그램 설명: roots가 바뀌면 서버가 새 경로를 인덱싱하고, resources 목록도 달라진다. 서버는 notifications/resources/list_changed를 보내서 클라이언트에게 리소스 목록도 다시 조회하라고 알린다. roots 변경이 연쇄적으로 resources 변경을 유발하는 이 흐름이 "동적으로 확장되는 파일시스템 MCP 서버"의 핵심 동작 원리다.

실전 시나리오 — Claude Code에서 roots가 작동하는 방식

Claude Code를 IDE처럼 쓸 때 roots가 어떻게 작동하는지 보자. 사용자가 특정 디렉토리에서 세션을 시작하면, Claude Code가 그 디렉토리를 root로 MCP 서버에 노출한다.

다이어그램 설명: Claude Code가 cd /workspace/my-app으로 시작하면 그 경로가 기본 root다. MCP 서버가 초기화 직후 roots/list를 요청하면 Claude Code가 현재 작업 디렉토리를 알려준다. 나중에 개발자가 다른 경로를 추가하면 roots가 갱신되고 resources 범위도 따라서 넓어진다. 서버를 재시작하거나 설정을 바꿀 필요가 없다.

보안 모델 — 클라이언트가 범위를 통제한다

Roots 설계에서 중요한 보안적 함의가 있다. 서버가 접근할 수 있는 파일시스템 범위를 클라이언트가 결정한다. 서버가 원하는 경로를 마음대로 접근할 수 없다 — 클라이언트가 허용한 roots 안에서만 작동한다.

// 악의적인 서버가 roots 밖의 경로를 리소스로 노출하려 해도...
{
  "result": {
    "resources": [
      {
        "uri": "file:///etc/passwd",      // roots 밖의 민감한 파일
        "name": "passwd",
        "mimeType": "text/plain"
      }
    ]
  }
}

// 클라이언트는 이 URI가 roots 범위 밖임을 확인하고 거부할 수 있다
// roots = ["file:///workspace/my-app"]
// /etc/passwd는 이 범위에 포함되지 않음 → 클라이언트가 resources/read 거부

코드 설명: MCP 명세 자체가 "roots 밖의 URI를 클라이언트가 거부해야 한다"고 강제하지는 않는다. 하지만 잘 구현된 클라이언트는 roots를 신뢰 경계로 써서 서버가 제안하는 URI가 허용 범위 내인지 검증한다. 이 패턴은 sampling/createMessage의 보안 모델과 같다 — 서버가 원하는 LLM 호출을 요청해도 클라이언트가 검토하고 허용/거부를 결정한다. "클라이언트가 보안 경계를 소유한다"는 원칙이 MCP 역방향 메서드 전반에 일관되게 적용된다.

Roots 메서드가 주는 것 — 동적 컨텍스트 범위

Roots는 메서드 2개(roots/list + notifications/roots/list_changed)로 구성된 단순한 구조다. 그런데 이 단순한 구조가 해결하는 문제가 크다.

첫째, 서버 설정 없이 클라이언트 컨텍스트를 따라간다. 사용자가 어떤 프로젝트를 열어도, 서버는 자동으로 그 범위를 파악한다. 파일 경로를 설정 파일에 하드코딩할 필요가 없다.

둘째, 멀티 워크스페이스를 자연스럽게 지원한다. VS Code의 Multi-root Workspace처럼 여러 폴더가 동시에 열려 있는 환경에서, 서버가 여러 roots를 한꺼번에 처리한다. 각 root의 파일을 별도로 관리하거나 합쳐서 제공할 수 있다.

셋째, 보안 경계를 코드가 아닌 프로토콜이 명시한다. 어디까지 접근할 수 있는지가 런타임 설정이 아니라 세션 초기화 과정에서 명확하게 선언된다. 클라이언트가 허용한 범위만 서버에 노출된다는 것이 MCP 세션의 기본 계약이 된다.

roots/list는 MCP의 역방향 설계가 실제로 무엇을 가능하게 하는지를 가장 잘 보여주는 예시다. 서버가 클라이언트에게 묻는 이 작은 역전이, 서버와 클라이언트의 파일시스템 컨텍스트를 항상 동기화된 상태로 유지하게 한다 — 사용자가 무엇을 열고 닫든 상관없이.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

MCP Prompts의 멀티턴 messages — 서버가 모델의 첫 생각을 설계하는 방법

타이젠 개발자, 윤진 — Sat, 13 Jun 2026 22:00:09 +0900

assistant 롤은 MCP가 만든 게 아니다

user / assistant 롤 구조는 2023년 3월 OpenAI가 Chat Completions API를 공개하면서 업계 표준이 됐다. 이후 Anthropic Messages API, Google Gemini, Mistral 등 사실상 모든 LLM 제공자가 동일한 구조를 채택했다. messages 배열에 user와 assistant 턴을 번갈아 넣어 대화 history를 표현하는 방식은 MCP 이전부터 이미 보편적 관행이었다.

MCP(Model Context Protocol)는 2024년 11월 Anthropic이 발표했고, prompts/get 응답의 messages 배열도 이 기존 표준을 그대로 빌려왔다. MCP가 새로 더한 것은 롤 자체가 아니라 서버가 assistant 턴을 미리 만들어 심을 수 있다는 구조적 허용이다. 사용자가 실제로 대화를 시작하기 전에, 서버가 "AI가 이미 이렇게 답했다"는 가상의 과거를 설계해 넣을 수 있게 된 것이다.

system 프롬프트만으로는 부족한 순간

LLM에게 복잡한 작업을 시킬 때 system 프롬프트로 "이렇게 분석해라"고 지시하는 건 기본이다. 그런데 실제로 써보면 system 프롬프트가 잘 안 먹히는 상황이 있다.

코드 보안 분석을 예로 들자. "unsafe 블록, 외부 입력 경로, 에러 핸들링 순으로 검토해라"고 system에 써도, 모델은 자기 흐름대로 대답하는 경우가 많다. system 프롬프트는 "규칙"이지만, 모델은 그 규칙을 얼마나 충실히 따를지 스스로 결정한다. 반면 이미 그 방향으로 대화가 진행된 상태라면 이야기가 달라진다. 모델은 자신이 한 말을 이어간다.

MCP Prompts의 messages 배열이 assistant 롤을 지원하는 이유가 여기 있다. 서버는 "AI가 이렇게 답했다"는 가상의 과거 대화를 미리 심을 수 있고, 모델은 그 대화를 이어받아 추론한다.

1-turn vs 멀티턴 — 어디서 차이가 나는가

같은 질문에 두 방식이 어떻게 다른지 구체적으로 보자.

▲ 1-turn: system 지시

▲ 멀티턴: 가짜 history 주입

핵심 차이: system 프롬프트는 모델에게 "이렇게 해라"는 지시다. 멀티턴 history는 "나는 이미 이렇게 시작했다"는 기정사실이다. 모델은 지시보다 자신이 이미 시작한 방향을 더 일관되게 따른다.

assistant 턴이 필수적으로 쓰이는 세 가지 패턴

어떤 상황에서 멀티턴이 실질적으로 필요한지 패턴별로 보자.

패턴 1 — 추론 방향 고정 (Reasoning Anchor)

모델이 어떤 프레임으로 문제를 바라볼지 미리 결정해 두는 패턴이다. 복잡한 분석 작업에서 모델이 "어디서부터 시작할지"를 스스로 선택하게 두면 매번 다른 결과가 나온다.

효과: 팀원 10명이 각자 다른 방식으로 요청해도 서버가 심어둔 체크리스트 프레임을 이어받기 때문에 분석 구조가 일관된다. 모델이 어떤 요점을 빠뜨리거나 엉뚱한 방향으로 달리는 것을 막는다.

패턴 2 — 출력 형식 강제 (Format Locking)

모델에게 "JSON으로 답해라"고 system에 써도 자연어가 섞이는 경우가 흔하다. assistant 턴에 원하는 형식의 예시를 미리 심으면 모델이 그 형식을 이어받는다.

효과: system 프롬프트에 JSON 형식을 설명하는 것보다 assistant가 그 형식으로 이미 시작한 것처럼 보여주는 것이 훨씬 강력하다. 특히 긴 목록 형태의 구조화된 출력에서 효과가 크다.

패턴 3 — 단계적 분해 유도 (Step Decomposition)

복잡한 작업을 모델이 한 번에 처리하려 하면 품질이 떨어진다. 미리 "단계별로 나눠서 보겠다"고 assistant가 선언하게 하면, 모델이 실제로 단계적으로 추론한다.

효과: 모델이 "생각해야 할 것"을 서버가 미리 분해해 줬기 때문에 각 단계를 깊이 있게 다룬다. 단일 질문으로 받았을 때 얕게 훑는 문제를 해결한다.

실제 messages 배열 구조

MCP prompts/get 응답에서 서버가 돌려주는 messages 배열은 이렇게 생겼다.

// prompts/get 응답 — 멀티턴 messages
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "이 Rust 코드의 잠재적 보안 취약점을 분석해 줘:\n[현재 편집 중인 파일 내용]"
      }
    },
    {
      "role": "assistant",           // ← 서버가 만들어 넣은 가짜 AI 답변
      "content": {
        "type": "text",
        "text": "코드를 분석하겠습니다. 보안 관점에서 다음 순서로 검토합니다:\n1. unsafe 블록 사용 현황\n2. 외부 입력 처리 경로\n3. 에러 핸들링 패턴\n분석을 시작합니다:"
      }
    },
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "특히 외부 입력(네트워크/파일 I/O)을 처리하는 부분에 집중해서 분석해 줘."
      }
    }
  ]
  // 클라이언트는 이 배열을 현재 대화 context 앞에 prepend하고 LLM에 전달
}

코드 설명: role: "assistant"가 있는 2번째 메시지는 실제로 모델이 생성한 것이 아니다. 서버가 "모델이 이렇게 답했다"고 가정하고 만든 텍스트다. 클라이언트는 이 배열 전체를 LLM에 넘기고, 모델은 자신이 이미 이 방향으로 시작했다고 인식한 채 다음 답변을 생성한다.

클라이언트 입장에서 보는 전체 흐름

클라이언트가 이 배열을 받아서 실제 LLM 호출까지 이어지는 흐름을 한눈에 보면 이렇다.

클라이언트 코드는 단순하다. 서버에서 받은 messages 배열을 그대로 LLM API의 messages 파라미터 앞에 붙이면 끝이다. 배열 안에 assistant 턴이 있어도 클라이언트는 특별히 할 일이 없다. LLM API가 알아서 history로 처리한다.

1-turn system 프롬프트 vs 멀티턴 messages — 언제 무엇을 쓰나

결정 기준은 간단하다: 모델이 자유롭게 구조를 잡아도 되면 system 프롬프트, 구조 자체를 서버가 통제해야 하면 멀티턴이다. 특히 같은 프롬프트를 팀 전체가 쓸 때 결과 품질 편차를 줄여야 한다면 멀티턴이 훨씬 강력하다.

세 가지 효과 — 정리

멀티턴 messages가 실제로 주는 효과를 정리하면 세 가지다.

세 번째 효과가 MCP Prompts 전체의 핵심이기도 하다. 클라이언트는 서버가 심어둔 assistant 턴의 내용을 모른다. 알 필요도 없다. 서버 팀이 프롬프트를 개선하면 — 체크리스트 항목을 추가하거나, 형식 예시를 더 정교하게 만들거나 — 클라이언트는 아무것도 바꾸지 않아도 자동으로 개선된 버전을 사용하게 된다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

MCP Prompts 완전 분해: 최적 프롬프트를 서버에 봉인하고 재사용하는 방법

타이젠 개발자, 윤진 — Sat, 13 Jun 2026 21:00:53 +0900

MCP의 세 기본 단위 중 Prompts는 가장 오해받는다. Tools는 "AI가 실행하는 함수"라고 설명하면 직관적으로 와닿는다. Resources는 "AI가 읽는 데이터"라고 하면 이해된다. 그런데 Prompts는? "서버에 저장된 재사용 프롬프트 템플릿"이라는 설명을 들으면 "그냥 클라이언트에서 관리하면 되지 않나?"라는 의문이 든다.

이 의문이 Prompts를 이해하는 출발점이다.

왜 프롬프트를 서버에 두는가

AI 개발 도구를 만든다고 가정하자. "코드 리뷰 해줘"라고 요청할 때 어떤 프롬프트를 쓸 것인가? 팀원 10명이 각자 다른 방식으로 요청하면 결과 품질이 들쭉날쭉해진다. 누군가 몇 달에 걸쳐 다듬은 최적 프롬프트가 있다면, 그걸 모두가 쓸 수 있어야 한다.

클라이언트(IDE 플러그인)에 프롬프트를 하드코딩할 수도 있다. 하지만 서버 팀이 프롬프트를 개선하면 모든 클라이언트가 업데이트해야 한다. MCP Prompts는 이 문제를 뒤집는다 — 최적 프롬프트 지식을 서버에 캡슐화하고, 클라이언트는 그냥 가져다 쓴다.

다이어그램 설명: 아래는 각자 다른 방식으로 요청하는 상황 — 프롬프트가 사람마다 달라서 결과 품질이 보장되지 않는다. 위는 Prompts를 쓰는 상황 — 서버의 code-review 템플릿을 인자만 바꿔서 쓴다. 서버가 프롬프트를 업데이트하면 모든 클라이언트가 자동으로 최신 버전을 쓰게 된다.

또 하나의 차이가 있다. Tools는 모델이 자율적으로 실행을 결정한다. Prompts는 사람이 명시적으로 선택한다. IDE의 슬래시 명령어(/code-review)나 드롭다운 메뉴로 사람이 골라야 활성화된다. 이 차이가 Prompts를 Tools·Resources와 별도로 분리한 이유다.

그림: Tools·Resources·Prompts의 트리거 주체 비교 — Prompts만 사람이 명시적으로 선택한다

다이어그램 설명: 세 단위의 가장 큰 차이는 누가 시작하느냐다. Tools는 모델이 필요하다고 판단하면 자동 실행한다. Resources는 클라이언트가 모델이 추론하기 전에 데이터를 채운다. Prompts는 사람이 골라야 활성화된다. 이 세 번째 트리거 주체가 Prompts를 "사용 패턴 캡슐화" 도구로 만드는 이유다.

prompts/list — "이 서버로 어떻게 요청하면 잘 되나"

클라이언트가 서버에서 사용 가능한 프롬프트 템플릿 목록을 조회한다. IDE가 슬래시 명령어 드롭다운을 채울 때 이 메서드를 호출한다.

// 요청
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "prompts/list"
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": [
      {
        "name":        "code-review",
        "description": "코드를 검토하고 개선점을 제안합니다",
        "arguments": [
          {
            "name":        "language",
            "description": "프로그래밍 언어 (예: rust, python, go)",
            "required":    true    // 이 인자 없으면 prompts/get 호출 불가
          },
          {
            "name":        "focus",
            "description": "리뷰 초점: 보안 | 성능 | 가독성 | 전반",
            "required":    false   // 없으면 서버가 기본값 사용
          },
          {
            "name":        "severity",
            "description": "지적할 최소 심각도: 낮음 | 보통 | 높음",
            "required":    false
          }
        ]
      },
      {
        "name":        "explain-error",
        "description": "컴파일/런타임 오류 메시지를 분석하고 원인을 설명합니다",
        "arguments": [
          { "name": "error_message", "description": "오류 메시지 전체", "required": true },
          { "name": "language",      "description": "프로그래밍 언어",   "required": true }
        ]
      },
      {
        "name":        "write-tests",
        "description": "함수나 클래스에 대한 단위 테스트를 작성합니다",
        "arguments": [
          { "name": "framework", "description": "테스트 프레임워크 (pytest, jest, cargo test)", "required": false }
        ]
      }
    ]
  }
}

코드 설명: arguments 배열의 required: true 인자는 prompts/get을 호출할 때 반드시 넘겨야 한다. 없으면 서버가 오류를 반환한다. required: false 인자는 선택 사항이며 서버가 기본값으로 채운다. 클라이언트는 이 메타데이터를 바탕으로 UI를 구성한다 — 필수 인자는 입력 필드를 붉게 표시하거나 빈 채로 제출하지 못하게 막는 식이다. nextCursor가 있으면 프롬프트 목록도 페이지네이션된다.

prompts/get — 인자를 채워서 완성된 messages를 받는다

사람이 프롬프트를 선택하고 인자를 입력하면, 클라이언트는 prompts/get으로 완성된 메시지 배열을 받는다. 이 배열은 LLM 대화의 history 형식과 동일하다.

다이어그램 설명: 사람이 슬래시 명령어를 선택하고 인자를 입력하면, 클라이언트가 prompts/get으로 완성된 messages 배열을 받는다. 클라이언트는 이 배열을 현재 대화 context 앞에 prepend하고, 모델에게 전달한다. 모델은 서버가 설계한 최적 프롬프트 구조를 그대로 받게 된다. 사람은 어떤 프롬프트를 쓸지만 결정하고, 실제 프롬프트 엔지니어링은 서버가 담당한다.

// prompts/get 요청
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "prompts/get",
  "params": {
    "name":      "code-review",
    "arguments": {
      "language": "rust",
      "focus":    "보안"
    }
  }
}

// 응답 — 완성된 messages 배열
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "description": "Rust 보안 코드 리뷰",  // 사람이 읽기 좋은 설명 (선택)
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "다음 Rust 코드를 보안 관점에서 검토해 주세요.\n\n검토 기준:\n- unsafe 블록 사용 여부와 안전성\n- 정수 오버플로 및 패닉 가능성\n- 소유권·수명 관련 메모리 안전성\n- 입력 검증 누락 여부\n\n각 지적 사항은 '심각도: [높음/보통/낮음]' 형식으로 분류해 주세요."
        }
      }
    ]
  }
}

코드 설명: messages 배열은 LLM API의 대화 history 형식과 동일하다. role은 user·assistant·system 중 하나고, content에 타입과 내용이 담긴다. 서버는 인자를 받아 이 배열을 동적으로 생성한다 — Rust라면 Rust 특화 보안 기준을, Python이라면 Python 특화 기준을 담는 식이다. 클라이언트는 이 배열을 현재 대화 앞에 prepend하면 된다. 프롬프트 내용을 모르고, 알 필요도 없다. 서버가 최신 버전으로 업데이트하면 클라이언트는 자동으로 개선된 버전을 쓴다.

messages 내 Resource 참조 — 데이터도 함께 넣는다

messages 배열의 content는 텍스트 외에 resource 타입도 지원한다. 프롬프트 템플릿 안에 특정 Resource 참조를 포함할 수 있다.

// messages 내 resource 타입 content
{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "resource",
        "resource": {
          "uri":      "file:///workspace/src/main.c",
          "mimeType": "text/x-csrc",
          "text":     "#include ..."  // 서버가 미리 읽어서 삽입
        }
      }
    },
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "위 파일을 보안 관점에서 검토해 줘."
      }
    }
  ]
}

코드 설명: 서버가 prompts/get을 처리할 때 Resource의 내용을 직접 읽어서 messages에 삽입할 수 있다. 클라이언트가 따로 resources/read를 호출하지 않아도 된다. 이 패턴은 "프롬프트 + 데이터"를 한 번의 왕복으로 받아오는 효율적인 방식이다. 예를 들어 코드 리뷰 프롬프트가 현재 편집 중인 파일의 내용을 자동으로 포함해서 돌려주는 식이다.

notifications/prompts/list_changed — 프롬프트 목록이 바뀌었다

서버가 새 프롬프트를 추가하거나 기존 프롬프트를 제거하면 클라이언트에게 알린다. 클라이언트는 이 알림을 받고 prompts/list를 다시 호출해서 최신 목록을 가져간다.

다이어그램 설명: notifications/prompts/list_changed는 params가 없다 — "목록이 바뀌었으니 다시 조회해"라는 invalidation 신호만이다. 클라이언트가 prompts/list를 재호출해서 최신 상태를 가져간다. 이 알림 지원 여부는 초기화 핸드셰이크의 capabilities.prompts.listChanged: true로 확인한다. 지원하지 않는 서버라면 클라이언트는 세션 시작 시 한 번 조회한 목록을 계속 쓴다.

completion/complete — 인자 입력 중 자동완성 제공

사람이 프롬프트 인자를 입력하는 도중에 서버에게 후보 값을 물어볼 수 있다. IDE 자동완성과 같은 경험이다. prompts/list에서 받은 arguments 메타데이터만으로는 어떤 값이 유효한지 알 수 없을 때 이 메서드가 유용하다.

// "language" 인자에 "py" 입력 중 → 후보 요청
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",   // 어떤 종류인지 — ref/prompt 또는 ref/resource
      "name": "code-review"   // 어떤 프롬프트의 인자인지
    },
    "argument": {
      "name":  "language",    // 어떤 인자를 완성하는지
      "value": "py"           // 지금까지 입력한 값
    }
  }
}

// 응답 — 후보 목록
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "completion": {
      "values":  ["python", "pypy"],  // "py"로 시작하는 후보들
      "total":   2,                   // 전체 후보 수 (선택)
      "hasMore": false                // 더 있으면 true (100개 초과 시 페이징)
    }
  }
}

코드 설명: ref.type: "ref/prompt"는 이게 프롬프트 인자 자동완성임을 나타낸다. ref/resource라면 리소스 URI 템플릿의 파라미터 자동완성이다. 서버는 argument.value(지금까지 입력한 값)를 prefix로 써서 매칭되는 후보를 돌려준다. 후보가 100개를 넘으면 hasMore: true로 잘려서 오고, 사용자가 더 타이핑하면 다시 물어봐야 한다. 이 메서드가 없어도 Prompts는 동작한다 — 인자 값을 자유 입력으로 받으면 된다. 하지만 있으면 사용자 경험이 훨씬 좋아진다.

실전 시나리오 — 팀 공용 코드 품질 MCP 서버

지금까지 다룬 메서드들이 실제 팀 환경에서 어떻게 조합되는지 보자. 팀의 코드 품질 기준과 리뷰 패턴을 MCP Prompts로 서비스하는 시나리오다.

다이어그램 설명: 개발자가 직접 경험하는 흐름이다. IDE가 시작할 때 한 번 prompts/list를 조회해서 슬래시 명령어를 준비한다. 개발자가 /code-review를 입력하면 인자 입력 폼이 뜨고, completion/complete로 자동완성을 제공한다. 인자를 채우면 prompts/get으로 완성된 프롬프트를 받아 모델에게 전달한다. 팀이 서버에 새 프롬프트를 추가하면 list_changed 알림으로 모든 IDE의 슬래시 명령어가 자동 업데이트된다 — 배포 없이.

Prompts가 주는 것 — 프롬프트 엔지니어링의 분업

MCP Prompts의 핵심 가치는 프롬프트 엔지니어링의 분업이다. 서버를 만드는 팀(또는 개인)이 수많은 시행착오를 거쳐 최적화한 프롬프트를 서버에 봉인한다. 클라이언트를 만드는 팀은 그 결과물을 그냥 가져다 쓴다. 최적 프롬프트가 무엇인지 몰라도 된다.

이 분업이 실제로 중요한 이유가 있다. "언어별로 다른 코드 리뷰 기준", "팀 코딩 스타일에 맞춘 피드백 방식", "도메인별 보안 체크리스트" 같은 지식은 서버 팀이 가장 잘 안다. 이 지식을 프롬프트로 구체화하는 작업은 반복 실험이 필요하다. Prompts는 이 실험 결과를 서버에 가두고, 클라이언트가 매번 재발명하지 않아도 되게 한다. 서버가 프롬프트를 개선할 때 클라이언트는 업데이트 없이 자동으로 더 나은 결과를 받는다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

MCP Resources 완전 분해: URI로 AI에게 데이터를 공급하는 7가지 메서드

타이젠 개발자, 윤진 — Fri, 12 Jun 2026 23:00:30 +0900

지난 글에서 MCP의 세 기본 단위(Tools·Resources·Prompts)를 큰 그림으로 훑었다. 이번 글은 그 중 Resources를 뼈대까지 분해한다. Resources는 5가지 요청 메서드 + 2가지 알림으로 구성되며, "AI가 외부 데이터를 어떻게 읽는가"라는 문제를 URI(Uniform Resource Identifier) 기반 접근 모델로 푼다.

먼저 가장 흔한 오해부터 짚는다. Tools로도 파일을 읽을 수 있는데 왜 Resources가 따로 필요한가?

Tools vs Resources — 같은 파일, 다른 목적

Tools의 read_file 도구와 Resources의 resources/read는 둘 다 파일 내용을 돌려주지만, MCP 명세가 둘을 분리한 이유가 있다. 핵심 차이는 누가 트리거하느냐와 어떻게 쓰이느냐다.

다이어그램 설명: Tool 경로에서는 모델이 "read_file 써줘"라고 먼저 결정하고, 결과를 도구 응답으로 받는다. 모델이 실행을 트리거한다. Resource 경로에서는 클라이언트가 모델이 추론을 시작하기 전에 데이터를 미리 읽어서 context에 삽입한다 — 모델은 파일이 이미 거기 있는 상태에서 대화를 시작한다. 이 차이가 두 경로를 분리한 이유다.

정리하면 이렇다. Tool은 "모델이 실행을 결정하는 동적 행동"이고, Resource는 "클라이언트가 context를 채우는 정적 데이터 공급"이다. 어떤 데이터를 쓸지 모델이 스스로 판단해야 한다면 Tool, 대화 시작 전에 미리 알려줄 수 있다면 Resource가 맞다. 실무에서 둘을 혼용하는 경우가 많지만, Resource를 올바르게 쓰면 모델의 불필요한 "도구 호출 → 읽기" 왕복을 줄여 응답이 빨라진다.

그림: Resources의 7가지 메서드 — 왼쪽 5개는 요청(응답 있음), 오른쪽 2개는 알림(응답 없음)

다이어그램 설명: Resources는 요청 5개와 알림 2개로 구성된다. 요청은 클라이언트가 서버에 보내고 응답을 받는다. 알림은 서버가 클라이언트에게 일방향으로 보내며 id가 없어 응답을 기대하지 않는다. 이 7가지가 Resources의 전부다. 각각을 순서대로 분해해 보자.

resources/list — "이 서버에 무엇이 있나"

Resources를 사용하려면 먼저 무엇이 있는지 알아야 한다. resources/list는 서버가 현재 노출하는 모든 정적 리소스의 목록을 돌려준다. "정적"이란 URI가 고정되어 있는 리소스를 뜻한다 — 특정 파일, 특정 DB 테이블처럼.

// 요청 (params 없음 — 단순 목록 조회)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "resources/list"
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
      {
        "uri":         "file:///workspace/src/main.c",  // 리소스를 가리키는 고유 식별자
        "name":        "main.c",                        // 사람이 읽기 좋은 이름
        "description": "네트워크 연결 모듈 진입점",
        "mimeType":    "text/x-csrc"                    // 콘텐츠 형식 힌트 (선택)
      },
      {
        "uri":         "sqlite:///build.db?table=errors",
        "name":        "build_errors",
        "description": "최근 빌드 오류 로그",
        "mimeType":    "application/json"
      },
      {
        "uri":         "https://docs.internal/api-spec",
        "name":        "API 명세",
        "description": "REST API OpenAPI 스펙",
        "mimeType":    "application/yaml"
      }
    ]
  }
}

코드 설명: uri가 핵심 필드다. 클라이언트는 이 값을 resources/read에 그대로 넘긴다. URI 스키마(file://·sqlite://·https://)는 MCP 명세가 강제하지 않는다 — 서버가 자유롭게 정의한다. 클라이언트는 URI를 opaque string(불투명 문자열)으로 취급하면 되고, 스키마를 해석할 필요 없다. mimeType은 클라이언트가 내용을 어떻게 렌더링할지 결정하는 힌트다 — 없어도 동작하지만 있으면 IDE가 구문 강조를 미리 준비할 수 있다.

응답에 nextCursor 필드가 있으면 목록이 더 있다는 신호다. 서버가 대량의 리소스를 노출하면 한 번에 다 돌려주지 않고 페이지로 나눈다. resources/list?cursor=로 다음 페이지를 요청한다. 전형적인 파일시스템 기반 MCP 서버라면 수백 개의 파일이 있을 수 있어 페이지네이션이 실용적이다.

resources/templates/list — 파라미터로 결정되는 동적 리소스

모든 리소스의 URI가 미리 고정되어 있는 건 아니다. "빌드 작업 번호 42의 로그"는 번호가 바뀌는 동적 리소스다. 이런 리소스를 위해 MCP는 URI 템플릿(RFC 6570 — URL 패턴을 변수로 표현하는 표준)을 별도로 노출한다.

다이어그램 설명: resources/templates/list로 패턴을 먼저 받고, 실제 값(job_id=42)을 채워서 resources/read를 호출하는 2단계 흐름이다. 클라이언트가 {job_id}를 채울 값을 모른다면 completion/complete로 서버에게 후보를 물어볼 수 있다 — 이것이 Resources·Prompts와 자동완성 메서드의 연결 지점이다.

// resources/templates/list 응답
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate":  "log://build/{job_id}",           // {job_id}가 파라미터
        "name":         "build_log",
        "description":  "빌드 작업별 실시간 로그",
        "mimeType":     "text/plain"
      },
      {
        "uriTemplate":  "db://users/{user_id}/profile",
        "name":         "user_profile",
        "description":  "사용자 프로필 레코드",
        "mimeType":     "application/json"
      },
      {
        "uriTemplate":  "git://commits/{branch}/{sha}",   // 복수 파라미터도 가능
        "name":         "git_commit",
        "description":  "특정 커밋의 diff",
        "mimeType":     "text/x-diff"
      }
    ]
  }
}

코드 설명: uriTemplate의 {변수명}은 RFC 6570 레벨 1 변수다. 클라이언트는 실제 값으로 대입해서 완성된 URI를 만들고 resources/read에 넘긴다. 예를 들어 log://build/{job_id}에 job_id=42를 넣으면 log://build/42가 된다. 서버는 이 패턴을 파싱해서 실제 데이터를 가져오는 로직을 갖고 있다 — 클라이언트는 URI 스키마의 의미를 몰라도 된다.

resources/read — URI를 넘기면 내용이 온다

resources/read는 Resources의 본론이다. URI 하나를 보내면 그 리소스의 실제 내용이 contents 배열로 온다. 텍스트와 바이너리 둘 다 처리한다.

// 텍스트 리소스 읽기
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "resources/read",
  "params": { "uri": "file:///workspace/src/main.c" }
}

// 텍스트 응답
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "contents": [
      {
        "uri":      "file:///workspace/src/main.c",
        "mimeType": "text/x-csrc",
        "text":     "#include \n\nint main(int argc, char **argv) {\n    ..."
        // text 필드: UTF-8 텍스트. 바이너리라면 이 자리에 blob 필드가 온다
      }
    ]
  }
}

// 바이너리 리소스 읽기 (예: 이미지, PDF)
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "contents": [
      {
        "uri":      "file:///workspace/docs/architecture.png",
        "mimeType": "image/png",
        "blob":     "iVBORw0KGgoAAAANSUhEUgAAA..."  // base64 인코딩
        // text와 blob은 배타적 — 둘 중 하나만 온다
      }
    ]
  }
}

코드 설명: contents가 배열인 이유가 있다. 하나의 URI가 논리적으로 여러 내용 조각을 가리킬 수 있다 — 예를 들어 DB 테이블 URI가 여러 행을 각각 별도 항목으로 돌려줄 수 있다. text와 blob은 배타적이다. text는 UTF-8로 인코딩된 일반 텍스트, blob은 base64로 인코딩된 바이너리다. 클라이언트는 mimeType을 보고 어느 쪽을 기대할지 판단한다. 이미지·PDF 같은 바이너리도 이 경로로 모델에게 공급할 수 있다는 점이 Resources의 범용성이다.

resources/subscribe — 변경을 기다리지 않고 통보받는다

파일을 한 번 읽고 끝내는 게 아니라, 그 파일이 바뀌면 자동으로 알고 싶을 때가 있다. 빌드 로그가 실시간으로 쌓이거나, 설정 파일이 외부 프로세스에 의해 갱신되는 상황이 그렇다. resources/subscribe가 이 문제를 푼다.

다이어그램 설명: subscribe → (외부 변경 발생) → 알림 수신 → read → unsubscribe의 전형적인 흐름이다. 핵심은 "push 알림 + pull 데이터" 패턴이다. notifications/resources/updated는 "바뀌었다"는 신호만 보내고, 실제 내용은 클라이언트가 resources/read로 다시 가져간다. 알림에 바뀐 내용을 싣지 않는 이유 — 클라이언트가 원할 때만 읽어가게 해서 불필요한 데이터 전송을 막는다. 구독 지원 여부는 초기화 핸드셰이크의 capabilities.resources.subscribe: true로 확인한다.

// resources/subscribe 요청
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "resources/subscribe",
  "params": { "uri": "file:///config/app.yaml" }
}

// 응답 — 빈 객체, "구독 시작됐어" 신호만
{ "jsonrpc": "2.0", "id": 5, "result": {} }

// (나중에) 서버 → 클라이언트: 변경 알림
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",   // id 없음 = 알림
  "params": { "uri": "file:///config/app.yaml" } // 뭐가 바뀌었는지만 알림
}

// resources/unsubscribe 요청
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "resources/unsubscribe",
  "params": { "uri": "file:///config/app.yaml" }
}

// 응답
{ "jsonrpc": "2.0", "id": 6, "result": {} }

코드 설명: notifications/resources/updated에는 변경된 URI만 들어 있다 — 바뀐 내용은 없다. 서버가 내용을 알림에 싣지 않는 건 설계상 의도다. 변경 내용이 크면 클라이언트가 필요 없을 수도 있고, 클라이언트가 원할 때 pull하는 편이 흐름 제어에 유리하다. resources/unsubscribe를 빠뜨리면 세션 내내 서버가 알림을 보내므로, 더 이상 필요 없을 때 반드시 해제해야 한다. 실제 서버 구현에서 구독 상태는 클라이언트 연결 범위와 함께 관리되는 게 일반적이다 — 연결이 끊어지면 모든 구독이 자동 해제된다.

notifications/resources/list_changed — 목록 자체가 바뀌었다

notifications/resources/updated가 특정 리소스의 내용 변경이라면, notifications/resources/list_changed는 리소스 목록의 변경이다. 새 파일이 추가되거나 기존 리소스가 사라질 때 서버가 클라이언트에게 보내는 힌트다.

// 서버 → 클라이언트: 리소스 목록 변경 알림
{
  "jsonrpc": "2.0",
  "method": "notifications/resources/list_changed"
  // params 없음 — "목록이 바뀌었으니 다시 list 해줘"라는 신호만
}

// 클라이언트는 이 알림을 받으면 resources/list를 다시 호출한다
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "resources/list"
}
// 새로 추가된/제거된 리소스가 반영된 목록이 온다

코드 설명: params가 없다 — 어떤 리소스가 추가/제거됐는지 알려주지 않는다. "뭔가 바뀌었으니 다시 조회해"라는 invalidation 신호만이다. 이 패턴은 "push invalidation + pull data"의 전형이다. 구체적인 변경 내용을 알림에 싣지 않는 이유는 두 가지다. 첫째, 변경이 연속으로 여러 번 오면 알림을 여러 번 보내지 않고 한 번만 보낼 수 있다. 둘째, 클라이언트가 관심 없는 리소스도 있으므로 필요한 것만 pull해 가게 한다.

중요한 점은 notifications/resources/list_changed는 resources/subscribe와 완전히 무관하다는 것이다. 클라이언트가 구독 요청을 따로 보낼 필요가 없다. 서버가 초기 핸드셰이크에서 capabilities.resources.listChanged: true를 선언하면, 이후 목록 변경이 발생할 때마다 서버가 자동으로 이 알림을 전송한다. 지원 여부는 서버 capabilities 하나로만 결정된다.

실전 시나리오 — 소스코드 분석 MCP 서버

지금까지의 7가지 메서드가 실제로 어떻게 조합되는지 보자. 소스코드 저장소를 Resources로 노출하는 MCP 서버 시나리오다.

다이어그램 설명: 세션 시작 시 resources/list와 resources/templates/list로 무엇이 있는지 파악한다. 실제 분석 작업에서는 resources/read로 내용을 가져온다. 빌드 로그 같은 실시간 데이터는 subscribe로 변경 알림을 받고 그때그때 read한다. 파일이 새로 추가되면 list_changed 알림 → 재조회로 최신 상태를 유지한다. 7가지 메서드가 각자 역할을 맡아 하나의 자연스러운 워크플로우를 이룬다.

Resources가 주는 것 — Tools 대비 얻는 것 3가지

Resources를 Tool 대신 쓸 때 실제로 무엇이 좋아지는지 구체적으로 정리한다.

1. 모델의 추론 왕복 제거. Tool로 파일을 읽으면 모델이 "read_file을 호출해야겠다"고 결정하고, 호출하고, 결과를 받고, 그 다음 추론을 이어간다. Resource를 context에 미리 삽입하면 이 왕복이 사라진다. 대화 응답 시간이 빨라진다.

2. context 공유. 클라이언트가 여러 Resource를 한꺼번에 context에 넣으면, 모델은 처음부터 전체 그림을 보고 추론한다. Tool은 모델이 하나씩 호출하면서 점진적으로 파악한다. 파일 3개를 비교해야 할 때 Resource가 더 유리하다.

3. subscribe로 실시간 데이터 연동. Tool은 호출 시점의 스냅샷을 준다. Resource의 subscribe는 데이터가 바뀔 때마다 클라이언트가 알 수 있다. 빌드 로그, 센서 데이터, 실시간 DB 같은 변화하는 데이터를 모델 context에 반영할 수 있다 — Tool만으로는 구현하기 까다로운 시나리오다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

MCP가 JSON-RPC 봉투 안에 채운 것들: 세 기본 단위와 20가지 메서드 전체 지도

타이젠 개발자, 윤진 — Fri, 12 Jun 2026 22:00:45 +0900

지난 글에서 JSON-RPC 2.0이 봉투 6단어(jsonrpc·id·method·params·result·error)만 정의하고, 그 안의 내용물은 전부 상위 계층이 채운다는 걸 짚었다. 그 상위 계층이 바로 MCP(Model Context Protocol)다. 이번 글은 MCP가 봉투 안에 실제로 뭘 채웠는지를 다룬다 — 메서드 이름, params 구조, result 구조, 그리고 각 메서드가 왜 필요하고 언제 쓰이는지.

MCP의 메서드는 현재 20여 개다. 흩어져 보이지만 세 기본 단위(Tools·Resources·Prompts)와 초기화·보조 카테고리로 묶으면 구조가 선명해진다. 가장 중요한 발견을 먼저 꺼내자면 — MCP는 단방향이 아니다. 서버가 클라이언트에게 LLM 호출을 위임(sampling/createMessage)하거나, 클라이언트가 보유한 파일 시스템 루트 목록을 서버가 물어보는(roots/list) 역방향 흐름이 프로토콜 안에 설계되어 있다. 이 역방향을 이해해야 MCP 아키텍처 전체가 보인다.

세 기본 단위 — Tools·Resources·Prompts

MCP 명세는 AI 모델이 외부 세계와 상호작용할 수 있는 경로를 세 개로 분류한다.

그림: MCP의 세 기본 단위 — 각각 두 개의 메서드 쌍(list/call)으로 노출된다

다이어그램 설명: 세 단위는 목적이 분명히 다르다. Tools는 모델이 실행하고 결과를 받는 "행동", Resources는 모델이 문맥으로 읽어들이는 "데이터", Prompts는 사람이 골라서 대화에 끼우는 "템플릿"이다. 이 구분이 명세 전반에 걸쳐 일관되게 유지된다 — 메서드 이름의 접두어(tools/·resources/·prompts/)가 곧 이 분류를 따른다.

왜 중요한가: 셋을 구분하는 게 API 설계의 의도를 읽는 열쇠다. "이 도구를 왜 Tool로 안 만들고 Resource로 만들었지?"라는 질문의 답이 이 분류에 있다 — 모델이 직접 실행해서 결과를 만들면 Tool, 읽어서 맥락으로 쓰면 Resource다.

초기화 핸드셰이크 — initialize와 notifications/initialized

클라이언트(LLM 에이전트)와 서버가 처음 만날 때 반드시 거쳐야 하는 단계가 있다. 서로 어떤 기능을 지원하는지 협상(capability negotiation)하는 핸드셰이크다. 이 없이는 tools/list를 보내도 서버가 거부할 수 있다 — 아직 준비 안 됐으니까.

다이어그램 설명: 세 단계 핸드셰이크다. 1) 클라이언트가 initialize를 보내면서 자신의 버전과 capabilities(지원하는 기능 목록)를 알린다. 2) 서버가 자신의 capabilities로 응답한다. 3) 클라이언트가 notifications/initialized를 보내면 세션이 활성화된다. 세 번째 단계가 "알림(notification)"인 게 중요 — id가 없으므로 서버는 응답을 돌려보내지 않는다. 클라이언트의 일방적인 "나 준비 끝" 신호다.

// 1단계: 클라이언트 → 서버 (initialize 요청)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",     // MCP 명세 버전
    "capabilities": {
      "roots": { "listChanged": true },  // 클라이언트가 roots/list_changed 알림을 보낼 수 있음
      "sampling": {}                     // 클라이언트가 sampling/createMessage를 처리할 수 있음
    },
    "clientInfo": {
      "name": "claude-code",
      "version": "1.0.0"
    }
  }
}

// 2단계: 서버 → 클라이언트 (응답)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2024-11-05",     // 합의된 버전
    "capabilities": {
      "tools": { "listChanged": true },  // 도구 목록이 바뀌면 알림 보낼 수 있음
      "resources": {
        "subscribe": true,               // 리소스 변경 구독 지원
        "listChanged": true
      },
      "prompts": { "listChanged": true },
      "logging": {}
    },
    "serverInfo": {
      "name": "mcp-server",
      "version": "0.9.0"
    }
  }
}

// 3단계: 클라이언트 → 서버 (알림, id 없음 → 응답 없음)
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

코드 설명: capabilities 객체가 핵심이다. "나는 이런 기능을 지원한다"는 선언이지, "나는 이 기능을 사용하겠다"는 요청이 아니다. 클라이언트가 sampling: {}을 넣으면 "서버야, 나한테 LLM 호출을 위임해도 돼"라는 뜻이다. 서버가 tools.listChanged: true를 넣으면 "내 도구 목록이 바뀌면 알림 보낼게"라는 뜻이다. 이 협상이 끝난 후에야 해당 기능이 활성화된다. protocolVersion은 클라이언트가 먼저 제안하고 서버가 자신이 지원하는 버전으로 응답한다 — 버전이 안 맞으면 연결을 끊는다.

왜 중요한가: 핸드셰이크를 건너뛰거나 순서를 바꾸면 서버 구현에 따라 이후 모든 요청이 -32603 Internal error로 거부된다. MCP 클라이언트를 직접 만들 때 가장 흔한 실수 1위가 이 순서를 빠뜨리는 것이다.

Tools — 모델이 실행하는 함수

가장 많이 쓰이는 카테고리다. 이전 글에서 tools/list와 tools/call의 JSON 모양을 다뤘으니 여기서는 설계 원칙과 심화 내용에 집중한다.

다이어그램 설명: tools/list → tools/call 흐름이다. 모델 자체는 MCP를 직접 호출하지 않는다 — 항상 클라이언트(Claude Code, Cursor 등 에이전트 런타임)가 중간에서 중계한다. 모델이 "build-app 써줘"라고 말하면 클라이언트가 tools/call을 MCP 서버에 보내고, 결과를 받아 다시 모델에게 전달한다. 이 삼각 구도가 MCP 전체 흐름의 기본 패턴이다.

tools/call 응답의 content 배열은 여러 형식을 섞을 수 있다. 텍스트 결과만 돌려주는 게 아니라 이미지나 리소스 참조도 포함할 수 있다.

// tools/call 응답 — content 배열의 세 가지 타입
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "content": [
      // 타입 1: 텍스트
      { "type": "text", "text": "빌드 성공. 출력: app-release-arm64.pkg" },

      // 타입 2: 이미지 (base64 인코딩)
      { "type": "image", "data": "iVBORw0KGgo...", "mimeType": "image/png" },

      // 타입 3: 리소스 참조 (서버 리소스를 URI로 가리킴)
      {
        "type": "resource",
        "resource": {
          "uri": "file:///app/build/report.html",
          "mimeType": "text/html"
        }
      }
    ],
    "isError": false          // true면 도구는 실행됐지만 오류 발생 (JSON-RPC 에러와 다름)
  }
}

코드 설명: isError: true와 JSON-RPC의 error 필드는 의미가 다르다. isError: true는 "도구는 정상 실행됐는데 도구의 로직이 실패를 보고"하는 것이다 — 예를 들어 빌드 오류. JSON-RPC의 error는 "도구를 실행하기 전에 프로토콜 수준에서 실패"한 것이다 — 예를 들어 인자 형식 오류. 클라이언트는 둘을 다르게 처리해야 한다: isError: true면 모델에게 실패 내용을 전달하고 재시도를 허용하고, JSON-RPC error면 재시도 전에 인자 자체를 수정해야 한다.

Resources — 모델이 읽는 데이터

Resources는 MCP 서버가 외부 데이터를 모델에게 공급하는 경로다. 파일, 데이터베이스 레코드, API 응답, 로그 같은 것들이 URI(Uniform Resource Identifier, URL처럼 리소스를 고유하게 가리키는 식별자)로 식별되어 노출된다. Tools와의 결정적 차이 — Resources는 모델이 직접 실행하지 않고, 클라이언트가 context에 삽입한다.

Resources에는 정적 리소스 외에 URI 템플릿도 있다. 고정 파일 경로가 아니라 파라미터로 동적으로 결정되는 리소스를 노출할 때 쓴다.

// resources/list 응답
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "resources": [
      {
        "uri": "file:///src/main.c",
        "name": "main.c",
        "description": "연결 모듈 진입점",
        "mimeType": "text/x-csrc"
      },
      {
        "uri": "sqlite:///build.db?table=jobs",
        "name": "build_jobs",
        "description": "빌드 작업 이력",
        "mimeType": "application/json"
      }
    ]
  }
}

// resources/templates/list 응답 — URI 템플릿 (RFC 6570 형식)
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "resourceTemplates": [
      {
        "uriTemplate": "log://build/{job_id}",  // {job_id}가 파라미터
        "name": "build_log",
        "description": "빌드 작업별 로그",
        "mimeType": "text/plain"
      }
    ]
  }
}

// resources/read — 실제 파일 내용 요청
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "resources/read",
  "params": { "uri": "file:///src/main.c" }
}

// resources/read 응답
{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "contents": [
      {
        "uri": "file:///src/main.c",
        "mimeType": "text/x-csrc",
        "text": "#include \nint main() { ... }"  // 텍스트면 text, 바이너리면 blob
      }
    ]
  }
}

코드 설명: URI 스키마는 MCP가 강제하지 않는다 — file://·sqlite://·log:// 모두 서버가 자유롭게 정의한다. 클라이언트가 opaque string으로 취급하면 된다. URI 템플릿의 {job_id}는 RFC 6570(URI Template) 표준으로, 클라이언트가 실제 값으로 채워서 resources/read에 보낸다. contents 배열의 각 항목은 text(UTF-8 텍스트) 또는 blob(base64 바이너리) 중 하나다 — 이미지·PDF 같은 바이너리 리소스도 이 경로로 노출된다.

resources/subscribe — 변경 감지

MCP는 리소스 내용이 바뀌면 서버가 클라이언트에게 알릴 수 있는 구독 메커니즘도 갖고 있다. 파일을 편집 중인데 그 파일이 다른 프로세스에 의해 바뀌면 자동으로 알림이 온다.

다이어그램 설명: subscribe → (변경 알림) → read → unsubscribe의 전형적인 흐름이다. notifications/resources/updated는 서버에서 클라이언트로 가는 알림 — 응답을 기대하지 않는다. 알림을 받은 클라이언트가 직접 resources/read를 다시 보내서 새 내용을 가져온다. "push 알림 + pull 데이터"의 패턴이다. resources/subscribe가 지원되는지는 초기화 핸드셰이크의 capabilities.resources.subscribe: true로 확인한다.

Prompts — 재사용 프롬프트 템플릿

Prompts는 MCP의 세 기본 단위 중 가장 오해받는다. Tools도 Resources도 아닌 세 번째 — 서버가 "이런 방식으로 나를 사용하면 잘 돌아가"라는 사용 패턴을 미리 정의해두는 것이다. 사람이 명시적으로 선택해서 대화에 끼우는 템플릿이라는 점에서 Tools(모델이 자율 실행)·Resources(context 삽입)와 다르다.

다이어그램 설명: 모델이 아니라 사람이 프롬프트를 선택한다는 점이 Tools 흐름과 다르다. IDE 플러그인이 슬래시 명령어 드롭다운으로 prompts/list를 보여주고, 사람이 고르면 prompts/get으로 완성된 메시지 배열을 받아 대화에 끼워 넣는 식이다.

// prompts/list 응답
{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "prompts": [
      {
        "name": "code-review",
        "description": "코드를 검토하고 개선점을 제안합니다",
        "arguments": [
          { "name": "language", "description": "프로그래밍 언어", "required": true },
          { "name": "focus",    "description": "리뷰 초점 (성능/보안/가독성)", "required": false }
        ]
      }
    ]
  }
}

// prompts/get — 인자를 채워서 완성된 프롬프트 요청
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "prompts/get",
  "params": {
    "name": "code-review",
    "arguments": { "language": "rust", "focus": "보안" }
  }
}

// prompts/get 응답 — messages 배열로 돌아옴
{
  "jsonrpc": "2.0",
  "id": 6,
  "result": {
    "description": "Rust 보안 코드 리뷰",
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "다음 Rust 코드를 보안 관점에서 검토해주세요. unsafe 블록, 정수 오버플로, 메모리 안전성을 중점으로..."
        }
      }
    ]
  }
}

코드 설명: messages 배열은 LLM 대화의 history 형식과 같다 — role이 user·assistant·system 중 하나고, content에 메시지 내용이 담긴다. 클라이언트는 이 배열을 그대로 대화 context에 prepend하면 된다. 인자(arguments)를 받아 템플릿을 채우는 로직은 서버 안에 있다 — 클라이언트는 인자만 넘기고 완성된 메시지를 받는다. 이 덕분에 MCP 서버를 만드는 팀이 "최적 프롬프트"를 서버에 캡슐화하고, 클라이언트는 그냥 따른다.

역방향의 충격 — sampling/createMessage

여기서 MCP의 가장 독특한 설계가 나온다. 지금까지는 클라이언트가 서버에게 요청을 보내는 흐름이었다. sampling/createMessage는 반대다 — 서버가 클라이언트에게 "LLM 호출을 대신 해줘"라고 요청한다.

다이어그램 설명: 서버가 클라이언트에게 JSON-RPC 요청을 보낸다. 방향이 완전히 뒤집혔다. 서버는 LLM API 키를 갖고 있지 않아도 된다 — LLM 접근 권한은 클라이언트가 갖고 있다. 클라이언트는 이 요청을 받았을 때 사람에게 확인을 구하거나 자동으로 처리하거나 거부할 수 있다. 이 승인 단계가 MCP에서 Human-in-the-Loop(사람의 중간 개입)를 구현하는 표준 방법이다.

// 서버 → 클라이언트: sampling/createMessage 요청
{
  "jsonrpc": "2.0",
  "id": 100,
  "method": "sampling/createMessage",
  "params": {
    "messages": [
      {
        "role": "user",
        "content": {
          "type": "text",
          "text": "다음 C 코드에서 parse_request의 실제 의도를 한 문장으로 요약해줘:\n[코드 스니펫]"
        }
      }
    ],
    "modelPreferences": {
      "hints": [{ "name": "claude-3-5-haiku" }],   // 선호 모델 힌트 (강제 아님)
      "speedPriority": 0.9,                          // 0=품질, 1=속도
      "intelligencePriority": 0.3
    },
    "systemPrompt": "너는 연결 모듈 전문가다.",
    "maxTokens": 200
  }
}

// 클라이언트 → 서버: 응답 (클라이언트가 LLM을 호출한 결과)
{
  "jsonrpc": "2.0",
  "id": 100,
  "result": {
    "role": "assistant",
    "content": {
      "type": "text",
      "text": "parse_request는 HTTP 요청 버퍼를 파싱해 구조체로 변환하는 비동기 진입점이다."
    },
    "model": "claude-3-5-haiku-20241022",     // 실제 사용된 모델
    "stopReason": "end_turn"
  }
}

코드 설명: modelPreferences는 서버가 선호를 "힌트"로 제안하는 것이지 강제가 아니다 — 클라이언트가 실제로 어떤 모델을 쓸지는 클라이언트가 결정한다. speedPriority·intelligencePriority는 0~1 사이 값으로 트레이드오프를 표현한다. 응답에 model 필드가 있어서 서버는 실제로 어떤 모델이 답했는지 알 수 있다. 이 메커니즘이 가능하려면 초기화 핸드셰이크에서 클라이언트가 capabilities.sampling: {}을 선언했어야 한다 — 선언하지 않은 클라이언트에게 서버가 sampling/createMessage를 보내면 -32601 Method not found가 온다.

왜 중요한가: 이 설계의 핵심은 "LLM 접근을 클라이언트가 독점한다"는 것이다. 서버는 LLM에 직접 접근하지 않는다 — 클라이언트에게 위임한다. 그래서 API 키 관리·비용 제어·사용자 승인이 한 곳(클라이언트)에서 통제된다. 서버가 악의적이어도 클라이언트가 모든 LLM 호출을 검토할 수 있다는 보안 모델이기도 하다.

roots/list — 클라이언트의 파일시스템을 서버가 물어본다

sampling/createMessage처럼 역방향인 메서드가 하나 더 있다. roots/list는 서버가 클라이언트에게 "너는 어떤 파일시스템 루트에 접근 권한이 있니?"를 묻는다. IDE 플러그인이 MCP 클라이언트라면, 현재 열려 있는 프로젝트 디렉토리를 roots로 노출한다.

// 서버 → 클라이언트: 내가 접근할 수 있는 디렉토리 목록 요청
{
  "jsonrpc": "2.0",
  "id": 101,
  "method": "roots/list"
}

// 클라이언트 → 서버: 현재 열린 작업 공간
{
  "jsonrpc": "2.0",
  "id": 101,
  "result": {
    "roots": [
      { "uri": "file:///home/user/projects/my-app",     "name": "my-app" },
      { "uri": "file:///home/user/projects/shared-lib", "name": "shared-lib" }
    ]
  }
}

코드 설명: 서버는 이 응답으로 어떤 경로를 resources/read로 노출할지, 어떤 범위에서 파일을 검색할지를 결정한다. 클라이언트가 루트 목록을 바꾸면(새 프로젝트 열기, 기존 닫기) notifications/roots/list_changed 알림을 서버에게 보내고, 서버는 roots/list를 다시 요청한다. "클라이언트가 제공하는 컨텍스트 범위를 서버가 동적으로 따라간다"는 설계다.

알림(Notifications) 시스템 — 일방향 신호들

MCP의 알림은 id 없이 보내는 일방향 메시지다. 응답을 기대하지 않는다. 크게 세 카테고리로 묶인다 — 초기화 신호, 변경 감지, 진행 상황.

다이어그램 설명: 알림도 방향이 있다. 클라이언트에서 서버로 가는 것(3개)과 서버에서 클라이언트로 가는 것(6개)이 따로 있다. 가장 자주 마주치는 것들: notifications/progress는 긴 작업의 중간 진행률 업데이트(프론트엔드 프로그레스 바에 해당), notifications/tools/list_changed는 "내 도구 목록 바뀌었으니 다시 tools/list 해줘"라는 힌트, notifications/cancelled는 클라이언트가 이미 보낸 요청을 취소할 때 쓴다.

// notifications/progress — 긴 작업의 진행률 알림 (서버 → 클라이언트)
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": "build-42",   // 원래 요청에 붙인 progressToken과 같은 값
    "progress": 73,                // 현재 진행 (단위는 서버 자유)
    "total": 100                   // 총량 (선택 — 없으면 클라이언트가 진행바를 indeterminate로 표시)
  }
}

// notifications/cancelled — 클라이언트가 요청 취소 (클라이언트 → 서버)
{
  "jsonrpc": "2.0",
  "method": "notifications/cancelled",
  "params": {
    "requestId": 7,               // 취소할 요청의 id
    "reason": "user requested"    // 선택: 취소 이유
  }
}

// notifications/message — 서버 로그 메시지 (서버 → 클라이언트)
{
  "jsonrpc": "2.0",
  "method": "notifications/message",
  "params": {
    "level": "warning",   // debug | info | warning | error
    "logger": "build-runner",
    "data": "빌드 디렉토리 쓰기 권한 없음, 임시 디렉토리로 대체"
  }
}

코드 설명: notifications/progress를 사용하려면 원래 요청(tools/call 등)의 params에 progressToken을 넣어야 한다. 서버는 이 토큰을 받으면 "이 클라이언트는 진행률 알림을 원한다"는 신호로 알고 중간중간 알림을 보낸다. 토큰이 없으면 서버는 알림을 보내지 않는다. notifications/message의 level은 Python logging과 같은 레벨 체계다 — 클라이언트는 이를 받아 IDE 콘솔이나 로그 패널에 표시한다.

logging/setLevel — 서버 로그 제어

서버가 notifications/message로 얼마나 상세한 로그를 보낼지를 클라이언트가 제어한다. 배포 환경에서는 warning, 디버깅할 때는 debug로 동적으로 바꿀 수 있다.

// logging/setLevel — 클라이언트 → 서버
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "logging/setLevel",
  "params": {
    "level": "debug"   // debug | info | notice | warning | error | critical | alert | emergency
  }
}

// 응답
{ "jsonrpc": "2.0", "id": 10, "result": {} }

코드 설명: 8단계 레벨은 syslog 표준을 따른다. debug → info → notice → warning → error → critical → alert → emergency 순서로 심각도가 높아진다. 서버는 설정된 레벨 이상의 메시지만 notifications/message로 보낸다. 응답이 빈 객체({})라는 게 특징 — "성공했다"는 신호만 준다. 이 메서드가 지원되는지도 초기화 핸드셰이크의 capabilities.logging: {}으로 확인한다.

completion/complete — 인자 자동완성

IDE의 자동완성처럼, 클라이언트가 "이 Tool·Prompt의 이 인자에 어떤 값을 넣으면 되나요?"를 서버에게 실시간으로 물어보는 메서드다. 사람이 MCP 서버 UI에서 인자를 입력할 때 도움이 된다.

// completion/complete 요청
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "completion/complete",
  "params": {
    "ref": {
      "type": "ref/prompt",           // ref/prompt 또는 ref/resource
      "name": "code-review"           // 어떤 프롬프트/리소스의 인자인지
    },
    "argument": {
      "name": "language",             // 어떤 인자를 자동완성하는지
      "value": "ru"                   // 지금까지 입력한 값
    }
  }
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 11,
  "result": {
    "completion": {
      "values": ["rust", "ruby", "r"],  // 후보 목록 (최대 100개)
      "total": 3,                       // 전체 후보 수 (선택)
      "hasMore": false                  // 더 있으면 true (페이징)
    }
  }
}

코드 설명: ref.type이 ref/prompt면 프롬프트 인자 자동완성, ref/resource면 리소스 URI 템플릿 파라미터 자동완성이다. 예를 들어 uriTemplate: "log://build/{job_id}"에서 job_id에 어떤 값이 들어가는지 서버에게 물어볼 수 있다. 후보 목록이 100개를 넘으면 hasMore: true로 잘려서 오고, 사용자가 더 입력할 때 다시 물어봐야 한다.

전체 메서드 지도

그림: MCP 전체 메서드 — 파란 화살표는 클라이언트→서버, 빨간 화살표는 서버→클라이언트(역방향)

다이어그램 설명: 메서드를 5개 그룹으로 묶었다. 초기화(파란 테두리)·Tools(남색)·Resources(초록)·Prompts(노랑)는 클라이언트가 시작하는 요청이다. 역방향(빨간 테두리)은 서버가 시작한다 — sampling/createMessage·roots/list·서버발 notifications가 여기 속한다. 보조(보라)는 logging/setLevel·completion/complete처럼 부가 기능이다. 방향 화살표를 다르게 그린 이유는 이 구분이 구현에서 가장 헷갈리는 부분이기 때문이다 — 서버 코드를 짜다 보면 클라이언트로 요청을 보낼 수 있다는 걸 나중에야 알게 되는 경우가 많다.

메서드별 언제/왜 쓰나 — 한 눈에

그림: MCP 메서드 사용 시점과 방향 — 빨간 행이 역방향(서버발)

계층 책임 정리

두 편에 걸쳐 JSON-RPC 2.0과 MCP를 살폈다. 각 계층이 무엇을 책임지고 무엇을 위임하는지 정리하면 이렇다.

JSON-RPC 2.0이 정한 것:
  jsonrpc · id · method · params · result · error (봉투 6단어)
  표준 에러 코드 -32700 ~ -32603
  id 유무로 알림(notification) 구분

MCP가 정한 것:
  method 값: initialize, tools/list, tools/call, resources/list, resources/read,
             resources/templates/list, resources/subscribe, resources/unsubscribe,
             prompts/list, prompts/get, sampling/createMessage, roots/list,
             logging/setLevel, completion/complete, notifications/* (20여 개)
  params 구조: 메서드별 별도 명세
  result 구조: 메서드별 별도 명세
  capabilities 협상 모델 (핸드셰이크)
  세 기본 단위 분류 (Tools·Resources·Prompts)

MCP 서버 개발자가 정하는 것:
  도구별 inputSchema (JSON Schema 형식)
  도구별 반환 페이로드 (content 배열의 내용)
  리소스 URI 스키마 및 실제 데이터
  프롬프트 템플릿 내용
  어떤 capabilities를 지원할지

코드 설명: 세 계층은 책임이 분리되어 있고, 각 계층의 변경이 다른 계층에 영향을 주지 않는다. MCP가 새 메서드를 추가해도 JSON-RPC 봉투는 그대로다. 서버 개발자가 새 도구를 추가해도 MCP 명세는 그대로다. 이 분리가 MCP 생태계가 중앙 조율 없이 확장될 수 있는 이유다.

MCP 서버를 직접 만들어보면 이 계층 구분이 구체적으로 와닿는다 — tools/call을 처리하는 핸들러를 짤 때, 내가 건드리는 건 content 배열의 내용물뿐이다. JSON-RPC 봉투를 싸는 건 MCP SDK가 하고, MCP의 result 구조도 SDK가 안다. 내가 새 도구를 만든다는 건 "이 이름·이 inputSchema·이 반환 페이로드"를 SDK에 등록하는 것뿐이다. 봉투 계층에서 손댈 게 없다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

JSON-RPC 2.0이 정의하는 건 봉투 6단어뿐: MCP 사례로 그 안과 밖을 가른다

타이젠 개발자, 윤진 — Fri, 12 Jun 2026 21:00:03 +0900

MCP(Model Context Protocol, AI 모델과 외부 도구·데이터를 잇는 공개 표준 — 흔히 "AI용 USB-C 포트"라 불린다) 서버를 직접 개발하려고 명세를 펼쳐보면, 와이어 포맷이 두 종류의 약속이 포개진 모양을 하고 있다. 가장 바깥은 JSON-RPC 2.0이라는 호출 규약, 그 안은 MCP가 메서드별로 정한 구조다. inputSchema·content·tools/call 같은 이름이 어느 쪽 약속에 속하는지부터 헷갈리는 게 보통이다. 결론부터 적으면 JSON-RPC는 봉투 6단어만 정의하고, 그 안의 내용물은 전부 MCP가 채운다. MCP를 다루기 전에 그 봉투부터 먼저 짚고 넘어가자 — 이 글은 JSON-RPC 2.0의 봉투 6단어를 MCP 도구 호출 사례로 풀어본다.

배경: JSON-RPC 2.0이 정의하는 것의 전부

JSON-RPC 2.0은 원격 함수 호출(Remote Procedure Call, 다른 프로세스의 함수를 마치 로컬 함수처럼 호출하는 패턴) 규약 중 가장 가벼운 축에 든다. HTTP REST가 URL·메서드(GET/POST)·헤더로 의미를 표현하는 반면, JSON-RPC는 그런 거 다 빼고 모든 호출을 단일 JSON 객체로 통일한다. 전송 계층(transport)도 정해두지 않는다 — HTTP·stdio(표준 입출력)·WebSocket 무엇이든 좋다. MCP는 주로 stdio를 쓴다.

그래서 JSON-RPC가 정의하는 건 메시지 두 가지 모양뿐이다 — 요청(Request)과 응답(Response). 각각 필드 네다섯 개로 끝난다.

요청(Request) — 4필드

{
  "jsonrpc": "2.0",       // 규약 버전 — 항상 "2.0" 문자열
  "id": 7,                // 이 호출의 고유 번호 (응답에서 그대로 돌아온다)
  "method": "tools/call", // 호출할 메서드 이름
  "params": { ... }       // 메서드 인자 (객체 또는 배열, 선택)
}

코드 설명: 네 필드 중 jsonrpc·method는 필수, id는 응답을 짝지을 때 필수(생략하면 "알림"이 된다 — 뒤에서 다룬다), params는 메서드가 인자를 받을 때만 둔다. method 값이 tools/call인지 resources/read인지 JSON-RPC는 모른다 — 그건 윗 계층(MCP)이 정한 이름이고, JSON-RPC 입장에서는 그냥 문자열이다.

응답(Response) — 성공이면 result, 실패면 error

// 성공
{
  "jsonrpc": "2.0",
  "id": 7,            // 요청과 같은 번호
  "result": { ... }   // 성공 시의 반환값 (임의 JSON)
}

// 실패
{
  "jsonrpc": "2.0",
  "id": 7,
  "error": {
    "code": -32602,    // 표준 에러 코드
    "message": "Invalid params",
    "data": { ... }    // 부가 정보 (선택)
  }
}

코드 설명: 성공이면 result가, 실패면 error가 들어온다 — 둘은 동시에 존재할 수 없다. id는 요청 때 보낸 값을 그대로 돌려주므로 클라이언트는 응답이 어느 호출에 대응되는지 안다(stdio처럼 응답 순서가 보장되지 않는 전송에서 특히 중요). error.code의 -32700~-32603은 JSON-RPC가 예약한 표준값이고, -32099~-32000은 구현이 자유롭게 정의하는 범위다.

왜 중요한가: JSON-RPC 규격으로 외울 건 이게 전부다. jsonrpc·id·method·params·result·error — 봉투 6단어. 그 안의 내용물이 어떤 모양이어야 하는지는 JSON-RPC가 일절 말하지 않는다.

사례 1: tools/list — "어떤 도구가 있나요?"

LLM(코딩 어시스턴트)이 MCP 서버에 "지금 쓸 수 있는 도구가 뭐가 있나요?"를 묻는, 가장 흔한 호출부터 보자. 메서드 이름은 tools/list다.

다이어그램 설명: 클라이언트는 id:1을 붙여 보내고, 서버는 같은 id:1을 응답에 박아 돌려준다. JSON-RPC가 보장하는 건 이 봉투의 짝맞춤(id)까지다 — result 안의 tools 배열 모양은 JSON-RPC 명세에 없는 MCP의 별도 약속이다.

// 실제 와이어 (요청)
{ "jsonrpc": "2.0", "id": 1, "method": "tools/list" }

// 실제 와이어 (응답)
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "build-app",
        "description": "프로젝트를 빌드한다",
        "inputSchema": {
          "type": "object",
          "properties": {
            "project_dir":   { "type": "string" },
            "configuration": { "type": "string", "enum": ["Debug", "Release"] },
            "arch":          { "type": "string", "enum": ["arm64", "x86_64"] }
          },
          "required": ["project_dir", "arch"]
        }
      },
      {
        "name": "lint-check",
        "description": "코드 린트 검사를 실행한다",
        "inputSchema": { "type": "object", "properties": {} }
      }
    ]
  }
}

코드 설명: 봉투(jsonrpc·id·result)는 JSON-RPC가 정한 모양이다. 그러나 result.tools[].name·description·inputSchema는 JSON-RPC와 무관하다 — MCP 명세가 "tools/list의 응답은 이런 모양이어야 한다"고 별도로 못 박은 약속이다. 흥미로운 점은 인자 명세(inputSchema, JSON Schema 형식)까지 이 한 번의 응답에 통째로 실려 온다는 것이다 — LLM 클라이언트는 tools/list 한 라운드트립으로 "어떤 도구가 있나"와 "어떤 인자로 불러야 하나"를 동시에 안다. 별도 describe 호출 단계가 없다.

사례 2: tools/call — "이 도구를 이 인자로 실행해줘"

실제 도구를 실행하는 호출이다. method가 tools/call로 고정되고, 어떤 도구를 어떤 인자로 부르는지는 params 안에 한 번 더 객체로 들어간다.

// 요청
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "build-app",
    "arguments": {
      "project_dir": "./app",
      "configuration": "Release",
      "arch": "arm64"
    }
  }
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 7,
  "result": {
    "structuredContent": {
      "exit_code": 0,
      "output": "app-release-arm64.pkg"
    },
    "isError": false
  }
}

코드 설명: 요청에서 method는 항상 tools/call이고, 실제 호출할 도구 이름은 params.name에 들어간다. 즉 JSON-RPC 봉투의 method는 "지금 너에게 시킬 동작 카테고리"이고, 실제 도구 이름은 MCP가 한 단계 더 안쪽에서 다룬다 — JSON-RPC 메서드 이름이 도구마다 늘어나지 않도록 한 설계다. 응답 result 안도 MCP 약속이다 — structuredContent라는 객체 필드에 우리 도구의 JSON이 구조 그대로 실린다. 문자열로 직렬화하지 않으니 클라이언트는 곧바로 result.structuredContent.exit_code처럼 점 접근으로 값을 꺼낸다.

왜 중요한가: 봉투 안의 봉투 구조다. 가장 바깥은 JSON-RPC가 정한 result, 그 안은 MCP가 정한 structuredContent, 다시 그 안은 우리가 정한 { exit_code, output }. 세 층이 각자 한 가지 결정만 책임진다 — 그리고 그 세 층이 다 같은 JSON 트리 안에 자연스럽게 중첩된다.

핵심 질문: 어디까지가 JSON-RPC이고 어디부터가 MCP인가

그림: 세 계층은 각자 다른 표준이 책임진다

다이어그램 설명: 가장 바깥 회색이 JSON-RPC 2.0이 정의하는 6단어다. 그 안 파란 영역이 MCP가 추가한 약속 — 메서드 이름의 값(tools/list·tools/call 등), params 안에 다시 들어가는 name·arguments 구조, result 안에 들어가는 structuredContent·tools·inputSchema 구조. 가장 안쪽 초록은 MCP 서버를 만드는 사람이 자유롭게 정하는 도구별 출력(exit_code·output·job_id 등 — 위 예시는 한 가지 설계안)이고, structuredContent 객체에 그대로 실려 들어간다. 세 층은 각자 한 가지 결정만 책임진다 — 봉투(JSON-RPC) / 도메인 계약(MCP) / 도구별 페이로드(서버 구현자).

왜 중요한가: 같은 JSON-RPC 봉투 위에 MCP·Ethereum JSON-RPC API·Language Server Protocol(LSP)이 전부 얹힐 수 있다 — 봉투는 공유하고 메서드 이름·파라미터·결과 구조만 도메인별로 갈린다. 봉투를 일부러 좁게 둔 덕에 윗 계층이 자유롭게 진화한다.

사례 3: 에러 응답 — params가 잘못됐을 때

LLM이 arch에 스키마가 허용하지 않는 값("ARM")을 넣어 보냈다고 하자. 서버는 도구를 실행하기 전에 inputSchema로 검증하고 에러를 돌려준다.

// 요청 (arch 값이 enum에 없음)
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "build-app",
    "arguments": { "project_dir": "./app", "arch": "ARM" }
  }
}

// 응답
{
  "jsonrpc": "2.0",
  "id": 8,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "field": "arch",
      "expected": ["arm64", "x86_64"],
      "received": "ARM"
    }
  }
}

코드 설명: 응답에 result 대신 error가 온다. code: -32602는 JSON-RPC가 예약한 "Invalid params" 표준 코드 — 어떤 구현이든 이 숫자는 같은 의미다. message도 표준 문구가 권장된다. 진짜 디버깅 정보는 data 필드에 들어가는데, 이 안쪽 구조는 다시 구현 자유다(MCP가 약속을 더할 수도, 안 정해두면 서버 마음대로).

JSON-RPC가 예약한 표준 에러 코드는 다섯 개로 짧다.

-32700  Parse error      — JSON 자체가 깨졌다
-32600  Invalid Request  — 봉투 모양이 틀렸다 (jsonrpc 필드 누락 등)
-32601  Method not found — method 이름이 등록 안 됨
-32602  Invalid params   — params가 메서드가 요구하는 모양 아님
-32603  Internal error   — 서버 내부 버그
-32099 ~ -32000          — 구현이 자유롭게 쓰는 Server error 범위

왜 중요한가: 에러 코드가 표준이라는 건 LLM 입장에서 분기 비용이 0이라는 뜻이다. -32602가 오면 "내가 인자를 잘못 보냈군"이라는 결론이 즉시 나온다 — 자연어 메시지를 정규식으로 파싱할 필요가 없다. JSON-RPC가 자연어 대신 숫자 코드를 못 박아둔 동기가 여기 있다.

사례 4: 알림(Notification) — 응답을 기대하지 않는 호출

요청에서 id를 빼면 그 메시지는 "알림(notification)"이 된다. 서버는 응답을 돌려주지 않는다. MCP에서는 초기화 완료 같은 일방향 신호에 주로 쓴다.

다이어그램 설명: 위 두 줄은 일반 호출 — id로 요청·응답이 짝지어진다. 아래 한 줄은 알림 — id가 없다는 점 하나로 메시지 의미가 바뀌고, 서버는 화살표를 되돌려 보내지 않는다. JSON-RPC는 id 유무 하나로 두 패턴을 구분한다.

// 클라이언트가 서버에게 "나 준비 끝" 알리는 알림
{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}
// id가 없다 → 서버는 응답 안 함

코드 설명: 서버가 알림 처리에 실패해도 클라이언트는 알 길이 없다 — 알림은 "받았으면 좋고 안 받았어도 안 망가지는" 종류의 신호에 한정해 써야 한다. MCP는 초기화 완료·progress 갱신·cancel 요청 같은 곳에서 이 패턴을 쓴다. notifications/라는 prefix 자체도 MCP 컨벤션이지 JSON-RPC가 강제한 건 아니다 — JSON-RPC는 그냥 "method 문자열"로만 본다.

핵심 통찰: 봉투를 일부러 좁게 둔 이유

JSON-RPC가 봉투 6단어로 끝나는 건 모자란 게 아니라 의도다. 봉투는 전송 무관·도메인 무관한 범용 짝맞춤만 책임지고(id로 요청·응답 페어링, method로 디스패치, error로 실패 신호), 내용물은 도메인이 알아서 정한다.

그래서 같은 JSON-RPC 위에 세 가지가 평화롭게 공존한다 — MCP(AI 도구 호출), Ethereum JSON-RPC API(블록체인 RPC), LSP(IDE-언어서버 통신). 봉투는 공유하고 메서드 이름·파라미터·결과 구조만 도메인별로 갈린다. 메서드 이름이 tools/call이든 eth_getBalance든 textDocument/completion이든, JSON-RPC 입장에서는 그냥 디스패치 키일 뿐이다.

MCP 서버 개발자 관점에서 책임이 어떻게 나뉘는지 정리하면 이렇다.

JSON-RPC 2.0이 정한 것 (이 글의 범위):
  jsonrpc · id · method · params · result · error
  표준 에러 코드 -32700 ~ -32603
  id 유무로 알림 구분

MCP가 정한 것 (다음 글의 범위):
  method 값들: tools/list, tools/call, resources/read, notifications/initialized, ...
  params 구조: { name, arguments }
  result 구조 (tools/list):  { tools: [{ name, description, inputSchema }] }
  result 구조 (tools/call):  { structuredContent, isError }
  inputSchema가 JSON Schema라는 점 (tools/list 응답에 직접 실림)

MCP 서버 개발자가 정하는 것:
  도구별 페이로드 (예: { exit_code, output } / { job_id, status, ... } / { logs, next_offset, eof })
  structuredContent에 객체 그대로 실려 들어감

코드 설명: inputSchema·structuredContent는 어디에 있는지 보자 — 둘 다 MCP가 정한 자리에 들어 있다. inputSchema는 tools/list의 result.tools[] 안, structuredContent는 tools/call의 result 안. JSON-RPC가 정의한 건 그 바깥의 result라는 슬롯이 있다는 사실까지다 — 그 안에 무엇이 들어가야 하는지는 도메인 명세(MCP)가 메서드별로 별도로 못 박는다.

왜 중요한가: JSON-RPC를 안다고 MCP를 다 아는 건 아니다. 반대도 마찬가지 — MCP만 외운 사람은 봉투 6단어가 어디서 왔는지 모른다. 둘은 따로 학습해야 하는 별개의 약속이고, 그게 분리되어 있다는 사실 자체가 두 표준이 각자 진화할 수 있는 이유다. MCP 명세가 다음 버전에서 structuredContent 형식을 더 다듬어도 JSON-RPC 봉투는 한 글자도 안 바뀐다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

서브에이전트 패키지를 직접 뜯어보다 — debug-pack 플러그인 해부

타이젠 개발자, 윤진 — Thu, 11 Jun 2026 21:00:09 +0900

GitHub MCP와 Playwright MCP는 도구 목록만 제공한다. 시스템 프롬프트와 트리거는 사용자가 별도로 만들어야 한다. 반면 debug-pack 플러그인은 다르다. 서브에이전트의 3가지 핵심 구성요소(시스템 프롬프트·도구 목록·트리거)가 모두 패키지 안에 들어 있다. 게다가 슬래시 커맨드(/debug-here)까지 묶여 있어, 설치하는 순간 Python 디버깅 전용 에이전트 생태계가 한 번에 세팅된다.

이 플러그인이 흥미로운 이유는 두 가지다. 첫째, 실제 서브에이전트 패키지가 어떻게 구성되는지 가장 완전한 형태로 보여주는 예시다. 둘째, Python 디버깅이라는 구체적인 문제를 풀기 위해 두 개의 MCP 서버(sequential-thinking, fetch)가 함께 포함되어 있어, 단순 역할 정의를 넘어 진짜 전문 도구를 갖춘 에이전트다.

다이어그램에서 주목할 것은 서브에이전트 박스(파란색)에 구성요소 ①과 ②가 함께 들어있다는 점이다. agents/python-debugger.md 파일의 본문이 ① 시스템 프롬프트가 되고, frontmatter의 tools 필드가 ② 도구 목록이 된다. 노란색 스킬 박스가 ③ 트리거를 담당한다. GitHub MCP나 Playwright MCP에서는 사용자가 직접 만들어야 했던 것들이 모두 패키지 안에 이미 들어 있다.

각 자산이 하는 일

python-debugger 서브에이전트는 이 패키지의 핵심이다. 시스템 프롬프트는 "오류 메시지와 스택 트레이스를 꼼꼼히 읽고, 가설을 단계별로 세우고 검증하며, 근본 원인을 고치는 가장 작은 변경만 제안한다"는 지시를 담는다. 모델은 추론 능력이 높은 sonnet으로 고정되어 있다.

sequential-thinking MCP 서버는 이 에이전트의 차별점이다. mcp__sequential-thinking__sequentialthinking이라는 도구를 제공하는데, 이 도구는 LLM이 "가설 → 검증 → 재고 → 재가설" 과정을 명시적인 단계로 기록하게 만든다. 내부적으로 추론하던 것을 도구 호출 로그로 외부화하는 것이다. 덕분에 "왜 이 결론에 도달했는지"를 추적할 수 있다.

fetch MCP 서버는 라이브러리 문서를 직접 조회하는 도구다. 에러가 특정 외부 라이브러리와 관련된 경우, 에이전트가 해당 라이브러리의 GitHub 이슈 목록이나 공식 문서를 직접 읽어서 이미 알려진 버그인지, 해결책이 있는지를 확인할 수 있다.

python-error-patterns 스킬은 자주 발생하는 Python 오류 패턴의 카탈로그다. ImportError, asyncio 관련 오류, pytest fixture 문제, mypy 타입 오류 등이 정리되어 있다. 에이전트가 오류를 처음 보는 게 아니라 이미 알고 있는 패턴과 대조하면서 판단하게 된다.

/debug-here 커맨드는 이 모든 것을 한 번에 트리거하는 원버튼이다. 오류가 발생한 상태에서 /debug-here를 입력하면, 현재 컨텍스트의 오류 정보를 python-debugger 서브에이전트에 즉시 위임한다.

설치 방법

debug-pack은 로컬 플러그인이므로 디렉토리 경로로 설치한다. MCP 서버 두 개는 모두 npx 패키지라 별도 설치 없이 첫 실행 시 자동으로 다운로드된다.

# 로컬 플러그인 설치
/plugin install ~/projects/debug-pack

# 설치 확인
# 대화창에서 /debug-here 커맨드가 나타나면 성공

# 사용 방법 1: 슬래시 커맨드
/debug-here
# → 현재 대화의 오류 정보를 python-debugger에게 즉시 위임

# 사용 방법 2: 자연어 트리거 (SKILL.md triggers)
# 사용자: "pytest tests/ 실행했는데 ImportError 났어"
# → python-error-patterns 스킬이 트리거되어 에이전트가 호출됨

# 사용 방법 3: 명시적 Agent 호출
# "python-debugger 에이전트한테 이 오류 분석 맡겨줘"

설치 후 파일 구조

debug-pack은 로컬 플러그인이라 GitHub MCP나 Playwright MCP와 설치 경로가 다르다. /plugin install ~/projects/debug-pack을 실행하면 다음 구조가 생성된다.

~/.claude/plugins/cache/debug-pack-local/debug-pack/0.1.0/
  .claude-plugin/
    plugin.json                              ← 플러그인 메타데이터
  .mcp.json                                  ← MCP 서버 2종 (sequential-thinking + fetch)
  README.md
  agents/
    python-debugger.md                       ← [구성요소 ①②] 시스템 프롬프트 + 도구 목록
  commands/
    debug-here.md                            ← 슬래시 커맨드 /debug-here
  skills/
    python-error-patterns/
      SKILL.md                               ← [구성요소 ③] 트리거 + 오류 패턴 카탈로그

GitHub MCP(파일 2개)나 Playwright MCP(파일 2개)와 비교하면 파일이 훨씬 많다. 각 파일이 역할을 나눠 맡고 있기 때문이다.

agents/python-debugger.md가 핵심이다. frontmatter의 tools 필드가 ② 도구 목록이고, model: sonnet으로 기본 Claude보다 추론 능력이 높은 모델을 고정한다. 본문 전체가 ① 시스템 프롬프트가 된다.

---
name: python-debugger
description: Use proactively when the user reports a Python error, stack trace,
             pytest failure, or "it broke after X". Root-causes the issue
             and proposes the smallest fix.
tools: Read, Edit, Bash, Grep, Glob,
       mcp__sequential-thinking__sequentialthinking,   ← 단계별 가설 검증 도구
       mcp__fetch__fetch                                ← 외부 문서 조회 도구
model: sonnet                                           ← 추론 능력이 높은 모델로 고정
---

You are a Python debugging specialist.
When invoked:
1. Read the error message or failing test output carefully.
2. Use mcp__sequential-thinking__sequentialthinking to lay out hypotheses step by step.
3. Verify each hypothesis with Read, Grep, or Bash before moving to the next.
4. Propose the smallest fix that addresses the root cause.

Output format: Root cause / Fix / Verification

skills/python-error-patterns/SKILL.md는 ③ 트리거와 오류 패턴 카탈로그가 함께 들어 있다. 트리거가 매칭되면 에이전트가 자동 호출되고, 카탈로그는 에이전트가 첫 번째 판단을 내릴 때 참조한다.

---
triggers:
  - Python 오류
  - 스택 트레이스
  - pytest 실패
  - 왜 안 되지
  - it broke after
---

## 오류 패턴 카탈로그

- ImportError / ModuleNotFoundError: 가상환경 불일치, 패키지 설치 누락
- asyncio RuntimeError: 이벤트 루프 중첩, sync 컨텍스트에서 await 호출
- pytest fixture: scope 불일치, autouse 충돌
- mypy 타입 오류: Optional 처리 누락, Any 타입 전파
- subprocess / File IO: 인코딩 불일치, 경로 오류
- GPU / CUDA: 드라이버 버전 불일치, 메모리 부족

.mcp.json에는 두 개의 로컬 서버가 정의되어 있다. 둘 다 GitHub MCP의 "type": "http"가 아닌 "command": "npx" 방식이다 — Playwright MCP와 같은 로컬 프로세스 실행이다.

// .mcp.json — 실제 파일 전체
{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  },
  "fetch": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-fetch"]
  }
}

commands/debug-here.md는 한 줄짜리 파일이다. 이 한 줄이 /debug-here 커맨드의 전부다.

Invoke @python-debugger to diagnose the failing test or error in the current directory.

세 플러그인의 파일 구조를 놓고 보면 차이가 선명하다. GitHub MCP와 Playwright MCP는 .mcp.json과 plugin.json 두 개뿐 — 도구(②)만 제공한다. debug-pack은 7개 파일로 구성요소 ①②③과 슬래시 커맨드, MCP 서버 2종까지 담았다. 파일 수가 역할의 완성도를 보여준다.

어떤 효과가 있나

debug-pack의 가장 큰 효과는 체계적인 가설 검증이다. 일반적으로 디버깅할 때는 "이게 문제인 것 같다 → 고쳐봄 → 아니면 저게 문제 → 고쳐봄"이라는 시행착오를 거친다. sequential-thinking 도구가 있으면 에이전트가 가설 A, B, C를 먼저 명시적으로 나열하고, 각각을 순서대로 검증한 뒤 근본 원인을 확정한다. 패닉 디버깅이 아니라 시스템적 분석이 된다.

두 번째 효과는 라이브러리 버그와 사용 오류의 구분이다. fetch 도구가 없으면 에이전트는 코드만 보고 판단해야 한다. 하지만 실제로는 외부 라이브러리의 알려진 버그인 경우가 많다. fetch로 라이브러리 GitHub 이슈를 직접 확인해서 "이것은 라이브러리 버전 2.1.3의 알려진 버그입니다. 2.1.4로 업그레이드하세요"라는 결론을 낼 수 있다.

세 번째 효과는 자산 재사용이다. debug-pack을 팀에 배포하면, 팀원 모두가 동일한 python-error-patterns 카탈로그와 동일한 디버깅 절차를 사용하게 된다. 시니어 개발자가 알고 있는 "흔한 오류 패턴"이 패키지 안에 들어 있어서, 주니어 개발자도 같은 수준의 첫 번째 판단을 받게 된다.

GitHub MCP, Playwright MCP, debug-pack 세 가지를 놓고 보면 패턴이 보인다. GitHub와 Playwright는 도구만 제공하고 "어떤 전문가로 만들지"는 사용자 결정이다. debug-pack은 "Python 디버깅 전문가"라는 역할까지 패키지 안에 완성되어 있다. 플러그인을 만들 때 이 중 어느 형태를 선택할지는 목적에 달려 있다. 범용 도구를 팀이 자유롭게 활용하게 하려면 도구만, 특정 전문 역할을 표준화하려면 완전한 패키지로 만드는 것이 맞다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

Claude에 브라우저 눈과 손을 달다 — Playwright MCP 플러그인

타이젠 개발자, 윤진 — Wed, 10 Jun 2026 23:00:42 +0900

Claude Code는 기본적으로 파일과 터미널만 다룬다. 브라우저를 직접 보거나 조작할 수 없다. 그래서 "내가 배포한 UI가 제대로 동작하는지 확인해줘"라고 하면, Claude가 할 수 있는 것은 코드를 읽어서 추론하는 것뿐이다. 실제 브라우저를 열어서 확인하는 게 아니다.

Playwright MCP 플러그인은 이 제약을 제거한다. 설치하면 Claude Code가 브라우저를 직접 열고, 버튼을 클릭하고, 텍스트를 입력하고, 화면을 캡처할 수 있게 된다. "로그인 페이지에서 틀린 비밀번호를 입력했을 때 에러 메시지가 제대로 나오는지 확인해줘"라고 하면, Claude가 실제 브라우저에서 그 동작을 재현하고 결과를 보고한다.

그림에서 핵심은 "browser_screenshot → Claude가 이미지를 분석" 단계다. Claude는 텍스트뿐만 아니라 이미지도 이해할 수 있다. Playwright MCP가 화면을 캡처해서 Claude에게 돌려주면, Claude는 그 이미지를 분석해서 "에러 메시지가 빨간색 텍스트로 나왔고, 위치는 로그인 버튼 아래입니다"처럼 시각적 판단을 내린다. 화면을 직접 보고 판단하는 것이다.

3가지 구성요소와의 관계

GitHub MCP와 마찬가지로 Playwright MCP 플러그인도 서브에이전트의 3가지 구성요소 중 ② 도구 목록만 제공한다. 플러그인 자체에는 시스템 프롬프트도 트리거도 없다. 브라우저를 조작하는 도구들이 Claude Code에 추가되는 것뿐이다.

직접 E2E 테스트 에이전트를 만들어 보자. Playwright MCP가 제공하는 도구를 사용하는 SKILL.md다.

# ~/.claude/skills/e2e-tester/SKILL.md
---
name: e2e-tester
description: 브라우저로 직접 E2E 테스트를 수행하는 에이전트
triggers:
  - E2E 테스트
  - 브라우저 테스트
  - UI 확인해줘
  - 화면 보여줘
allowed-tools:
  - mcp__playwright__browser_navigate
  - mcp__playwright__browser_click
  - mcp__playwright__browser_type
  - mcp__playwright__browser_screenshot
  - mcp__playwright__browser_wait_for_element
  - mcp__playwright__browser_evaluate
---

당신은 QA 엔지니어로, 실제 브라우저에서 기능을 검증합니다.

## 테스트 절차

1. browser_navigate로 테스트할 URL로 이동한다.
2. browser_screenshot으로 초기 상태를 캡처해 확인한다.
3. 지시받은 동작을 browser_click, browser_type으로 실행한다.
4. browser_wait_for_element로 결과가 나타날 때까지 기다린다.
5. browser_screenshot으로 최종 상태를 캡처해 분석한다.

## 보고 형식

- 테스트 항목: 무엇을 확인했는지
- 결과: PASS / FAIL
- 근거: 화면에서 확인한 내용 (캡처 포함)

설치 방법

GitHub MCP와 달리 Playwright MCP는 인증이 필요 없다. 로컬에서 브라우저를 제어하는 방식이라 토큰이 없어도 된다. npx로 자동 실행되므로 Node.js만 설치되어 있으면 된다.

# 1단: 플러그인 설치 (npx 자동 처리)
/plugin install playwright@claude-plugins-official

# 처음 실행 시 Playwright 브라우저 다운로드가 자동으로 진행된다
# (Chromium ~200MB)

# 2단: 위 SKILL.md 파일 저장
mkdir -p ~/.claude/skills/e2e-tester
# (SKILL.md 내용 저장)

# 사용 예시
# 사용자: "localhost:3000 로그인 화면 E2E 테스트해줘"
# → e2e-tester 에이전트가 호출되어 실제 브라우저를 열고 테스트한다

한 가지 주의할 점이 있다. Playwright MCP는 헤드리스(headless) 모드로 기본 동작한다 — 브라우저 창이 화면에 나타나지 않고 백그라운드에서 실행된다. 디버깅 목적으로 브라우저를 눈으로 보고 싶다면 플러그인 설정에서 headless를 끌 수 있다.

설치 후 파일 구조

설치 후 파일 구조는 GitHub MCP와 동일하게 두 개뿐이다. 하지만 .mcp.json의 내용이 완전히 다르다 — HTTP 원격 접속이 아니라 로컬 프로세스 실행 방식이다.

~/.claude/plugins/cache/claude-plugins-official/playwright/unknown/
  .claude-plugin/
    plugin.json     ← 플러그인 메타데이터 (이름·설명·작성자: Microsoft)
  .mcp.json         ← 로컬 MCP 서버 실행 명령

// .mcp.json — 실제 파일 전체
{
  "playwright": {
    "command": "npx",                    // 로컬 프로세스 방식
    "args": ["@playwright/mcp@latest"]   // 최신 버전을 그때그때 다운로드해 실행
  }
}

GitHub MCP의 "type": "http"와 달리 여기는 "command": "npx"다. Claude Code가 이 플러그인을 활성화하면 백그라운드에서 npx @playwright/mcp@latest를 실행해 로컬 MCP 서버 프로세스를 띄운다. 이 프로세스가 Chromium 브라우저를 제어하고, Claude Code가 그 프로세스와 JSON-RPC로 통신한다. 인증이 따로 없는 이유는 브라우저가 로컬 머신에서만 동작하기 때문이다.

plugin.json의 작성자 필드를 보면 GitHub MCP와 차이가 있다.

// .claude-plugin/plugin.json
{
  "name": "playwright",
  "description": "Browser automation and end-to-end testing MCP server by Microsoft.
    Enables Claude to interact with web pages, take screenshots, fill forms,
    click elements, and perform automated browser testing workflows.",
  "author": { "name": "Microsoft" }   // Microsoft 제작·배포
}

이 두 파일 어디에도 시스템 프롬프트(①)와 트리거(③)가 없다. GitHub MCP와 동일하게 도구 목록(②)만 제공하는 플러그인이다. 앞서 작성한 e2e-tester/SKILL.md가 없으면 Playwright 도구들은 사용자가 직접 "browser_navigate 도구로 localhost:3000 열어줘"라고 요청해야만 동작한다. SKILL.md가 시스템 프롬프트와 트리거를 붙여줘야 비로소 "UI 확인해줘" 한 마디로 자동화가 동작한다.

어떤 효과가 있나

Playwright MCP가 가장 효과적인 순간은 코드를 배포한 직후다. 코드를 고치고 나서 "정말 제대로 동작하는지" 확인하는 과정이 자동화된다. 기존에는 개발자가 직접 브라우저를 열고 클릭해가며 확인해야 했지만, 이제 Claude에게 "방금 고친 비밀번호 재설정 흐름 테스트해줘"라고 하면 된다.

두 번째 효과는 회귀 테스트 자동화다. "매번 PR이 올라올 때마다 로그인 → 메인 페이지 이동 → 데이터 로드 순서로 기본 동작을 확인한다"는 루틴을 만들어 두면, Claude가 자동으로 브라우저를 열어 확인하고 결과를 보고한다. Playwright 코드를 직접 짜지 않아도 된다.

세 번째 효과는 덜 알려져 있지만 중요하다. Claude가 이미지를 분석한다는 것이다. 단순히 클릭 좌표를 계산하는 도구가 아니다. "이 버튼의 색상이 디자인 가이드(파란색 #2563EB)와 일치하는지 확인해줘"라고 하면, Claude가 스크린샷을 찍고 화면에서 실제 색상을 확인한 뒤 판단을 내린다. 시각적 UI 검증이 자동화되는 것이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

Claude에 GitHub 전체를 연결하다 — GitHub MCP 플러그인 실전 가이드

타이젠 개발자, 윤진 — Wed, 10 Jun 2026 22:00:42 +0900

코드를 짜다가 PR을 확인해야 할 때마다 브라우저로 넘어가는 흐름이 끊기는 느낌이 있다. GitHub 탭을 열고, 필터를 걸고, 코멘트를 달고, 다시 에디터로 돌아오는 과정이다. GitHub MCP 플러그인을 설치하면 이 흐름이 사라진다. Claude Code 대화창 안에서 "내가 리뷰어로 지정된 PR 목록 보여줘"라고 하면 즉시 목록이 나오고, "이 PR에 LGTM 코멘트 달아줘"라고 하면 GitHub에 바로 반영된다.

이 플러그인이 흥미로운 이유는 HTTP 방식의 MCP 서버라는 점이다. 앞서 설명한 서브에이전트의 3가지 핵심 구성요소 중 플러그인이 제공하는 것은 도구 목록(②)만이다. 시스템 프롬프트(①)와 트리거(③)는 사용자가 별도로 정의한다. GitHub API와 통신하는 MCP 서버가 GitHub Copilot 인프라에서 운영되고, 그 서버를 Claude Code가 HTTP로 호출하는 구조다. 로컬에 별도 프로세스가 뜨지 않는다.

핵심은 아키텍처 그림 가운데 있는 "GitHub MCP 서버"다. 이 서버는 로컬 컴퓨터에 뜨는 프로세스가 아니라, api.githubcopilot.com/mcp/라는 원격 서버다. Claude Code가 HTTP로 이 서버를 호출하고, 서버가 GitHub.com API를 대신 호출해 결과를 돌려준다. npx로 로컬 프로세스를 띄우는 Playwright나 context7과 다른 방식이고, 덕분에 Node.js 설치 없이도 동작한다.

3가지 구성요소와의 관계

GitHub MCP 플러그인은 서브에이전트의 3가지 핵심 구성요소 중 ② 도구 목록만 제공한다. PR을 읽고 코멘트를 다는 도구들이 Claude Code에 추가되는 것이다. ① 시스템 프롬프트("PR 리뷰어로서 보안을 중점적으로 확인한다")와 ③ 트리거("리뷰해줘")는 사용자가 별도로 SKILL.md를 만들어 정의해야 한다.

직접 SKILL.md를 만들어 붙여 보자. GitHub MCP가 제공하는 도구를 활용하는 PR 리뷰어 에이전트다.

# ~/.claude/skills/pr-reviewer/SKILL.md
---
name: pr-reviewer
description: GitHub PR을 자동으로 리뷰하는 에이전트
triggers:
  - PR 리뷰
  - pull request 확인
  - PR 머지해도 돼
allowed-tools:
  - mcp__plugin_github_github__list_pull_requests
  - mcp__plugin_github_github__pull_request_read
  - mcp__plugin_github_github__pull_request_review_write
  - mcp__plugin_github_github__add_issue_comment
  - mcp__plugin_github_github__merge_pull_request
  - mcp__plugin_github_github__request_copilot_review
---

당신은 시니어 소프트웨어 엔지니어로, 팀의 PR 리뷰를 담당합니다.

## 리뷰 절차

1. pull_request_read로 변경 내용을 파악한다.
2. 보안 → 로직 → 스타일 순으로 이슈를 분류한다.
3. pull_request_review_write로 구체적 코멘트를 단다.
4. 머지 가능 여부를 판단해 결론을 내린다.

## 리뷰 기준

- SQL Injection, XSS 등 보안 패턴을 우선 확인한다.
- 테스트가 없는 변경에는 반드시 지적한다.
- 좋은 코드도 반드시 언급해 균형을 유지한다.

설치 방법

플러그인 설치는 한 줄이다. 그 다음 GitHub Personal Access Token(개인 계정 인증 토큰)을 환경변수로 설정해야 한다. PAT는 GitHub → Settings → Developer settings → Personal access tokens에서 생성한다. 필요한 권한은 repo, read:org, read:user다.

# 1단: 플러그인 설치
/plugin install github@claude-plugins-official

# 2단: GitHub PAT 환경변수 설정 (~/.bashrc 또는 ~/.zshrc에 추가)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# 3단: 위에서 만든 PR 리뷰어 스킬 설치
mkdir -p ~/.claude/skills/pr-reviewer
# (위 SKILL.md 내용을 저장)

# 이제 대화창에서
# 사용자: "my-org/my-repo PR 리뷰해줘"
# → pr-reviewer 스킬이 호출되고 GitHub MCP 도구로 실제 PR을 분석한다

설치 후 파일 구조

설치가 완료되면 Claude Code의 플러그인 캐시 디렉토리에 파일이 생긴다. GitHub MCP 플러그인은 구조가 단순하다 — 파일이 단 두 개다.

~/.claude/plugins/cache/claude-plugins-official/github/unknown/
  .claude-plugin/
    plugin.json     ← 플러그인 메타데이터 (이름·설명·작성자)
  .mcp.json         ← MCP 서버 접속 정보 (핵심 파일)

파일이 두 개뿐이라는 것 자체가 이 플러그인의 특성을 보여준다. 로컬에 설치되는 코드가 없고, 접속 정보만 기록한다. 핵심은 .mcp.json이다.

// .mcp.json — 실제 파일 전체
{
  "github": {
    "type": "http",                               // HTTP 방식 (로컬 프로세스 없음)
    "url": "https://api.githubcopilot.com/mcp/",  // GitHub 운영 원격 서버
    "headers": {
      "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
                                                  // 환경변수에서 PAT를 런타임에 주입
    }
  }
}

이 파일에서 주목할 것이 세 가지 있다. 첫째, "type": "http"다. Playwright나 sequential-thinking의 "command": "npx"와 다르게 HTTP 연결 타입이다 — 원격 서버에 접속하는 방식이라는 뜻이다. 둘째, URL이 githubcopilot.com이다. Anthropic이 아닌 GitHub가 직접 운영하는 서버다. 셋째, ${GITHUB_PERSONAL_ACCESS_TOKEN}은 런타임에 환경변수 값을 읽어서 Bearer 토큰으로 사용한다. 이 환경변수가 설정되지 않으면 모든 도구 호출이 401 인증 오류로 실패한다.

plugin.json은 메타데이터만 담는다.

// .claude-plugin/plugin.json
{
  "name": "github",
  "description": "Official GitHub MCP server for repository management. Create issues,
    manage pull requests, review code, search repositories, and interact with GitHub's
    full API directly from Claude Code.",
  "author": { "name": "GitHub" }
}

시스템 프롬프트(①)와 트리거(③)가 이 파일들 어디에도 없다는 점을 확인할 수 있다. 이 플러그인은 도구 목록(②)만 제공하고, 나머지는 사용자가 SKILL.md로 채워야 한다.

어떤 효과가 있나

GitHub MCP 플러그인의 효과는 세 가지로 정리된다. 첫째, 컨텍스트 전환이 사라진다. 코드를 짜다가 PR을 확인할 때 브라우저로 넘어갈 필요가 없다. Claude Code 대화창 안에서 모든 GitHub 작업이 완결된다.

둘째, 복합 작업을 자연어 한 마디로 실행한다. "내가 reviewer인 PR 중 7일 이상 지난 것 목록 보여주고 각각 머지 가능 여부 판단해줘"는 수십 번의 클릭이 필요한 작업이지만, Claude에게 한 문장으로 요청하면 된다. Claude가 search_pull_requests, pull_request_read, list_commits를 차례로 호출해 판단 결과를 낸다.

셋째, 보안 스캔과 코드 리뷰를 함께 자동화한다. PR이 열릴 때마다 search_code로 위험 패턴을 찾고 run_secret_scanning으로 비밀 토큰 노출을 확인하는 루틴을 만들어 두면, 별도 CI 도구 없이 Claude가 매번 자동으로 실행한다.

주의할 점은 하나다. merge_pull_request, pull_request_review_write 같은 쓰기 작업은 실행 전 Claude Code가 사용자에게 확인을 요청한다. 직접 GitHub에 영향을 주는 작업이므로 Claude Code의 기본 동작이 이를 사용자 확인 대상으로 분류하기 때문이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.

Claude Code에서 나만의 AI 전문가 만들기 — 서브에이전트 제작 가이드

타이젠 개발자, 윤진 — Wed, 10 Jun 2026 21:00:41 +0900

Claude Code를 쓰다 보면 이런 순간이 온다. "이 작업만큼은 전문가가 봐줬으면." 코드를 짜다가 보안 취약점도 함께 검사하고 싶을 때, 대용량 로그 파일을 분석하느라 정작 하던 작업의 맥락을 잃어버릴 때, PR마다 똑같은 체크리스트를 반복할 때다.

Claude Code에는 이 문제를 해결하는 서브에이전트(Sub-agent)라는 개념이 있다. 메인 Claude에게 특정 작업을 "이건 전문가한테 맡겨"라고 위임할 수 있는, 목적에 특화된 AI 조수다. 마치 회사에서 법무팀·디자인팀·보안팀이 따로 있듯이, Claude Code에도 역할별 전문가를 만들어 붙일 수 있다.

더 좋은 점은 이 전문가를 직접 만들 수 있다는 것이다. 텍스트 파일 하나로 시작할 수 있고, 필요하면 새 도구까지 추가해 진짜 전문 시스템으로 키울 수 있다. 이 글은 그 방법을 처음부터 끝까지 설명한다.

언제 서브에이전트가 필요한가

서브에이전트가 빛을 발하는 상황은 크게 네 가지다. 하나만 해당해도 도입을 고려할 만하고, 여러 개가 겹칠수록 효과가 배가된다.

네 상황이 겹칠수록 서브에이전트의 효과가 커진다. 예를 들어 "보안 감사"는 ① 전문 지식이 필요하면서 ② 분석 결과가 방대하고, ④ PR마다 반복되는 경우가 많다. 세 가지가 겹치면 서브에이전트 없이는 버거운 작업이 된다.

핵심 구성요소 3가지

서브에이전트는 레고 블록처럼 세 가지 파츠를 맞추면 완성된다. 이 세 가지 중 하나라도 빠지면 제대로 동작하지 않는다.

세 구성요소의 역할을 비유로 이해하면 쉽다. 시스템 프롬프트는 직원 채용 공고의 "직무 기술서"다. 도구 목록은 그 직원이 회사 시스템에서 접근할 수 있는 "권한 범위"다. SKILL.md는 "이 사람을 언제 부를지"를 정하는 호출 규칙이다. 세 가지가 갖춰져야 제대로 된 전문가 에이전트가 탄생한다.

방법 1 — SKILL.md 파일 하나로 3가지 구성요소 담기

가장 빠른 방법은 SKILL.md 파일 하나를 작성하는 것이다. 이 파일 하나가 앞서 설명한 3가지 핵심 구성요소를 전부 담는다. 코드 한 줄도 필요 없다.

파일은 크게 두 영역으로 나뉜다. ---으로 감싼 frontmatter에 ② 도구 목록(allowed-tools)과 ③ 트리거(triggers)를 적고, 그 아래 본문에 ① 시스템 프롬프트를 적는다. 파일 하나로 끝이다.

# 파일 위치: ~/.claude/skills/code-reviewer/SKILL.md

# ━━━ frontmatter 시작 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
---
name: code-reviewer
description: |
  Python 코드 품질을 검사하는 시니어 리뷰어.
  코드 리뷰, PR 리뷰, review code를 언급하면 반드시 이 스킬을 사용한다.
version: 1.0.0

# [구성요소 ②: 도구 목록]
# 에이전트가 쓸 수 있는 도구를 제한한다.
# 리뷰어는 읽고 검색만 하면 되므로 Edit·Write 권한은 주지 않는다.
allowed-tools:
  - Read      # 파일 읽기
  - Grep      # 코드 내 패턴 검색
  - Glob      # 파일 목록 조회
  - Bash      # 테스트·린트 실행 확인

# [구성요소 ③: 트리거]
# 이 단어가 대화에 나오면 이 에이전트를 자동으로 호출한다.
triggers:
  - 코드 리뷰
  - PR 리뷰
  - review code
  - 리뷰해줘
---
# ━━━ frontmatter 끝 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

# [구성요소 ①: 시스템 프롬프트]
# 여기서부터 아래 전체가 에이전트에게 주는 지시문이다.

당신은 Python 전문가로, 10년 경력의 시니어 엔지니어입니다.
코드를 볼 때 다음 순서로 검토합니다.

## 리뷰 순서

1. 변경된 파일 목록부터 확인한다.
2. 핵심 로직을 파악한다 (5분 이내).
3. 이슈를 버그 → 보안 → 성능 → 스타일 순으로 분류한다.
4. 각 이슈에 구체적인 수정 제안을 작성한다.

## 리뷰 원칙

- 문제를 지적할 때 반드시 코드의 정확한 위치(파일명:줄번호)를 명시한다.
- 좋은 부분도 반드시 언급해 균형 잡힌 피드백을 제공한다.
- "이 코드는 문제가 있습니다"가 아니라 "38번 줄의 user_input이 SQL에
  직접 들어가고 있어 SQL Injection 위험이 있습니다. f-string 대신 파라미터
  바인딩을 사용하세요"처럼 구체적으로 말한다.

파일 구조를 보면 3가지 구성요소가 어디에 들어가는지 분명하다. frontmatter의 allowed-tools가 ② 도구 목록이고, triggers가 ③ 트리거다. 그리고 frontmatter 아래 본문 전체가 ① 시스템 프롬프트가 된다. 파일 하나가 세 역할을 동시에 한다.

설치도 간단하다. 파일을 올바른 경로에 두면 Claude Code가 자동으로 인식한다.

# 스킬 디렉토리 만들고 파일 저장
mkdir -p ~/.claude/skills/code-reviewer
# 위 내용을 ~/.claude/skills/code-reviewer/SKILL.md 에 저장

# 대화창에서 바로 쓸 수 있다
# 사용자: "auth.py 코드 리뷰해줘"
# → "리뷰해줘"가 triggers에 있으므로 code-reviewer가 자동 호출된다
# → allowed-tools에 따라 Read·Grep·Glob·Bash만 사용한다
# → 본문 지시(시스템 프롬프트)대로 버그→보안→성능 순으로 분석한다

방법 2 — Plugin으로 구성요소를 분리하고 새 도구 추가하기

SKILL.md는 세 구성요소를 파일 하나에 몰아넣는다. 빠르지만 에이전트가 복잡해질수록 관리가 어려워지고, 가장 중요한 제약이 하나 있다. Claude Code에 이미 내장된 도구만 쓸 수 있다는 것이다. 외부 API를 호출하는 도구나 특수한 서비스와 연결하는 도구를 추가하고 싶다면 플러그인(Plugin) 방식으로 가야 한다.

여기서 두 개념을 구분해 두자. MCP(Model Context Protocol)는 AI 모델이 외부 도구를 표준 방식으로 호출하는 프로토콜이다 — USB-C처럼 규격이 통일되어 있으면 어떤 도구든 꽂을 수 있는 것과 같다. 플러그인은 그 MCP 서버를 비롯해 에이전트 정의·스킬·명령어를 한 묶음으로 패키징한 패키지다. MCP는 도구를 추가하는 방식이고, Plugin은 그것을 담는 그릇이다.

Plugin 방식에서는 3가지 구성요소가 각각 별도 파일로 분리된다.

my-project/                ← 프로젝트 루트 (이름은 자유)
  plugins/
    my-debugger/           ← 플러그인 ID (설치·공유의 기준이 되는 이름)
      .mcp.json            ← [선택] 새 도구를 제공하는 MCP 서버 목록
      agents/
        debugger.md        ← [구성요소 ①②] 시스템 프롬프트 + 도구 목록
      skills/
        SKILL.md           ← [구성요소 ③] 트리거 조건

SKILL.md에서 한 파일에 몰려 있던 세 구성요소가 agents/와 skills/로 나뉜다. 그리고 .mcp.json이 선택적으로 추가되어 새 도구를 Claude Code에 등록한다.

파이썬 디버깅 전문 에이전트를 예시로 만들어 보자. 이 에이전트는 sequential-thinking(LLM이 가설을 단계별로 명시적으로 세우고 검증하는 MCP 도구)이라는 새 도구를 추가해 사용한다.

1단계 — .mcp.json: 새 도구를 제공하는 MCP 서버 등록 (구성요소 ②의 확장)

// plugins/my-debugger/.mcp.json
// Claude Code에 없는 새 도구를 MCP 서버로 추가한다
{
  "sequential-thinking": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
  }
}

2단계 — agents/debugger.md: 시스템 프롬프트(본문) + 도구 목록(frontmatter)

---
name: python-debugger
description: Python 오류와 스택 트레이스를 보고할 때 자동 호출된다.

# [구성요소 ②: 도구 목록]
# .mcp.json에 등록한 MCP 도구도 여기서 허용할 수 있다
tools: Read, Edit, Bash, Grep, mcp__sequential-thinking__sequentialthinking
model: sonnet
---

# [구성요소 ①: 시스템 프롬프트]
당신은 Python 디버깅 전문가입니다.

오류를 받으면 다음 순서로 진행합니다.

1. 오류 메시지와 스택 트레이스를 꼼꼼히 읽는다.
2. sequential-thinking 도구로 가설을 단계별로 세우고 검증한다.
3. 스택 트레이스에서 파일과 줄 번호를 찾아 해당 코드를 읽는다.
4. 근본 원인을 고치는 가장 작은 변경만 제안한다.

출력 형식: 근본 원인 / 수정 내용 / 검증 명령

3단계 — skills/SKILL.md: 트리거 조건 (구성요소 ③)

---
name: python-debugger
description: Python 디버거 스킬

# [구성요소 ③: 트리거]
triggers:
  - Python 오류
  - 스택 트레이스
  - pytest 실패
  - 왜 안 되지
---

방법 1과 방법 2를 비교하면 이렇다. SKILL.md 방식은 파일 하나가 세 구성요소를 전부 담고, Plugin 방식은 구성요소를 파일별로 분리해 관리하면서 MCP로 새 도구를 추가한다. 에이전트가 단순하면 SKILL.md로 시작하고, 새 도구가 필요하거나 여러 사람에게 배포하려면 Plugin으로 키우면 된다.

배포: 만든 에이전트를 패키징하고 팀에 전달하기

에이전트를 팀과 공유하려면 먼저 배포용 패키지를 만들어야 한다. SKILL.md 방식은 폴더를 통째로 Git에 올리고, Plugin 방식은 npm 패키지로 묶는다.

SKILL.md 방식 배포 — Git 저장소로 공유

스킬 폴더를 Git 저장소에 올리면 팀원이 clone해서 가져다 쓸 수 있다. 버전 관리가 되므로 "이 에이전트가 언제 어떻게 바뀌었는지"도 추적할 수 있다.

# 1단: 공유할 스킬을 Git 저장소에 올린다
mkdir claude-skills
cp -r ~/.claude/skills/code-reviewer claude-skills/
cd claude-skills
git init && git add . && git commit -m "add code-reviewer skill"
git push origin main

# 2단: 팀원이 받아서 설치한다
git clone https://github.com/my-team/claude-skills.git
cp -r claude-skills/code-reviewer ~/.claude/skills/
# Claude Code 재시작 없이 바로 인식된다

Plugin 방식 배포 — npm 패키지로 배포

Plugin을 npm으로 배포하면 /plugin install 명령 한 번으로 설치할 수 있다. 먼저 프로젝트 루트에 package.json을 추가해 Claude Code가 이것을 설치 가능한 패키지로 인식하게 한다.

// my-project/package.json
{
  "name": "@my-team/claude-debugger",
  "version": "1.0.0",
  "description": "Python 디버깅 전문 에이전트",
  "keywords": ["claude-code-plugin"],
  "main": "plugins/my-debugger"
}

# npm에 배포
npm publish --access public

# 팀원이 설치하는 방법 — 한 명령으로 끝난다
/plugin install @my-team/claude-debugger

# 배포 전 로컬 테스트는 경로로 바로 설치
/plugin install ~/my-project

만들고 나면 어떻게 달라지나

서브에이전트를 도입하고 나면 작업 방식이 달라진다. 메인 Claude가 "작업 감독"이 되고, 전문 에이전트들이 "실무자"가 된다. 메인이 PR을 받으면 코드 리뷰어, 보안 감사자, 테스트 실행자에게 동시에 맡기고, 결과가 돌아오면 취합해서 사용자에게 보고한다.

이 구조가 가장 빛나는 순간은 병렬 실행이다. 코드 리뷰(3분)와 보안 감사(5분)를 순서대로 하면 8분이 걸리지만, 동시에 실행하면 5분에 끝난다. 에이전트 수가 많아질수록 이 효과는 커진다.

시작은 간단하다. 오늘 가장 자주 반복하는 작업 하나를 골라 SKILL.md 파일을 만들어 보자. "이 작업을 전문가에게 시키면 어떻게 하도록 지시할까"를 텍스트로 쓰는 것이 전부다. 그것이 서브에이전트의 첫 걸음이다.

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.