본문으로 건너뛰기

레시피

stdio 서버와 HTTP 서버 연결하기​

stdio​

stdio 서버는 Inspector가 생성하는 프로세스입니다. 모든 위치 정보는 명령줄에 포함됩니다.

mcp-inspector node build/index.js -- --verbose --config /etc/myserver.conf

서버에 전달될 모든 인자 앞에 --를 붙여 주십시오. 이 구분자가 없으면 --verbose가 Inspector에 의해 해석되어 서버에 전달되지 않습니다.

-e를 사용하여 프로세스에 환경 변수를 지정하고, --cwd를 사용하여 작업 디렉터리를 지정해 주십시오.

mcp-inspector -e API_KEY=abc123 -e REGION=us-east-1 --cwd ~/projects/my-server \
  node build/index.js

서버의 stderr 정보는 (웹 환경의) Console 탭이나 (TUI 환경의) o인 Console 탭에 표시됩니다. 대부분의 stdio 서버는 진단 정보를 이곳에 기록하므로, 명백한 원인 없이 연결에 실패할 경우 먼저 이곳을 확인해 보십시오.

HTTP와 SSE​

mcp-inspector --server-url https://api.example.com/mcp --transport http \
  --header "X-Tenant: acme"

--transport는 http(Streamable HTTP)와 sse을 지원합니다. 서버에 보안 설정이 적용된 경우 Authorization을 참조하십시오. 사전에 별도의 설정이 필요하지 않으며, 서버가 401에 응답하면 인스펙터가 해당 문서에 설명된 OAuth 흐름을 실행하여 연결을 다시 시도하기 때문입니다.

HTTP 서버의 경우 protocol era도 지정해야 합니다. 기본값은 legacy이며, 2026-07-28의 동작 방식을 적용하려면 서버 설정에서 modern 또는 auto을 설정하거나 카탈로그 파일에서 protocolEra을 설정해야 합니다.

기존 클라이언트 설정 파일 가져오기​

서버들 화면의 Add Servers 기능을 사용하면 다른 곳에서 이미 설정해 둔 MCP 서버들을 다시 입력하는 대신 직접 가져올 수 있습니다. 이 기능은 Claude Desktop, Cursor, Cline, VS Code의 클라이언트 설정 파일들을 직접 파싱할 뿐만 아니라, 서버 자체의 MCP Registry server.json도 읽어들입니다.

가져온 서버 정보는 현재 활성화된 catalog(인스펙터에서 수정 가능한 서버 목록)에 병합되므로 기존의 서버 항목들이 삭제되지 않습니다. 만약 카탈로그를 전혀 건드리고 싶지 않다면, 외부 파일을 읽기 전용 모드로 사용하여 서버를 실행하십시오.

mcp-inspector --config ~/Library/Application\ Support/Claude/claude_desktop_config.json

--config은 해당 파일이 그대로 제공되며, 절대로 수정되거나 초기화되거나 마이그레이션되지 않도록 보장합니다.

Add Servers 기능을 통해 기존 클라이언트 설정 파일이나 registry server.json 파일에서 서버를 가져올 수 있습니다.

MCP 애플리케이션 검토하기​

MCP 앱들은 UI 위젯을 포함하는 도구들입니다. 자동화된 리뷰어(CI 또는 에이전트)의 경우, JSON을 반환하는 모든 검사에는 CLI를 사용해야 하며, 렌더링된 위젯을 확인할 때만 브라우저를 열어야 합니다.

도구를 호출하지 않고도 보안 상태를 점검할 수 있습니다

mcp-inspector --cli --transport http --server-url https://example.com/mcp \
  --method tools/call --tool-name <tool> --app-info

표준 출력에는 JSON 한 줄만 표시됩니다. 해당 도구에 앱이 있는 경우 0 상태로 종료되고, 앱이 없는 경우에는 2 상태로 종료되어 && 체인이 조기에 종료됩니다.

{
  "hasApp": true,
  "toolName": "get_pros",
  "resourceUri": "ui://pros/view.html",
  "csp": { "connectDomains": ["https://api.example.com"] },
  "permissions": { "clipboard": false },
  "prefersBorder": true,
  "resourceMimeType": "text/html"
}

