콘텐츠로 이동

MCP Inspector

MCP Inspector는 MCP 서버를 테스트하고 디버깅하기 위한 레퍼런스 개발 도구예요. GitHub 저장소(modelcontextprotocol/inspector)에서 관리되며, 하나의 패키지 @modelcontextprotocol/inspector로 배포됩니다. 흥미로운 점은 이 패키지가 하나의 바이너리 안에 세 가지 클라이언트를 담고 있다는 거예요.

클라이언트 실행 방법 용도
Web npx @modelcontextprotocol/inspector 브라우저에서 동작하는 전체 그래픽 인스펙터. 기본값이면서 가장 풍부한 화면을 제공해요.
CLI npx @modelcontextprotocol/inspector --cli CI, 셸 파이프라인, 코딩 에이전트용으로 스크립팅·머신 리더블한 클라이언트예요.
TUI npx @modelcontextprotocol/inspector --tui 브라우저를 쓸 수 없거나 원하지 않을 때 쓰는 대화형 터미널 UI예요.

세 클라이언트 모두 같은 공용 코어 위에 만들어져서, 연결 동작은 어느 쪽에서든 동일해요. 전송(transport)도 같고, 설정 파일도 같고, 디스크에 저장되는 OAuth 상태도 같으며, 프로토콜 시대(protocol era, 레거시 vs. 2026-07-28 기준 모던) 협상도 똑같이 이뤄져요.

빠른 시작

Inspector는 Node 22.19.0 이상이 필요하고, npx로 바로 실행돼요. 별도 설치가 필요 없어요.

# 웹 UI를 띄우고 로컬 stdio 서버에 연결
npx @modelcontextprotocol/inspector node path/to/server/index.js

# 대상 없이 실행하고 UI에서 서버를 추가
npx @modelcontextprotocol/inspector

이 명령은 일회용 세션 토큰을 담은 URL을 출력해요. 그 URL을 브라우저에서 열면 됩니다. (자세한 내용은 Web 클라이언트 참고)

출시된 서버 검사하기

서버를 실행하는 명령을 Inspector의 인자로 넘기거나, 원격 서버라면 --server-url로 지정해요.

npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

서버마다 필요한 명령과 인자가 다르므로, 항상 서버 자신의 README를 먼저 읽어야 해요.

런처 플래그 vs. 클라이언트 플래그

npx @modelcontextprotocol/inspector가 실행하는 바이너리 mcp-inspector는 얇은 런처이에요. 런처는 딱 두 가지만 전담해요.

  1. 모드 플래그: --web(기본값), --cli, --tui. 최대 하나만 지정할 수 있고, 두 개를 넘기면 Specify at most one of --web, --cli, or --tui. 오류가 나요.
  2. -h / --help.

그 외 나머지(--catalog, --config, --server-url, --transport, --method, OAuth 플래그)는 런처가 아니라 클라이언트가 정의해요. 그리고 클라이언트마다 정의하는 플래그 집합이 전부 같지는 않아요. 설정과 플래그 페이지가 바로 주체(owner)별로 이렇게 구성되어 있어요.

모드 플래그는 명령줄의 맨 앞에서만 인식돼요. --web / --cli / --tui가 아닌 첫 토큰이 나오면 런처 파싱이 끝나고, 그 뒤의 모든 것은 클라이언트로 그대로 전달돼요. 덕분에 서버 자신의 인자로 리터럴 --cli가 뒤에 나와도 괜찮아요.

mcp-inspector --cli node server.js --cli   # 모드는 CLI이고, 뒤쪽 --cli는 server.js로 전달됨

--help는 모드 플래그가 있느냐에 따라 다르게 동작해요. 플래그 없이 mcp-inspector --help를 실행하면 런처의 도움말을 출력하고 종료해요. 반면 모드 플래그와 함께 쓰면 그대로 전달되므로, mcp-inspector --cli --help는 CLI의 전체 플래그 레퍼런스를 출력해요.

다음으로 볼 것들

  • Web 클라이언트 — 그래픽 인스펙터를 탭별로 살펴보는 설명.
  • CLI 클라이언트 — 메서드 레퍼런스, 출력 형식, 종료 코드, CI 레시피.
  • TUI 클라이언트 — 터미널 내비게이션과 키보드 레퍼런스.
  • 설정과 플래그 — 카탈로그 vs. 설정 파일, 클라이언트별 전체 플래그 레퍼런스, 환경 변수.
  • 인증(Authorization) — OAuth 흐름 전체, 세션 중 재인증, 루프백 콜백.
  • 프로토콜 시대(Protocol eras) — 레거시와 모던(2026-07-28) 동작, 시대에 따라 각 탭이 어떻게 달라지는지.
  • 레시피(Recipes) — 클라이언트 설정 가져오기, MCP 앱 검토, Docker, 네트워크 호스팅.
  • 디버깅 가이드 — Inspector를 넘어선 더 넓은 디버깅 전략.