MCP Inspector로 MCP 서버 디버깅하기

MCP 서버를 하나 만들었습니다. 도구를 정의하고 핸들러를 구현했는데, 이걸 Claude나 ChatGPT에 바로 연결해서 테스트하면 문제가 생겼을 때 원인을 찾기가 쉽지 않아요. LLM이 도구를 잘못 호출한 건지, 서버가 엉뚱한 응답을 보낸 건지, 전송 계층에서 뭔가 꼬인 건지 구분이 안 되거든요 😅

REST API를 만들면 Postman으로 테스트하잖아요. MCP 서버도 프로토콜 수준에서 직접 메시지를 주고받으며 검증할 수 있으면 좋겠죠. 바로 그 역할을 하는 것이 Anthropic에서 공식적으로 제공하는 MCP Inspector입니다.

이 글에서는 MCP Inspector의 설치부터 웹 UI 활용, 설정 파일 관리, CLI 모드 자동화까지 다뤄보겠습니다.

MCP Inspector란?

MCP Inspector는 MCP(Model Context Protocol) 서버를 테스트하고 디버깅하기 위한 공식 개발 도구입니다. Anthropic이 MCP 프로토콜과 함께 오픈소스로 제공하고 있고, GitHub 스타가 9천 개를 넘길 정도로 MCP 생태계에서 널리 쓰이고 있어요.

내부적으로는 두 컴포넌트가 돌아갑니다. 브라우저에서 실행되는 React 기반 웹 UI(MCP Inspector Client)와, 이 웹 UI와 MCP 서버 사이를 이어주는 Node.js 기반 프록시(MCP Proxy)예요. 프록시가 MCP 클라이언트 역할을 맡아서 테스트 대상 서버에 접속하고, 웹 UI에서 보낸 요청을 JSON-RPC 메시지로 바꿔 전달하는 구조입니다.

덕분에 LLM 없이도 MCP 서버의 도구, 리소스, 프롬프트를 직접 호출해볼 수 있어요. 서버가 프로토콜 스펙을 잘 따르는지, 요청에 올바른 응답을 돌려주는지 하나하나 확인할 수 있어서 개발 초기에 특히 유용합니다.

설치와 실행

MCP Inspector는 npm 패키지로 배포되기 때문에 설치 없이 바로 실행할 수 있습니다. Node.js 22.7.5 이상이 필요해요.

bunx @modelcontextprotocol/inspector
npx @modelcontextprotocol/inspector

이 명령을 실행하면 프록시 서버와 웹 UI가 동시에 뜨고, 브라우저가 자동으로 열립니다. 웹 UI는 기본적으로 http://localhost:6274에서 접근할 수 있고, 프록시 서버는 http://localhost:6277에서 돌아갑니다. 포트 번호가 궁금하실 수 있는데, 6274는 휴대폰 키패드로 MCPI, 6277은 MCPP를 누른 숫자예요 🤓

특정 MCP 서버를 바로 연결해서 시작할 수도 있습니다.

npx @modelcontextprotocol/inspector node build/index.js

이렇게 하면 Inspector가 뜨면서 지정한 서버에 stdio 전송 방식으로 자동 연결됩니다. 환경 변수가 필요하다면 -e 플래그를 사용하면 돼요.

npx @modelcontextprotocol/inspector -e API_KEY=abc123 node build/index.js

Docker를 선호한다면 컨테이너로도 실행할 수 있습니다.

docker run --rm \
  -p 127.0.0.1:6274:6274 \
  -p 127.0.0.1:6277:6277 \
  -e HOST=0.0.0.0 \
  -e MCP_AUTO_OPEN_ENABLED=false \
  ghcr.io/modelcontextprotocol/inspector:latest

보안을 위해 127.0.0.1에 바인딩하는 게 중요합니다. 0.0.0.0으로 열면 네트워크에 노출되니까요.

웹 UI로 서버 테스트하기

Inspector를 실행하고 브라우저에서 접속하면 좌측 사이드바에 연결 설정이 보입니다. 전송 방식(Transport Type)을 stdio, SSE, Streamable HTTP 중에서 고르고 서버 정보를 입력한 뒤 Connect를 누르면 끝이에요.

연결되면 상단의 Tools, Resources, Prompts 탭을 오가며 테스트하면 됩니다.

Tools 탭에서는 서버가 노출하는 도구 목록을 보고 직접 호출할 수 있어요. 도구를 선택하면 입력 파라미터 폼이 나타나는데, 값을 채우고 Run Tool을 누르면 JSON-RPC 요청이 서버로 날아갑니다. 응답은 바로 아래에 표시되고, 오류가 나면 에러 메시지도 같이 보여줘요.

Resources 탭에서는 서버가 제공하는 리소스 목록을 탐색하고, URI를 선택해서 내용을 읽어올 수 있습니다.

