레시피

레시피 (Recipes)

전송, 구성 가져오기, MCP Apps 검토, Docker, 네트워크 호스팅을 위한 실용 가이드예요.

출처: 문서

본문

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 탭(web)이나 Console 탭(o, TUI)에 들어갑니다. 대부분의 stdio 서버가 진단을 거기에 두므로, 보이는 이유 없이 연결이 실패하면 먼저 거기를 확인하세요.

HTTP와 SSE

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

--transport는 http(Streamable HTTP)와 sse를 받아요. 서버가 보호되어 있으면 인증을 참고하세요. 사전 설정은 필요 없어요. 서버가 401로 답하면 Inspector가 거기에 설명된 OAuth 흐름을 실행하고 연결을 재시도하기 때문입니다.

HTTP 서버라면 프로토콜 시대도 결정하세요. 기본은 legacy이고, Server Settings(또는 카탈로그 파일의 protocolEra)에서 modern이나 auto를 설정해 2026-07-28 동작을 검증하세요.

기존 클라이언트 구성 가져오기

Servers 화면에서 Add Servers는 이미 다른 곳에 구성한 MCP 서버를 다시 입력하지 않고 가져올 수 있어요. Claude Desktop, Cursor, Cline, VS Code 클라이언트 구성을 직접 파싱하고, 서버 자신의 MCP Registry server.json도 읽습니다.

가져오기는 활성 카탈로그(Inspector의 쓰기 가능한 서버 목록)에 병합되므로 기존 항목을 덮어쓰지 않아요. 카탈로그를 전혀 건드리지 않으려면, 대신 외부 파일을 읽기 전용으로 상대로 실행하세요.

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

--config는 파일이 있는 그대로 제공되고 절대 쓰이지 않으며 시드되거나 마이그레이션되지 않음을 보장해요.

MCP App 검토

MCP Apps는 UI 위젯을 지닌 도구예요. 자동 검토자(CI나 에이전트)는 JSON을 반환하는 모든 검사에 CLI를 사용하고, 렌더링된 위젯을 검사할 때만 브라우저를 열어야 해요.

1단계: 도구를 호출하지 않고 보안 자세 프로브

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

stdout에 단일 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가 그 리소스를 읽어요. 도구는 결코 호출되지 않습니다.

2단계: 여전히 브라우저 없이 전체 결과 페이로드 얻기

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

3단계: Web Inspector를 한 번, 루프백 전용으로 실행

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는 기본적으로 동적인 별도 샌드박스 포트에서 서빙되며, 자동화가 도달하려면 고정 주소가 필요하죠.

4단계: 렌더링된 위젯으로 단일 딥 링크 이동

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

appArgs는 base64url 인코딩된 JSON의 도구 인수이고, 모든 딥 링크 매개변수는 Deep links에 설명돼 있어요. autoConnect와 autoOpen은 둘 다 세션 토큰과 같아야 해요. autoOpen이 URL에서 곧바로 도구 호출을 발사해 autoConnect와 같은 게이트가 필요하기 때문입니다.

5단계: 잠자기 대신 결정적 신호 대기

Apps 화면은 안정적인 자동화 계약을 노출해요. 잠자는 대신 다음 속성을 폴링하세요.

선택자	속성	값
`[data-testid="apps-form"]`	`data-app-status`	`ready`(실패 시 `data-app-error`가 이유를 담음)
`[data-testid="connection-status"]`	`data-status`	`connecting`, 그다음 `connected` 또는 `error`(`data-error-message`에 상세)
`[data-testid="connection-status"]`	`data-deeplink`	`parsed`, `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는 web 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

게시 포트를 다시 매핑하면 ALLOWED_ORIGINS를 설정하세요. -p 8080:6274에서는 브라우저의 오리진이 http://localhost:8080이 되어 컨테이너 내부 포트와 더 이상 일치하지 않고, 연결이 403이 돼요. -e CLIENT_PORT=8080 -p 8080:8080으로 실행하거나 -e ALLOWED_ORIGINS=http://localhost:8080,http://127.0.0.1:8080을 설정하세요.

네트워크에서 호스팅하기

Inspector는 기본적으로 localhost에 바인딩하고 그 백엔드가 프로세스를 실행하므로, 네트워크에 노출하는 것을 의도적 결정으로 취급하세요.

Inspector는 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` 필요.

ALLOWED_ORIGINS는 기본 목록과 병합하지 않고 교체해요. 탐색할 모든 오리진을 나열하세요. 유지하고 싶은 루프백 형태도 포함해서요.
ALLOWED_ORIGINS=http://localhost:6274,http://127.0.0.1:6274,http://192.168.1.50:6274
각 항목은 스킴을 포함해야 해요. 스킴 없는 값은 경고와 함께 버려집니다. 빈 값은 검사를 끄지 않으며 기본값으로 폴백돼요. 오리진 검증을 끄는 손잡이는 없습니다.

루프백을 벗어날 때 두 가지 추가 주의 사항이 있어요.

MCP Apps는 샌드박스 포트도 도달 가능해야 해요. 그것은 별도의 기본 동적 포트입니다. MCP_SANDBOX_PORT로 고정하고 노출하거나 포워딩하세요. Docker 이미지는 6274만 게시합니다.
MCP Apps는 TLS 위나 맨 IPv6 리터럴에서는 렌더링할 수 없어요. 샌드박스 URL은 항상 일반 http라서 https:// 페이지가 iframe을 혼합 콘텐츠로 차단하고, 대괄호 IPv6 리터럴은 유효한 CSP 호스트 소스가 아니므로 이름이나 IPv4 주소에서 탐색하세요.

어떤 형태든 인증은 켜두세요. 여러분 외의 누구든 도달할 수 있는 것에 DANGEROUSLY_OMIT_AUTH를 설정하지 마세요.

개발 워크플로

실제로 잘 작동하는 루프:

1단계: CLI로 시작

--method initialize는 서버가 시작되고, 핸드셰이크하며, 기대하는 기능을 보고하는지 1초 만에 기계 판독 가능한 답으로 확인해 줍니다. "작동 안 함"의 대부분이 사실 여기 있는 경우가 많아요.

2단계: 탐색은 web 클라이언트로

스키마 기반 폼, 렌더링된 결과, 옆에 있는 Protocol 탭이 도구가 잘못 동작하는 경우를 빨리 찾게 해 줍니다.

3단계: 경계 테스트

잘못된 입력, 누락된 필수 프롬프트 인수, 동시 호출, 그리고 HTTP 서버는 두 프로토콜 시대 모두를 테스트하세요. 오류가 성공만큼 의도적이도록 검증하세요.

4단계: CLI로 확정

발견한 것을 CI 단언으로 바꾸세요. CLI의 --format json 출력을 --stored-auth-only와 함께 jq -e로 파이프하면, 누락된 토큰이 상호작용 OAuth를 시작하는 대신 빠르게 실패합니다. 전체 명령은 CI에서 서버 검증을 참고하세요.

레시피