csp와 permissions(리소스가 하나를 지정할 경우 domain도 포함)는 도구가 아닌 UI 리소스에 존재하므로, --app-info은 해당 리소스를 읽어들입니다. 도구는 절대 호출되지 않습니다.

브라우저를 사용하지 않고도 전체 결과 데이터를 가져올 수 있습니다

mcp-inspector --cli --transport http --server-url https://example.com/mcp \
  --method tools/call --tool-name <tool> --tool-args-json '{"zip":"10001"}' --format json

웹 인스펙터를 단 한 번만 실행하며, 이때는 로컬 루프백 연결만 사용됩니다

TOKEN="$(openssl rand -hex 24)"
HOST=127.0.0.1 CLIENT_PORT=6274 MCP_SANDBOX_PORT=6275 \
MCP_AUTO_OPEN_ENABLED=false MCP_INSPECTOR_API_TOKEN="$TOKEN" \
mcp-inspector --web &

여기서는 MCP_SANDBOX_PORT 고정이 매우 중요합니다. 앱의 UI는 기본적으로 동적인 별도의 샌드박스 포트를 통해 제공되므로, 자동화 작업에서 이에 접근하려면 고정된 주소가 필요합니다.

렌더링된 위젯으로 이동할 수 있는 딥 링크를 하나 사용할 수 있습니다

http://127.0.0.1:6274/?serverUrl=<encoded url>&transport=http&autoConnect=<TOKEN>&openApp=<tool>&appArgs=<base64url(JSON)>&autoOpen=<TOKEN>

appArgs는 base64url로 인코딩된 JSON 형태의 도구 인자이며, 모든 딥링크 매개변수는 딥링크 항목에 설명되어 있습니다. autoConnect와 autoOpen는 둘 다 세션 토큰과 동일해야 하는데, 이는 autoOpen가 URL에서 직접 도구 호출을 수행하기 때문에 autoConnect와 동일한 게이트가 필요하기 때문입니다.

sleep 대신 결정론적 신호 기다리기

Apps 화면은 안정적인 자동화 인터페이스를 제공합니다. 일정 시간을 무작정 기다리는 대신 다음 속성을 폴링하세요.

선택자속성값들
[data-testid="apps-form"]data-app-statusready (실패 시 data-app-error에 원인이 포함됨)
[data-testid="connection-status"]data-statusconnecting 이후 connected 또는 error (data-error-message에 자세한 내용이 있음)
[data-testid="connection-status"]data-deeplinkparsed, rejected, 또는 none (none는 딥링크가 제공되지 않았음을, rejected는 딥링크가 거부되었음을 의미합니다)

Docker​

컨테이너 이미지는 linux/amd64 및 linux/arm64를 위해 GitHub Container Registry에 게시됩니다.

docker run --rm -p 6274:6274 ghcr.io/modelcontextprotocol/inspector

컨테이너 로그에서 세션 토큰을 읽거나 -e MCP_INSPECTOR_API_TOKEN=<value>로 토큰을 고정하세요.

이 이미지는 기본적으로 --web를 사용하며, 브라우저 자동 열기 기능이 꺼진 상태에서 0.0.0.0:6274에 바인딩되고 비루트 사용자로 실행됩니다. 컨테이너가 -p을 통해 접근 가능하도록 와일드카드 주소에 바인딩되어야 하므로 DANGEROUSLY_BIND_ALL_INTERFACES=true가 설정됩니다.

이미지의 HEALTHCHECK은 웹 UI를 점검하므로, 웹 서버가 없는 --cli이나 --tui를 실행할 때는 --no-healthcheck를 추가해 주어야 합니다. 아래에 있는 <target>는 의 임시 목표로, 위치 기반의 stdio 명령어이거나 --server-url <url> --transport http입니다.

docker run --rm --no-healthcheck ghcr.io/modelcontextprotocol/inspector --cli <target> --method tools/list

네트워크상에서 호스팅하기​

Inspector는 기본적으로 localhost을 바인딩하며 그 백엔드에서 프로세스를 생성하므로, 이를 네트워크에 노출시키는 것은 신중한 결정이 필요합니다.

