본문으로 건너뛰기

프로토콜 era

MCP의 2026-07-28 버전 업데이트로 인해 프로토콜에 상당한 변화가 있었습니다. 따라서 Inspector는 프로토콜 era(레거시 또는 현대, 즉 해당 업데이트 이전 또는 그 시점의 상태)를 트랜스포트와는 무관한, 서버별로 설정되는 일등급 설정으로 간주합니다. 동일한 HTTP URL이라도 레거시 서버로도, 현대 서버로도 검사될 수 있습니다. 현재 적용 중인 era에 따라 여러 탭에서 표시되는 UI와 트래픽이 상당히 다르게 나타납니다.

Protocol Era 설정​

각 서버는 protocolEra 형태로 legacy, auto, 또는 modern 중 하나를 가지고 있습니다. 웹 클라이언트에서는 Server Settings에 저장되며, 카탈로그나 설정 파일에서는 protocolEra 필드로 표시되고, CLI 및 TUI에서도 동일한 파일에서 해당 값이 가져옵니다.

Era연결 시 Inspector가 수행하는 동작
legacy기본값입니다. 일반적인 initialize 방식을 사용하며, 어떠한 탐색도 수행하지 않습니다.
auto먼저 server/discover를 탐색한 후, 비현대적인 결과가 나올 경우 initialize 방식으로 전환합니다.
modern정확히 2026-07-28를 고정합니다. 별도의 대체 방식이 없어 비현대적인 서버의 경우 명확하게 오류가 발생합니다.

세 가지 클라이언트 모두에서 에라 선택 기능은 동일한 방식으로 작동합니다.

연결이 완료되면 협상된 에라 정보는 연결 헤더와 Connection Info에 표시됩니다. 최신 형태의 연결에서는 server/discover을 통해 capabilities( extensions를 포함함), instructions, 그리고 supportedVersions 목록도 제공됩니다. 서버의 이름과 버전은 결과 _meta 내의 io.modelcontextprotocol/serverInfo 항목에 포함되어 전달됩니다.

서버 설정: 세 가지 옵션이 모두 제공되는 Protocol Era 선택기입니다.

각 시대를 로컬에서 재현하기​

아래의 각 섹션은 Inspector 리포지토리에 포함된 컴포저블 테스트 서버 중 하나에 해당하는 JSON 설정 파일을 가리키는 Reproduce with ... 링크로 마무리됩니다. 먼저 해당 리포지토리를 클론하여 테스트 서버를 빌드한 다음, 섹션 제목에 명시된 설정 파일을 Inspector가 참조하도록 설정해야 합니다.

git clone https://github.com/modelcontextprotocol/inspector
cd inspector && npm install && npm run build
cd clients/web && npm run test-servers:build

로깅​

로깅은 세션 범위로 처리됩니다. 클라이언트는 한 번 logging/setLevel을 전송하고, 서버는 해당 세션의 남은 기간 동안 그 수준 이상에서 notifications/message을 출력합니다.

Logs 탭에는 Set Active Level 선택기와 Set 버튼이 표시됩니다. 원하는 로그 수준을 선택한 후 Set을 클릭하면 이후 발생하는 서버 로그들이 해당 패널에 실시간으로 표시됩니다.

test-servers/configs/logging-legacy-http.json를 사용하여 재현하기.

구버전 방식: Logs 탭에는 세션 범위 내에서 활성화 수준을 설정하는 제어 기능이 제공되며, send_notification을 호출한 후에 로그가 도착합니다.
현대적인 방식: 동일한 탭에서 요청별 로그 수준 제어 기능이 제공됩니다. 모든 외부 요청에 해당 수준이 표시되며, 로그는 해당 요청의 스트림에 포함됩니다.

리소스 구독​

리소스의 Subscribe 버튼을 클릭하면 resources/subscribe이 전송됩니다. 구독 목록에는 스트림 관련 정보가 표시되지 않은 URI가 나열됩니다. 리소스에 변경 사항이 생기면 서버는 notifications/resources/updated을 전송하고, 구독된 항목의 마지막 업데이트 시간이 기록됩니다.

test-servers/configs/subscriptions-legacy-http.json를 사용하여 해당 동작을 직접 확인해 볼 수 있으며, 이 도구는 update_resource도 제공하여 사용자가 직접 알림의 전송 및 수신 과정을 테스트할 수 있도록 합니다.