Prompts 탭에서는 서버에 정의된 프롬프트 템플릿을 확인하고 인자를 넣어서 결과를 미리 볼 수 있어요.

세 탭 모두에서 주고받는 JSON-RPC 메시지가 실시간으로 찍히기 때문에 요청과 응답 흐름을 통째로 들여다볼 수 있습니다. 서버가 이상한 응답을 보내는 것 같다면 로그를 확인해보면 바로 답이 나오죠.

설정 파일로 서버 관리하기

매번 서버 정보를 수동으로 입력하는 건 번거롭습니다. MCP Inspector는 mcp.json 형식의 설정 파일을 지원해서 여러 서버를 한 번에 관리할 수 있어요.

mcp.json

{
  "mcpServers": {
    "math-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "NODE_ENV": "development"
      }
    },
    "weather-server": {
      "command": "python",
      "args": ["-m", "weather_mcp"]
    }
  }
}

이 파일을 만들어두면 Inspector가 자동으로 감지해서 서버 목록을 보여줍니다. 서버가 하나뿐이거나 default-server라는 이름의 서버가 있으면 자동으로 선택까지 해줘요.

원격 서버도 설정 파일에 추가할 수 있습니다.

mcp.json

{
  "mcpServers": {
    "remote-api": {
      "url": "https://api.example.com/mcp",
      "type": "streamable-http"
    }
  }
}

이 설정 파일 형식은 Claude Desktop이나 Cursor 같은 MCP 호스트에서 사용하는 것과 동일합니다. 그래서 Inspector에서 테스트를 마치고 나면 그 설정을 그대로 복사해서 다른 클라이언트에 붙여넣을 수 있어요. Inspector의 Server Export 기능을 쓰면 현재 연결된 서버의 설정을 클립보드로 복사할 수 있어서 더 편리합니다.

인증과 보안

Inspector는 보안 쪽에 꽤 신경을 쓴 도구예요. 프록시 서버가 뜰 때 랜덤 세션 토큰을 하나 만들고, 모든 요청에 이 토큰을 Bearer 토큰으로 넣어야 합니다. 브라우저 URL에 토큰이 미리 채워져 있어서 평소에는 의식할 일이 없지만, API로 직접 접근한다면 Authorization 헤더에 넣어줘야 해요.

SSE로 원격 서버에 연결할 때 별도 인증이 필요하면 사이드바에서 Bearer 토큰을 입력할 수 있습니다. 헤더 이름도 바꿀 수 있어서 X-API-Key 같은 비표준 헤더를 쓰는 서버에도 맞출 수 있어요.

DNS 리바인딩 공격 방어를 위한 Origin 검증도 기본으로 켜져 있습니다. 추가로 허용할 오리진이 있다면 ALLOWED_ORIGINS 환경 변수에 쉼표로 구분해서 넣으면 돼요.

DANGEROUSLY_OMIT_AUTH 환경 변수로 인증을 끌 수도 있긴 한데, 변수 이름에서 느껴지듯 정말 위험합니다. 악성 웹사이트를 방문하는 것만으로도 공격자가 Inspector를 통해 로컬 MCP 서버에 접근할 수 있게 되거든요.

타임아웃 설정

외부 API를 호출하거나 무거운 연산을 수행하는 도구는 응답이 느릴 수 있습니다. Inspector는 이런 상황을 위해 타임아웃 옵션을 제공해요.

설정	설명	기본값
`MCP_SERVER_REQUEST_TIMEOUT`	개별 요청 타임아웃(ms)	300000
`MCP_REQUEST_MAX_TOTAL_TIMEOUT`	전체 최대 타임아웃(ms)	60000
`MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS`	진행 알림 시 타임아웃 초기화	true

이 값들은 웹 UI의 Configuration 버튼에서 변경할 수 있고, 브라우저의 localStorage에 저장되어 세션 간에 유지됩니다. URL 쿼리 파라미터로도 설정할 수 있어서 ?MCP_SERVER_REQUEST_TIMEOUT=60000 같이 URL에 붙이면 팀원에게 링크로 공유하기 편합니다.

CLI 모드

웹 UI가 인터랙티브 디버깅에 좋다면, CLI 모드는 자동화에 적합합니다. --cli 플래그를 붙이면 브라우저 없이 터미널에서 바로 MCP 서버와 통신할 수 있어요.

서버의 도구 목록을 확인하려면 이렇게 실행합니다.

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list

특정 도구를 호출할 때는 --tool-name과 --tool-arg를 사용합니다.

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name get_weather \
  --tool-arg location=Seoul

리소스와 프롬프트도 마찬가지로 조회할 수 있어요.

npx @modelcontextprotocol/inspector --cli node build/index.js --method resources/list
npx @modelcontextprotocol/inspector --cli node build/index.js --method prompts/list