DANGEROUSLY_BIND_ALL_INTERFACES=true을 설정하지 않으면 인스펙터는 와일드카드 형태의 모든 인터페이스 주소(0.0.0.0, :: 및 이와 동일한 다른 표기법들)를 바인딩하는 것을 거부합니다. 반면 특정 주소의 바인딩은 별도의 동의 절차 없이도 허용됩니다. 이는 모든 인터페이스를 한꺼번에 노출하는 것이 아니라 의도적으로 단일 인터페이스만 노출하기 때문이며, DNS 리바인딩 공격이 주로 노리는 형태이기도 합니다.

목표해야 할 일
LAN의 다른 장치에서 접근HOST=192.168.1.50을 사용합니다. 기본 오리진 허용 목록은 바인딩 호스트를 따르므로 별도 설정 없이 http://192.168.1.50:6274가 허용됩니다.
TLS 또는 리버스 프록시 뒤에서 접근브라우저의 Origin이 공개 오리진이 되어 바인딩 호스트와 일치하지 않습니다. ALLOWED_ORIGINS=https://inspector.example.com을 설정하세요.
와일드카드 바인딩(컨테이너)DANGEROUSLY_BIND_ALL_INTERFACES=true를 설정합니다. 루프백 접근은 기본으로 동작하지만, 비루프백 주소에서 접근하려면 ALLOWED_ORIGINS가 필요합니다.

루프백을 사용하지 않을 때 주의해야 할 두 가지 사항이 더 있습니다.

  • MCP 앱의 샌드박스 포트에도 접근할 수 있어야 합니다. 이 포트는 별도이며 기본적으로 동적으로 할당됩니다. MCP_SANDBOX_PORT로 고정한 뒤 외부에 노출하거나 포워딩하세요. Docker 이미지는 6274만 공개합니다.
  • MCP 앱들은 TLS를 통해 렌더링되거나 순수 IPv6 주소로 접근할 수 없습니다. 샌드박스 URL은 항상 일반적인 http 형태를 가지므로, https:// 페이지는 혼합 콘텐츠로 인해 iframe을 차단합니다. 또한 괄호로 둘러싼 IPv6 주소는 유효한 CSP 호스트 소스가 아니므로 이름이나 IPv4 주소를 사용하여 접속해야 합니다.

형태와 상관없이 항상 인증을 유지해야 합니다. 귀하 외에 누구나 접근할 수 있는 리소스에는 DANGEROUSLY_OMIT_AUTH을 설정해서는 안 됩니다.

개발 워크플로우​

실제 운영에서 효과적으로 작동하는 반복 절차입니다:

CLI를 통해 시작합니다

--method initialize는 서버가 시작되고 핸드셰이크가 이루어지는 것을 확인한 후, 기대하는 기능들에 대한 기계가 읽을 수 있는 형태의 답변을 1초 이내에 제공합니다. "작동하지 않는다"는 문제의 대부분이 바로이 부분에서 발생합니다. "작동하지 않는다"는 문제의 대부분이 바로 여기에서 비롯됩니다.

탐색을 위해 웹 클라이언트로 이동하십시오

스키마 기반의 양식, 표시되는 결과, 그리고 그 옆에 위치한 프로토콜 탭 덕분에 도구가 잘못 동작하는 경우를 빠르게 찾아낼 수 있습니다.

한계 상황을 테스트하십시오

무효한 입력, 필수적인 프롬프트 인자의 누락, 동시에 발생하는 호출 등이 그 예입니다. HTTP 서버의 경우에는 두 가지 프로토콜 버전 모두를 대상으로 하며, 오류가 성공 사례만큼이나 의도된 대로 표시되는지를 확인해야 합니다.

CLI를 사용하여 그 결과를 확정하십시오

검색 결과를 CI 어서션으로 변환하려면 CLI의 --format json를 트랜스포트로 사용하여 출력합니다. --stored-auth-only를 활용해 jq -e로 출력함으로써, 특정 토큰이 누락될 경우 즉시 오류가 발생하도록 합니다. 대화형 OAuth를 시작하는 대신, [서버 인증하기]를 참조하십시오. 전체 내용에 대한 CI입니다. 명령어입니다.