웹 클라이언트

웹 클라이언트 (Web Client)

출처: MCP 공식 문서 — Web client

MCP Inspector의 웹 클라이언트는 이 도구가 제공하는 화면 중에서 가장 풍부한 인터페이스예요. 단일 페이지 앱(Single-Page App)으로 동작하는데, 뒤에서 작은 Node 서버가 실제 MCP 연결을 직접 들고 있어요. 기본 모드라서 npx @modelcontextprotocol/inspector를 모드 플래그 없이 실행하면 바로 이 화면으로 들어가요.

npx @modelcontextprotocol/inspector                       # 빈 상태로 시작, UI에서 서버를 추가
npx @modelcontextprotocol/inspector node build/index.js   # 임시 stdio 서버와 함께
npx @modelcontextprotocol/inspector --catalog ./mcp.json  # 카탈로그 파일과 함께

세션 토큰

웹 클라이언트 뒤의 Node 서버는 여러분 머신에서 프로세스를 띄울 수 있기 때문에, /api/* 라우트마다 실행마다 새로 만들어지는 토큰으로 보호해요. 실행기가 그 토큰을 포함한 URL을 출력하니까 그 URL을 그대로 여세요. localhost:6274를 기억해서 직접 타이핑하지는 말아요.

브라우저는 토큰을 세 곳에서 우선순위 순서대로 찾아요.

  1. 페이지가 로드될 때마다 index.html에 주입되는 window.__INSPECTOR_API_TOKEN__. 이것 덕분에 URL만으로 새로고침하거나 북마크해도 계속 동작해요.
  2. 그 출력 URL에 들어 있는 ?MCP_INSPECTOR_API_TOKEN=... 쿼리 문자열.
  3. 마지막 보험으로서의 sessionStorage.

스크립트로 실행할 때 토큰을 고정하고 싶으면 MCP_INSPECTOR_API_TOKEN 환경 변수를 설정하면 되고, 아예 검사를 끄려면 DANGEROUSLY_OMIT_AUTH=true를 쓰면 되는데, 그 포트에 다른 아무것도 접근할 수 없는 머신에서만 해야 해요. 둘 다 웹 백엔드 환경 변수에 설명돼 있어요.

개발 모드

--dev는 웹 전용 플래그예요. 미리 빌드된 번들을 서빙하는 대신 Vite 개발 서버를 띄우는데, Inspector 자체 코드를 작업할 때 중요해요.

mcp-inspector --web --dev

프로덕션 --web은 빌드된 번들을 서빙해요. 배포된 패키지에는 항상 번들이 들어 있지만, 소스 저장소를 새로 받은 상태에는 없어서 처음 실행할 때 그때그때 빌드해서 써요.

탭 바

탭 표시 조건 하는 일
Servers 항상 서버 목록: 추가, 편집, 불러오기, 연결, 서버별 설정 열기.
Apps 서버가 MCP App 도구를 노출할 때 샌드박스 프레임 안에서 도구의 UI를 렌더링.
Tools tools capability 스키마 탐색, 인자 채우기, 호출, 결과 확인.
Prompts prompts capability 프롬프트 나열, 인자 지정, 생성된 메시지 미리보기.
Resources resources capability 리소스 탐색·읽기·구독.
Tasks capabilities.tasks(legacy 에라) 또는 tasks 확장(modern 에라) 오래 걸리는 도구 호출 추적.
Logs logging capability 서버 notifications/message 출력과 에라에 맞는 레벨 제어.
Protocol 항상 JSON-RPC 전문 기록: 요청, 응답, 알림.
Network HTTP / SSE 서버 원시 HTTP 뷰: 상태, 헤더, 본문.
Console stdio 서버 서버 프로세스의 stderr.

Network와 Console은 절대 같이 나타나지 않아요. legacy와 modern 에라에 대한 설명은 Protocol eras에서 볼 수 있어요.

모니터링 사이드바

Tasks, Logs, Protocol, Network, Console은 모니터 그룹을 이뤄요. 이 그룹을 핀으로 고정하면 탭 바를 떠나 크기 조절 가능한 오른쪽 열로 이동해서, Tools나 Resources에서 작업하는 동안에도 트래픽을 지켜볼 수 있어요. 열 너비와 선택된 모니터 탭은 새로고침해도 유지돼요.

Servers

Servers 화면이 진입점이에요. 서버 한 줄마다 전송 방식(transport), 연결 상태, 서버별 설정을 여는 컨트롤이 담겨 있어요.

이 목록이 어디서 오는지, 편집 가능한지는 실행 방식에 따라 달라요.

실행 서버 목록 편집 가능?
mcp-inspector --web 기본 카탈로그 ~/.mcp-inspector/mcp.json, 첫 실행 시 시드됨 네
--catalog <path> 그 파일, 없으면 샘플 서버로 시드됨 네
--config <path> 그 파일, 읽기 전용(쓰거나 시드하지 않음) 아니요
--server-url <url> 또는 위치 인자 명령 메모리에만 보관되는 임시 서버 하나 아니요

첫 실행 때 웹 클라이언트는 카탈로그에 샘플 서버 두 개를 시드해요. /tmp로 한정된 파일시스템 서버와 '모든 것' 레퍼런스 서버죠. 전체 규칙은 Configuration and flags에서 볼 수 있고, CLI와 TUI가 왜 빈 카탈로그를 시드하는지도 거기 나와 있어요.

Server Settings

  • Protocol Era: legacy / auto / modern. Protocol eras 참고.
  • Log level per request: modern 에라 연결에서 보내는 각 요청에 기본으로 찍는 레벨, 또는 off로 탈퇴 (Logging 참고).
  • Advertised Extensions: Inspector가 capabilities.extensions에 선언하는 확장. 디버깅용 노브인데, 서버는 여러분이 광고하는 내용에 따라 등록을 바꿀 수 있으니까요. Tasks 확장을 해제하고 test-servers/configs/advertised-extensions-http.json 픽스처(Reproducing each era locally)에 다시 연결하면 도구가 사라지는 걸 볼 수 있어요.
  • Roots: roots 클라이언트 capability로 광고되는 루트. 예컨대 @modelcontextprotocol/server-filesystem은 허용 디렉터리를 알기 위해 roots/list를 호출해요.
  • Headers, timeouts, OAuth 필드.
  • Fetch lists one page at a time: 꺼져 있으면 연결 시 목록 결과를 페이지 간에 자동 합산하고, 켜져 있으면 각 목록이 1페이지만 로드한 뒤 Load next page 컨트롤과 N pages loaded 상태를 보여줘요. 도구·리소스·프롬프트 12개를 각각 세 페이지로 나누는 test-servers/configs/pagination-http.json으로 재현할 수 있어요.

Tools

도구를 선택하면 설명, 폼으로 렌더링된 입력 스키마, 어노테이션을 볼 수 있어요. 폼을 채우고 호출하면 결과가 아래 렌더링되는데, 구조화된 콘텐츠·내장 리소스·이미지를 네이티브로 처리해요.

modern 에라 서버에서는 이 화면에 미러링된 Mcp-Param-* 헤더, 제외된 도구, 별도의 -32602 오류 패널까지 보여줘요. 모두 Protocol eras에 들어 있어요.

Resources

리소스와 리소스 템플릿을 MIME 타입·설명과 함께 나열하고, 선택하면 내용을 읽으며, 구독을 지원하는 서버에서는 Subscribe를 제공해요. 구독 방식은 에라마다 달라요. Resource subscriptions 참고.

Prompts

프롬프트 템플릿을 인자와 함께 나열하고, 지정한 인자로 생성된 메시지를 렌더링해요. 프롬프트가 의도한 결과를 만드는지 확인하는 가장 빠른 방법이에요.

Apps

MCP Apps는 UI를 갖는 도구예요. Apps 탭은 그 UI를 별도 포트에서 서빙되는 샌드박스 iframe 안에 렌더링하고, ui/* 브릿지를 실행하며, 뷰의 ui/message 제출과 notifications/message 로그를 사이드 패널에 보여줘요.

  • 샌드박스 포트는 기본적으로 동적으로 정해져요. 노출하거나 포워딩해야 한다면 MCP_SANDBOX_PORT로 고정하면 돼요.
  • 샌드박스는 frame-ancestors CSP로 게이트돼 있어서, 브래킷 IPv6 리터럴은 유효한 CSP host-source가 아니에요. 따라서 Inspector를 localhost, 127.0.0.1, 호스트명, 또는 LAN IPv4로 열어야 해요. 맨 http://[::1]:...로는 안 돼요.
  • 샌드박스 URL은 항상 평문 http라서, https:// Inspector 페이지는 혼합 콘텐츠로 프레임을 막아요. MCP Apps는 오늘날 평문-http 오리진이 필요해요.

CLI 우선의 자동화 리뷰 흐름은 Recipes에서 볼 수 있어요.

Protocol, Network 그리고 Console

세 탭은 같은 트래픽을 다른 상세 수준으로 보여줘요.

  • Protocol: JSON-RPC 전문. 요청과 응답이 짝을 이루고, 알림은 인라인으로, MRTR 라운드는 하나의 대화로 묶이며, 명세 오류는 클래스별로 렌더링돼요.
  • Network: SSE와 Streamable HTTP 서버를 위한 HTTP 계층. 상태 코드, 요청·응답 헤더, 본문. modern 연결에서는 표준화된 Mcp-* 헤더가 강조되고 센티널 값이 디코딩돼요.
  • Console: 연결된 stdio 서버 프로세스의 stderr. 대부분 stdio 서버가 자기 진단을 이곳에 넣어요.

이 뷰들에서 비밀 값은 마스킹되고, 항목을 지우거나 내보낼 수 있어요.

딥 링크

드라이버(스크립트, CI 하니스, 또는 CLI의 --print-handoff)는 단 한 번의 탐색으로 연결된 Inspector에 도달할 수 있어요.

http://127.0.0.1:6274/?serverUrl=<url>&transport=http|sse&autoConnect=<token>
파라미터 의미
serverUrl MCP 서버 URL. http: / https:만 허용되고, 조작된 javascript:나 file: 값은 거부돼요.
transport http(기본) 또는 sse.
autoConnect 필수 CSRF 게이트. 실행마다 만들어지는 세션 토큰과 같아야 하고, 그 토큰은 서버를 띄운 쪽만 알아요.

세 파라미터를 더 쓰면 렌더링된 앱으로 가요. openApp=<toolName>은 도구를 지정하고, appArgs=<base64url(JSON)>는 인자를 공급하며(도구 스키마 기본값 위에 병합), autoOpen=<token>은 도구 호출을 자동으로 실행해요. autoOpen은 호출을 실행하므로 autoConnect와 같은 필수 토큰 게이트를 지녀요.

호스트 바인딩과 오리진

기본적으로 Inspector는 localhost에 바인딩되고 자신의 포트에 대한 루프백 오리진만 수락해요. 백엔드가 여러분 머신에서 프로세스를 띄우므로 둘 다 보안 경계로 다뤄야 해요.

모든 인터페이스에 바인딩하는 것(HOST=0.0.0.0)은 DANGEROUSLY_BIND_ALL_INTERFACES=true를 설정하지 않으면 거부돼요. 특정 비-루프백 주소에 바인딩하는 건 옵트인이 없어도 허용되는데, 모든 인터페이스를 한 번에 노출하는 게 아니라 의도된 단일 노출이기 때문이에요.

전체 매트릭스는 Hosting on a network 레시피에서, 변수는 Configuration에서 볼 수 있어요.

더 알아보기 (Learn more)