원격 서버에 연결할 때는 URL을 직접 지정합니다. 기본적으로 SSE 전송 방식을 사용하고, --transport http로 Streamable HTTP를 선택할 수도 있어요.

npx @modelcontextprotocol/inspector --cli https://api.example.com/sse \
  --method tools/list

npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --transport http \
  --method tools/list

인증이 필요한 서버라면 --header 플래그로 커스텀 헤더를 추가하면 됩니다.

npx @modelcontextprotocol/inspector --cli https://api.example.com/mcp \
  --header "Authorization: Bearer sk-abc123" \
  --method tools/list

CLI 모드의 결과는 JSON으로 출력되기 때문에 jq와 조합하면 셸 스크립트에서 쓰기 좋습니다. 예를 들어 서버가 노출하는 도구 이름만 뽑으려면 이렇게 할 수 있어요.

npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/list 2>/dev/null | jq -r '.tools[].name'

포트와 환경 변수

Inspector의 동작을 세밀하게 제어하고 싶다면 환경 변수를 활용할 수 있습니다. 주요 환경 변수를 정리하면 이렇습니다.

CLIENT_PORT — 웹 UI 포트 (기본값: 6274)
SERVER_PORT — 프록시 서버 포트 (기본값: 6277)
HOST — 바인딩할 호스트 (기본값: localhost)
MCP_PROXY_AUTH_TOKEN — 프록시 인증 토큰을 직접 지정
MCP_AUTO_OPEN_ENABLED — 브라우저 자동 열기 여부 (기본값: true)
ALLOWED_ORIGINS — 허용할 오리진 목록 (쉼표 구분)
MCP_PROXY_FULL_ADDRESS — 프록시의 전체 주소를 직접 지정

예를 들어 포트 충돌을 피하려면 이렇게 실행합니다.

CLIENT_PORT=3000 SERVER_PORT=3001 npx @modelcontextprotocol/inspector

CI 환경처럼 브라우저가 없는 곳에서는 자동 열기를 꺼두면 됩니다.

MCP_AUTO_OPEN_ENABLED=false npx @modelcontextprotocol/inspector

MCPJam과 비교하면?

MCP Inspector가 프로토콜 수준의 디버깅에 집중하는 가벼운 도구라면, MCPJam은 LLM 연동 테스트와 평가까지 포함하는 종합 플랫폼입니다. 용도에 따라 선택하면 돼요.

MCP Inspector는 서버가 프로토콜 스펙을 제대로 따르는지 확인하는 데 최적화되어 있습니다. 도구의 입출력이 올바른지, JSON-RPC 메시지 형식이 맞는지 같은 기본적인 검증이 필요할 때 쓰면 됩니다. 공식 도구답게 MCP 스펙 변경에 빠르게 대응하고, 설치도 npx 한 줄이면 끝이라서 진입 장벽이 낮아요.

반면 “AI 모델이 이 도구를 적절한 시점에 올바르게 호출하는가?”까지 확인하고 싶다면 MCPJam이 더 적합합니다. 실제 LLM과 대화하면서 테스트하거나 여러 모델 간 비교, OAuth 디버깅, 평가 자동화 같은 고급 기능이 필요한 단계에서 힘을 발휘하거든요.

실무에서는 둘을 순서대로 활용하는 흐름이 자연스럽습니다. MCP Inspector로 서버의 기본 동작을 먼저 검증하고, 프로토콜 수준에서 문제가 없으면 MCPJam으로 넘어가서 LLM 연동까지 테스트하는 거죠.

마치며

MCP 서버를 만들 때 Inspector가 있으면 개발 흐름이 달라집니다. 처음에는 웹 UI로 도구와 리소스를 하나씩 호출하면서 동작을 확인하고, 안정화 단계에 들어가면 CLI 모드로 반복 테스트를 자동화할 수 있거든요.

무엇보다 JSON-RPC 메시지를 실시간으로 볼 수 있다는 점이 디버깅에 결정적입니다. 서버가 예상과 다른 응답을 보내거나 에러를 반환할 때, 원시 메시지를 직접 들여다보면 원인을 훨씬 빨리 찾을 수 있어요. MCP 서버를 다루고 있다면 개발 워크플로우에 꼭 넣어보세요.

더 자세한 내용은 MCP Inspector GitHub 저장소를 참고하세요.

This work is licensed under CC BY 4.0

MCP Inspector란?

설치와 실행

웹 UI로 서버 테스트하기

설정 파일로 서버 관리하기

인증과 보안

타임아웃 설정

CLI 모드

포트와 환경 변수

MCPJam과 비교하면?

마치며

개발자를 위한 뉴스레터

관련 포스트

Model Context Protocol: AI 애플리케이션의 통신 표준

MCPJam으로 MCP 서버 테스트하기

클로드 코드에서 MCP 서버 연동하기

MCP Registry