현대적인 구독 방식의 경우, 구독 섹션에는 레거시 구독에는 필요 없는 LISTENING stream-status 배지가 표시됩니다.

작업​

프로토콜의 버전이 변경될 때마다 작업 관련 사항들이 가장 많이 변화하며, 여기에는 _Inspector UI 탭의 표시 여부_도 포함됩니다.

서버가 capabilities.tasks를 공지할 경우 작업 탭이 나타납니다. 작업으로 실행 기능이 활성화된 도구를 실행하면 tasks/list에 의해 데이터가 채워지고 tasks/get를 통해 정보가 수집되어 해당 탭에 표시됩니다. 완료된 작업 결과는 **블로킹 tasks/result**를 통해 가져오며, 취소 버튼을 누르면 tasks/cancel이 전송됩니다.

test-servers/configs/tasks-legacy-http.json을 사용하여 동일한 상황을 재현해 보십시오.

Legacy: Tasks 탭은 tasks/list에서 데이터를 가져오며, 페이로드는 블로킹되는 tasks/result를 통해 가져옵니다.
Modern 방식에서는 클라이언트가 이미 보유하고 있는 핸들에 대해 tasks/get을 폴링하여 처리하며, 완료된 작업은 그 결과를 내장합니다. 전체 작업 객체의 resultType이 complete인 점에 유의해 주십시오.

다라운드 도구 결과(MRTR)​

현대적인 환경에서는 도구가 최종 결과 대신 input_required를 반환할 수 있으며, 여기에는 사용자 입력 요청, 샘플링 요청, 또는 roots/list 요청이 포함될 수 있습니다. 클라이언트는 이러한 내장된 요청에 응답한 후, 호출이 complete에 도달할 때까지 새로운 JSON-RPC 식별자를 사용하여 tools/call를 반복적으로 시도합니다.

인스펙터는 MRTR을 수동으로 실행하므로, 각 반복 단계에서는 응답을 기다리는 동안 input_required으로 표시된 pending-request modal에 일시 중단되어 사용자가 답변할 수 있도록 합니다. 프로토콜 뷰는 서로 관련이 없는 여러 호출이 아닌 전체 교환 내용을 하나의 MRTR 대화로 그룹화합니다.

test-servers/configs/mrtr-showcase-http.json는 하나의 최신 서버 내에 모든 형태의 기능을 통합합니다.

도구해당 도구가 수행하는 작업
mrtr_confirm단일 번의 사용자 입력 요청 라운드입니다.
mrtr_two_steprequestState을 통해 연결된 두 번의 사용자 입력 요청 라운드입니다.
mrtr_sample샘플링 패널로 전달되는 내장형 샘플링 요청입니다.
mrtr_roots구성된 루트에서 음성 없이 조용히 응답되는 내장형 roots/list입니다.
mrtr_edge먼저 inputRequests 전용 라운드가 진행된 후, requestState 전용 라운드가 진행됩니다.
mrtr_loop결코 완료되지 않으므로 클라이언트는 MRTR_MAX_ROUNDS에 정의된 한도에 도달하여 작동을 중단합니다.
입력이 필요함(input_required)으로 표시된 대기 중인 요청 모달에서 MRTR 라운드가 일시 중단됩니다. 이 모달에 응답하면 원래의 요청이 다시 시도됩니다.

도구: 미러링된 헤더 및 제외된 도구​

SEP-2243을 통해 특정 도구는 x-mcp-header로 인자에 주석을 달 수 있으며, 이를 통해 Streamable HTTP 클라이언트에게 해당 인자의 값을 Mcp-Param-* 요청 헤더에 그대로 반영하도록 요청할 수 있습니다.

인스펙터는 도구 탭에 해당 계약의 양쪽 내용을 모두 표시합니다:

  • 유효한 주석이 있는 도구의 경우, 상세 패널에 "미러링된 요청 헤더(SEP-2243)" 섹션이 표시되며, city -> Mcp-Param-City이 그 예입니다.
  • 무효한 주석이 있는 도구의 경우(예: 공백으로 인해 RFC 9110 토큰으로 인정되지 않는 "Bad Header"와 같은 헤더 이름), 사이드바의 "제외됨(SEP-2243)" 구분선 아래에 줄이 그어진 형태로 표시되며 마우스를 올리면 그 이유가 표시됩니다. 규격을 준수하는 클라이언트는 반드시 tools/list에서 그러한 도구를 제거해야 하며, 인스펙터는 도구를 조용히 숨기는 대신 제거된 이유를 명확하게 보여줍니다.

