MCP Inspector로 서버 디버깅하기: 연결 실패, 도구 오류, 스키마 문제 찾기

MCP 서버를 Claude Code나 VS Code에 연결했는데 도구가 보이지 않거나 호출이 실패하면, 문제가 서버에 있는지 클라이언트 설정에 있는지부터 가려야 한다. MCP Inspector는 서버를 직접 연결해 요청과 응답을 확인하는 공식 개발 도구로, 클라이언트를 거치지 않고 서버 동작만 따로 검증할 수 있다. 이 글은 Inspector 실행 방법과 증상별 점검 순서를 정리한다. 서버를 처음 만드는 과정은 2026-07-28 스펙 마이그레이션 글의 변경 사항과 함께 보면 이해가 쉽다.

Inspector의 세 가지 실행 방식

Inspector는 @modelcontextprotocol/inspector 패키지 하나에 웹, CLI, TUI 세 클라이언트를 담고 있으며 Node 22.19.0 이상이 필요하다. 세 클라이언트는 같은 전송 방식, 설정 파일, OAuth 상태를 공유한다.

방식	명령	용도
웹	npx @modelcontextprotocol/inspector	브라우저에서 도구·리소스·프롬프트를 눌러 보며 확인
CLI	npx @modelcontextprotocol/inspector --cli	스크립트, CI, 코딩 에이전트에서 기계가 읽는 출력
TUI	npx @modelcontextprotocol/inspector --tui	브라우저 없이 터미널에서 대화형 점검

1단계: 서버 종류별로 연결하기

# 로컬 Node 서버(stdio)
npx @modelcontextprotocol/inspector node path/to/server/index.js

# npm으로 배포된 서버
npx -y @modelcontextprotocol/inspector npx @modelcontextprotocol/server-filesystem ~/Desktop

# PyPI로 배포된 서버
npx @modelcontextprotocol/inspector uvx mcp-server-git --repository ~/code/repo.git

# 원격 HTTP 서버
npx @modelcontextprotocol/inspector --server-url https://api.example.com/mcp --transport http

웹 모드는 일회용 세션 토큰이 포함된 URL을 출력하므로 그 주소를 브라우저에서 연다. 서버마다 필요한 인자가 다르므로 대상 서버의 README를 먼저 확인한다.

2단계: 증상별로 원인 좁히기

증상	먼저 확인할 것	흔한 원인
Inspector에서도 연결 실패	서버 단독 실행 시 오류 출력	의존성 누락, 경로 오류, Node 버전
연결은 되나 응답 해석 오류	서버가 stdout에 쓰는 로그	console.log 등 일반 출력이 프로토콜 메시지와 섞임
도구 목록이 비어 있음	tools/list 응답	도구 등록 전에 연결, 권한에 따라 목록이 걸러짐
호출 시 프로토콜 오류(-32602 등)	요청 인자와 inputSchema	알 수 없는 도구 이름, 요청 형식 오류
호출 결과에 isError: true	결과 텍스트 메시지	입력값 범위·형식, 외부 API 실패 등 업무 오류
Inspector는 정상, 클라이언트만 실패	클라이언트 설정 파일	실행 경로·환경 변수·작업 디렉터리 차이

명세는 도구 오류를 두 종류로 나눈다. 알 수 없는 도구나 요청 형식 오류는 JSON-RPC 프로토콜 오류로, 입력값 검증 실패·API 실패·업무 로직 오류는 isError: true인 도구 결과로 보고한다. Inspector에서 어느 쪽 오류가 나오는지 보면 고칠 위치가 서버의 요청 처리부인지 도구 내부 로직인지 바로 갈린다.

3단계: 스키마 문제를 찾는 방법

1. 웹 UI의 도구 목록에서 대상 도구를 열어 입력 폼이 기대한 필드로 생성되는지 본다. 필드가 없거나 형식이 이상하면 inputSchema 정의를 의심한다.
2. 인자가 없는 도구는 명세 권장대로 { "type": "object", "additionalProperties": false }인지 확인한다. 스키마는 null이면 안 된다.
3. outputSchema가 있는 도구는 호출 결과의 structuredContent가 스키마의 필수 필드를 모두 담았는지 확인한다.
4. 도구 이름이 1~128자, 영문·숫자·밑줄·하이픈·점만 쓰는지 확인한다. 공백이나 쉼표가 들어가면 일부 클라이언트에서 문제가 생길 수 있다.
5. 경계값(빈 문자열, 최댓값 초과, 잘못된 열거값)을 넣어 오류 메시지가 모델이 고칠 수 있을 만큼 구체적인지 본다.

4단계: CLI 모드로 반복 점검 자동화하기

CLI 모드는 결과를 JSON으로 출력할 수 있어 CI나 배포 전 스크립트에 넣기 좋다.

# 도구 목록 확인
npx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list

# 특정 도구 호출 결과를 jq로 검사
npx @modelcontextprotocol/inspector --cli node dist/server.js \
  --method tools/call --tool-name get_stock --tool-arg sku=SKU-1001 \
  --format json | jq '.result.structuredContent.quantity'

배포 파이프라인에서 위 명령이 실패하면 배포를 멈추게 하면, 도구 이름 변경이나 스키마 변경이 클라이언트를 깨뜨리는 일을 미리 막을 수 있다. GitHub Actions 연동 방식은 GitHub Actions AI 코드 리뷰 봇 글의 워크플로 구성을 참고하면 된다.

Inspector는 정상인데 클라이언트에서만 실패할 때

• 클라이언트 설정의 command와 args를 Inspector에서 쓴 명령과 글자 단위로 비교한다.
• 클라이언트가 서버를 실행할 때의 작업 디렉터리와 환경 변수가 터미널과 다를 수 있으므로 절대 경로와 명시적 env를 쓴다.
• 원격 서버라면 인가 흐름을 확인한다. Inspector도 OAuth 흐름을 지원하므로 같은 계정으로 토큰을 받아 비교한다.
• VS Code 계열 클라이언트 설정은 VS Code Continue MCP 연결 글의 문제 해결 항목도 함께 본다.