MCP Inspector
MCP Inspector
브라우저, 명령줄, 터미널에서 MCP 서버를 테스트하고 디버깅하기 위한 상호작용 개발 도구예요. MCP Inspector는 MCP 서버를 테스트·디버깅하기 위한 참조 개발자 도구입니다.
출처: 문서
본문
MCP Inspector는 MCP 서버를 테스트하고 디버깅하기 위한 참조 개발자 도구예요. @modelcontextprotocol/inspector라는 단일 패키지로 제공되며, 하나의 바이너리 뒤에 세 개의 클라이언트를 담고 있습니다.
| 클라이언트 | 호출 | 용도 |
|---|---|---|
| Web | npx @modelcontextprotocol/inspector |
브라우저에서 사용하는 완전한 그래픽 Inspector. 기본값이며 가장 풍부한 표면이에요. |
| CLI | npx @modelcontextprotocol/inspector --cli |
CI, 셸 파이프라인, 코딩 에이전트용 스크립트 가능하고 기계 판독 가능한 클라이언트. |
| TUI | npx @modelcontextprotocol/inspector --tui |
브라우저를 사용할 수 없거나 원하지 않을 때 쓰는 상호작용 터미널 UI. |
세 개 모두 같은 공유 코어 위에 구축되어서, 연결 동작이 세 클라이언트에서 동일해요. 같은 전송, 같은 구성 파일, 디스크의 같은 OAuth 상태, 같은 프로토콜 시대 협상(레거시 대 현대 2026-07-28)을 사용하죠.
빠른 시작 (Quickstart)
Inspector는 Node 22.19.0 이상이 필요하며 npx로 직접 실행됩니다. 설치가 필요 없어요.
Web
# Launch the web UI and connect to a local stdio server
npx @modelcontextprotocol/inspector node path/to/server/index.js
# Or launch with no target and add servers from the UI
npx @modelcontextprotocol/inspector
이 명령은 일회성 세션 토큰이 포함된 URL을 출력하니, 브라우저에서 열어 보세요. Web 클라이언트를 참고하세요.
CLI
# List a server's tools and exit
npx @modelcontextprotocol/inspector --cli node path/to/server/index.js --method tools/list
# Call a tool and pipe the result into jq
npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp --transport http \
--method tools/call --tool-name get_weather --tool-arg city=Boston --format json | jq .result
CLI 클라이언트를 참고하세요.
TUI
npx @modelcontextprotocol/inspector --tui node path/to/server/index.js
TUI 클라이언트를 참고하세요.
게시된 서버 검사하기
Inspector의 인수로 서버를 실행하는 명령을 전달하거나, --server-url로 원격 서버를 가리키세요.
npm 패키지
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop
PyPI 패키지
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/mcp/servers.git
원격 HTTP 서버
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http
모든 서버는 서로 다른 명령과 인수를 요구하므로, 항상 먼저 서버 자신의 README를 읽어 보세요.
런처 플래그 대 클라이언트 플래그
npx @modelcontextprotocol/inspector가 실행하는 바이너리 mcp-inspector는 얇은 런처예요. 두 가지만 소유합니다.
- 모드 플래그:
--web(기본값),--cli, 또는--tui. 최대 하나만 가능하며, 두 개를 전달하면Specify at most one of --web, --cli, or --tui.오류가 나요. -h/--help.
그 밖의 모든 것(--catalog, --config, --server-url, --transport, --method, OAuth 플래그)은 런처가 아니라 클라이언트가 정의하며, 클라이언트마다 같은 집합을 정의하지 않아요. 구성과 플래그 페이지는 이렇게 소유자별로 정리되어 있어요.
모드 플래그는 명령줄 앞에서만 인식됩니다.
--web/--cli/--tui가 아닌 첫 토큰이 런처 파싱을 끝내고, 이후의 모든 것은 변경 없이 클라이언트로 전달돼요. 그래서 리터럴--cli를 나중에 서버 자신의 인수 중 하나로 쓸 수 있죠.mcp-inspector --cli node server.js --cli # mode is CLI; the trailing --cli goes to server.js
--help는 모드 플래그 유무에 따라 다르게 동작합니다. 플래그 없이mcp-inspector --help는 런처의 도움말을 출력하고 종료해요. 모드 플래그가 있으면 전달되므로,mcp-inspector --cli --help는 대신 CLI의 전체 플래그 참조를 출력합니다.
다음으로 어디
- Web 클라이언트 — 그래픽 Inspector의 탭별 둘러보기
- CLI 클라이언트 — 메서드 참조, 출력 형식, 종료 코드, CI 레시피
- TUI 클라이언트 — 터미널 내비게이션과 키보드 참조
- 구성과 플래그 — 카탈로그 대 구성 파일, 클라이언트별 전체 플래그 참조, 환경 변수
- 인증 — OAuth 흐름 전체, 세션 중 재인증, 루프백 콜백
- 프로토콜 시대 — 레거시 대 현대(2026-07-28) 동작과 시대별 탭 변화
- 레시피 — 클라이언트 구성 가져오기, MCP Apps 검토, Docker, 네트워크 호스팅
- 디버깅 가이드 — Inspector를 넘어선 더 넓은 디버깅 전략