test-servers/configs/xmcpheader-modern-http.json을 사용하여 동일한 상황을 재현할 수 있습니다.

get_weather는 미러링된 도시에 대한 Mcp-Param-City 헤더를 표시하며, invalid_header_tool은 Excluded (SEP-2243) 구분선 아래에 줄이 그어져 표시됩니다.

-32602 오류 패널​

현대 환경에서는 -32602 방식으로 거부하는 tools/call가 별도의 오류 패널 형태로 표시됩니다.

  • 알 수 없는 도구: 메시지에 서버가 나열하지 않은 도구 이름이 포함된 경우입니다. 서버의 tools/list에 없는 이름을 호출하여 재현할 수 있습니다.
  • 잘못된 매개변수: 그 밖의 모든 -32602 경우입니다. 위 구성의 trigger_invalid_params 도구로 재현할 수 있습니다.

두 환경 모두 -32602 방식으로 거부를 처리하지만, 인스펙터의 표시 방식만 다릅니다. 구버전 연결에서는 일반적인 JSON-RPC 오류가 발생하므로 어떤 경우인지 파악하려면 메시지 내용을 직접 확인해야 합니다.

네트워크 및 프로토콜: 헤더와 오류 분류 체계​

현대 환경에서는 일련의 Mcp-* HTTP 헤더를 표준화하였으며, 보다 상세한 JSON-RPC 오류 분류 체계(SEP-2243 / SEP-2575)를 도입했습니다. 두 모니터링 탭은 각각 다른 역할을 담당합니다.

  • 네트워크 탭은 HTTP 뷰로, 복제된 Mcp-* 헤더가 강조 표시되고 센티널 값도 디코딩됩니다.
  • 프로토콜 탭은 JSON-RPC 뷰로, 각각의 사양 오류가 일반적인 오류가 아닌 별도의 형태로 표시됩니다.

test-servers/configs/modern-network-http.json는 각 클래스별로 실제 HTTP 상태 코드와 JSON-RPC 오류 본문을 모두 생성하는 네 가지 도구를 제공합니다.

도구HTTPJSON-RPC 코드의미
trigger_header_mismatch400-32020필수인 미러링 헤더가 누락되었거나 잘못되었습니다.
trigger_missing_capability400-32021요청에 서버가 요구하는 클라이언트의 기능이 포함되어 있지 않습니다.
trigger_unsupported_version400-32022지원되지 않는 버전입니다. 지원되는 버전은 data.supported에 나와 있습니다.
trigger_method_not_found404-32601메서드가 찾을 수 없습니다.
네트워크 탭에서는 HTTP 계층이 표시되며, 여기에는 엄격한 설정을 가진 서버가 반환한 400 Bad Request 오류가 나타납니다.
프로토콜 탭에서는 동일한 오류가 입력 형식의 사양 오류로 표시되며, 그 내용은 서버가 지원하는 버전들과 함께 -32022 UnsupportedProtocolVersion입니다.

세션​

구식의 스트리머블 HTTP 연결의 경우 서버가 할당한 세션 ID(Mcp-Session-Id)가 포함될 수 있으며, 클라이언트는 HTTP DELETE를 통해 해당 연결을 종료합니다. 반면 현대적인 연결은 세션 없이 요청별로 작동하므로 세션 ID가 없어 클라이언트 SDK는 서버에 DELETE를 전송하지 않아 연결 해제가 순전히 클라이언트 측에서 이루어집니다.

이는 클라이언트가 사용하는 테스트 서버에 실질적인 영향을 미칩니다. 요청별로 생성되는 상태 없는 최신 핸들러는 호출 간에 상태를 유지할 수 없기 때문에, 기존의 구식 핸들러와는 달리 test-servers/configs/subscriptions-modern-http.json에서는 update_resource 도구가 생략됩니다. 즉, 변경 작업은 일회용 서버 인스턴스에서 수행되어 다음 읽기 작업에서는 전혀 반영되지 않습니다.