MCP Inspector란?

2026년 01월 16일

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: key

🔗 Open inspector with token pre-filled:
   <http://localhost:6274/?MCP_PROXY_AUTH_TOKEN={Session_token}>

DNS 리바인딩 보호

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

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

호스트 바인딩 설정

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

HOST=0.0.0.0 npm start

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

환경 변수 설정

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

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를 통한 시각적 디버깅이 개발 시간을 크게 단축시켜줍니다.