MCP Inspector: MCP 서버 개발을 위한 필수 도구

MCP
2025년 07월 06일

MCP Inspector란?

MCP Inspector는 Model Context Protocol (MCP) 서버를 시각적으로 테스트하고 디버깅할 수 있는 강력한 도구입니다. 웹 기반 UI를 통해 MCP 서버의 도구(tools), 리소스(resources), 프롬프트(prompts)를 손쉽게 탐색하고 테스트할 수 있습니다.

주요 기능

1. 시각적 테스팅 인터페이스

  • 웹 기반 UI로 MCP 서버와 상호작용
  • 실시간으로 서버 응답 확인
  • 직관적인 사용자 인터페이스

2. 다양한 전송 방식 지원

  • STDIO: 표준 입출력을 통한 통신
  • SSE (Server-Sent Events): 실시간 이벤트 스트림
  • Streamable HTTP: HTTP 기반 스트리밍

3. CLI 모드

  • 명령줄에서 직접 MCP 서버와 상호작용
  • 스크립팅 및 자동화에 유용
  • 프로그래밍 방식으로 서버 테스트 가능

설치 및 기본 사용법

빠른 시작

가장 간단한 방법으로 MCP Inspector를 실행할 수 있습니다:

npx @modelcontextprotocol/inspector

이 명령을 실행하면 http://localhost:6274에서 웹 인터페이스에 접근할 수 있습니다.

MCP 서버와 함께 실행

빌드된 MCP 서버를 직접 검사하려면:

npx @modelcontextprotocol/inspector node build/index.js

환경 변수와 인수 전달

MCP 서버에 환경 변수를 전달하는 방법:

npx @modelcontextprotocol/inspector -e API_KEY=your-api-key -e DEBUG=true node build/index.js

서버에 명령줄 인수를 전달하는 방법:

npx @modelcontextprotocol/inspector node build/index.js arg1 arg2

고급 사용법

설정 파일 사용

복잡한 설정이나 여러 서버를 관리할 때는 JSON 설정 파일을 사용할 수 있습니다:

{
  "mcpServers": {
    "everything": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-everything"],
      "env": {
        "hello": "Hello MCP!"
      }
    },
    "my-server": {
      "command": "node",
      "args": ["build/index.js", "arg1", "arg2"],
      "env": {
        "key": "value",
        "key2": "value2"
      }
    }
  }
}

설정 파일을 사용하여 실행:

npx @modelcontextprotocol/inspector --config path/to/config.json --server everything

포트 커스터마이징

기본 포트(클라이언트: 6274, 서버: 6277)를 변경하려면:

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector node build/index.js

CLI 모드 활용

기본 CLI 사용법

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

도구 목록 조회

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

특정 도구 실행

npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/call --tool-name mytool --tool-arg key=value

리소스 목록 조회

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

프롬프트 목록 조회

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

원격 서버 연결

npx @modelcontextprotocol/inspector --cli https://my-mcp-server.example.com

개발 환경 설정

개발 모드 실행

Unix/Linux/macOS:

npm run dev

Windows:

npm run dev:windows

프로덕션 빌드

npm run build
npm start

개별 컴포넌트 빌드

클라이언트만 빌드:

npm run build-client

서버만 빌드:

npm run build-server

보안 고려사항

인증 토큰

MCP Inspector는 보안을 위해 세션 토큰을 생성합니다:

🔑 Session token: 3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

🔗 Open inspector with token pre-filled:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=3a1c267fad21f7150b7d624c160b7f09b0b8c4f623c7107bbf13378f051538d4

DNS 리바인딩 보호

특정 오리진만 허용하도록 설정:

ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274 npm start

호스트 바인딩 설정

개발 환경에서만 모든 인터페이스에 바인딩:

HOST=0.0.0.0 npm start

⚠️ 주의: 프로덕션 환경에서는 보안상 권장하지 않습니다.

환경 변수 설정

MCP Inspector는 다양한 환경 변수를 통해 동작을 제어할 수 있습니다:

설정설명기본값
MCP_SERVER_REQUEST_TIMEOUTMCP 서버 요청 타임아웃 (ms)10000
MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS진행 알림 시 타임아웃 재설정true
MCP_REQUEST_MAX_TOTAL_TIMEOUT최대 총 타임아웃 (ms)60000
MCP_PROXY_FULL_ADDRESS프록시 서버 주소""
MCP_AUTO_OPEN_ENABLED자동 브라우저 열기true

URL 쿼리 매개변수

URL을 통해 초기 설정을 지정할 수 있습니다:

http://localhost:6274/?MCP_SERVER_REQUEST_TIMEOUT=10000&MCP_REQUEST_TIMEOUT_RESET_ON_PROGRESS=false

전송 방식 설정:

http://localhost:6274/?transport=sse&serverUrl=http://localhost:8787/sse
http://localhost:6274/?transport=stdio&serverCommand=npx&serverArgs=arg1%20arg2

실제 사용 예제

1. 간단한 MCP 서버 테스트

# 서버 실행
npx @modelcontextprotocol/inspector node my-server.js
 
# 브라우저에서 http://localhost:6274 접속
# UI를 통해 도구, 리소스, 프롬프트 탐색

2. 복잡한 설정으로 테스트

# 환경 변수와 인수를 포함한 실행
npx @modelcontextprotocol/inspector \
  -e DATABASE_URL=postgresql://localhost/mydb \
  -e API_KEY=secret123 \
  -- node build/index.js --verbose --port 3000

3. CLI를 통한 자동화된 테스트

# 도구 목록 확인
npx @modelcontextprotocol/inspector --cli node build/index.js --method tools/list
 
# 특정 도구 실행
npx @modelcontextprotocol/inspector --cli node build/index.js \
  --method tools/call \
  --tool-name search \
  --tool-arg query="MCP tutorial"

마무리

MCP Inspector는 MCP 서버 개발 과정에서 필수적인 도구입니다. 시각적 인터페이스를 통해 서버의 동작을 실시간으로 확인하고, CLI 모드를 통해 자동화된 테스트를 수행할 수 있습니다.

개발 초기 단계부터 MCP Inspector를 활용하면 더 안정적이고 효율적인 MCP 서버를 개발할 수 있습니다. 특히 복잡한 도구나 리소스를 다루는 서버의 경우, Inspector를 통한 시각적 디버깅이 개발 시간을 크게 단축시켜줍니다.