MCP Inspector - Model Context Protocol 서버 디버그 치트시트

MCP Inspector는 Model Context Protocol 서버의 공식 시각적 테스팅 및 디버깅 도구입니다. MCP 서버를 구축할 때, 실제로 무엇을 노출하고 어떻게 응답하는지 봐야 합니다. Inspector는 서버에 연결하고 도구, 리소스, 프롬프트를 나열하고, 각각을 임의 인자로 호출하고, 양방향으로 흐르는 원본 JSON-RPC 메시지를 표시합니다. Claude, Cursor 또는 다른 클라이언트에 연결하기 전에 서버가 작동하는지 확인하는 가장 빠른 방법입니다.

실행

방법	명령
npx (설치 없음)	`npx @modelcontextprotocol/inspector`
서버 포함	`npx @modelcontextprotocol/inspector node build/index.js`
Python 서버	`npx @modelcontextprotocol/inspector uv run server.py`
원격/SSE 서버	실행 후 UI에서 URL 입력
UI	브라우저에서 열기 (기본값 `http://localhost:6274`)

연결 유형

전송	사용
STDIO	서브프로세스로 실행된 로컬 서버 (가장 일반적)
SSE	Server-Sent Events를 통한 원격 서버
Streamable HTTP	현대적 원격 전송

# 로컬 stdio 서버 검사, 인자 및 환경 전달
npx @modelcontextprotocol/inspector \
  -e API_KEY=abc123 \
  node build/index.js --verbose

인터페이스

탭	표시
도구	모든 도구, JSON 스키마, 호출 양식
리소스	노출된 리소스 및 내용
프롬프트	프롬프트 템플릿 및 인자
알림	서버가 시작한 메시지/로그
히스토리	모든 요청/응답 쌍

도구 테스팅

단계	작업
1	도구 탭을 열고 도구가 나열되었는지 확인
2	입력 스키마가 올바르게 렌더링되었는지 확인 (유형, 필수 필드)
3	생성된 양식을 입력하고 호출 클릭
4	반환된 콘텐츠 및 모든 `isError` 플래그 검사
5	형태 문제를 디버그하기 위해 히스토리의 원본 JSON-RPC 읽기

이 루프는 가장 흔한 MCP 버그를 포착합니다. 잘못된 스키마, 잘못된 콘텐츠 형태를 반환하는 도구, 처리되지 않은 오류입니다.

선적 전에 검증할 사항

확인	이유
도구 이름이 고유/설명적임	클라이언트가 모델에 표시
설명이 언제 사용할 것인지 설명	올바른 도구 선택 수행
입력 스키마가 정확함	잘못된 호출 방지
오류가 `isError` 메시지 반환	모델이 복구 가능
큰 출력이 페이지화/잘림	컨텍스트 창 폭발 방지
리소스에 안정적 URI 있음	클라이언트가 캐시/참조

디버깅 팁

증상	확인
서버가 연결되지 않음	명령/인자; 실행 터미널의 stderr
도구 누락	등록 코드; 서버 재시작
스키마가 이상하게 렌더링됨	도구 정의의 JSON 스키마 유형
클라이언트가 다르게 작동	히스토리의 원본 JSON-RPC 비교
Env-의존 버그	Inspector를 `-e KEY=value`로 재실행

일반적인 워크플로우

# TypeScript MCP 서버를 위한 개발 및 테스트 루프
npm run build && npx @modelcontextprotocol/inspector node build/index.js

# uv로 Python 서버 테스트
npx @modelcontextprotocol/inspector uv run my_server.py

# 클라이언트에 추가하기 전에 원격 SSE 서버 검증
npx @modelcontextprotocol/inspector   # SSE 선택, URL 붙여넣기

MCP Inspector vs 대안

접근	트레이드오프
MCP Inspector	목적 내장, 시각적, 원본 프로토콜 표시
실제 클라이언트에 연결	현실적이지만 느린 피드백 루프
손으로 작성된 JSON-RPC	완전한 제어, 번거로움
단위 테스트	빠르고 반복 가능; 탐색을 위해 Inspector와 쌍

구축 중에 Inspector를 사용한 후 자동 테스트를 추가하세요. MCP 서버에서 서버 구현 패턴을 참조하세요.