CLI 클라이언트

각 CLI 실행은 서버에 연결된 후 --method으로 지정된 단일 요청을 전송하여 결과를 출력한 뒤 종료됩니다. 이러한 특성 덕분에 서버의 변경 사항을 즉시 확인해야 하는 CI 파이프라인, 셸 원-라이너, 코딩 에이전트에 매우 적합합니다.

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

아래 예제들은 설치된 mcp-inspector 바이너리를 사용합니다. 전역에 설치되어 있지 않은 경우에는 위와 같이 각 명령어 앞에 npx @modelcontextprotocol/inspector를 붙여 사용해야 합니다.

서버 선택

CLI는 인자형 명령어(stdio), --server-url(HTTP/SSE), 또는 카탈로그나 설정 파일에 명시된 서버 중 하나를 받아들일 수 있습니다.

# stdio: everything positional is the command to spawn
mcp-inspector --cli node build/index.js --method tools/list

# HTTP
mcp-inspector --cli https://api.example.com/mcp --transport http --method tools/list

# From a file
mcp-inspector --cli --config ./mcp.json --server myserver --method tools/list

서버 정보가 파일에서 가져오는 경우, 해당 서버에 대한 설정(헤더, 타임아웃, OAuth, protocol era, 그리고 roots)은 TUI나 웹 클라이언트가 설정을 해결하는 방식과 동일하게 연결에 적용됩니다. --header 플래그는 해당 실행 시 파일의 헤더 값을 재정의하지만 타임아웃과 OAuth 설정은 그대로 유지합니다.

이후의 예제들에서는 사용자가 선택하는 이러한 형태들과 그에 따른 --transport 또는 --config/--server 플래그들을 <server>으로 간략히 표기합니다.

설정 파일은 실행에 필요한 정보를 지속적으로 제공할 수 있는 유일한 방법입니다. roots:** roots에 해당하는 플래그는 존재하지 않으며, --method roots/set는 해당 단일한 일시적인 연결에만 적용됩니다. 서버에 대해 설정된 roots 정보는 연결 시 공개되므로, 서버가 호출할 때이 정보를 받을 수 있습니다. roots/list(@modelcontextprotocol/server-filesystem와 마찬가지로 자신의 정보를 확인하기 위해 사용됨)를 통해, 허용된 디렉터리 목록을 가져올 수 있습니다.

--catalog와 --config의 차이점, -- 구분 기호, 그리고 공통적으로 사용되는 서버 선택 플래그들에 대한 내용은 Configuration and flags를 참조하십시오.

메서드

--method	반드시 함께 사용해야 하는 옵션	비고
initialize	없음	단순 연결 확인용 프로브: {serverInfo, protocolVersion, capabilities, instructions}.
tools/list	없음
tools/call	--tool-name 및 --tool-arg / --tool-args-json
resources/list	없음
resources/read	--uri
resources/templates/list	없음
prompts/list	없음
prompts/get	--prompt-name, --prompt-args
logging/setLevel	--log-level	레거시 에라에서만 사용합니다. 현대 서버는 요청별로 로그 수신을 선택합니다.
servers/list, servers/show	없음	서버에 연결하지 않고 카탈로그를 읽습니다.

스트림 전용이거나 세션 전용인 메서드(예: logging/tail)는 종료된 프로세스가 스트림을 계속 열어둘 수 없기 때문에 거부됩니다.

인자 전달

--tool-arg는 key=value 형식의 인자를 받아 JSON 파싱을 통해 값들을 변환하므로, count=1는 숫자로, "012"는 12 형태로 변환됩니다.

mcp-inspector --cli <server> --method tools/call --tool-name mytool \
  --tool-arg key=value --tool-arg count=1 --tool-arg 'options={"format":"json"}'

--tool-args-json는 인자 객체 전체를 그대로 받아 변환 없이 원문 그대로 전달하므로, "012"는 문자열 012의 형태를 그대로 유지합니다. 이 두 방식은 서로 상충합니다.

mcp-inspector --cli <server> --method tools/call --tool-name mytool \
  --tool-args-json '{"zip":"10001"}'

출력

--format text(기본값)는 인간이 읽기 쉽도록 결과를 꾸며서 표시합니다. 반면 --format json는 어떠한 메시지도 표시하지 않고 stdout에 단일 JSON 객체만을 출력하므로 전체 출력 결과가 깔끔하게 연결됩니다.

mcp-inspector --cli <server> --method tools/list --format json | jq '.result.tools[].name'

MCP 앱 확인

--app-info는 도구를 호출하지 않고도 해당 도구가 MCP App UI(그 리소스인 ui://, CSP, 권한 설정 등)를 제공하는지 여부를 보고하므로, 파이프라인은 어떤 작업을 실행하기 전에 브라우저가 필요한지 판단할 수 있습니다.

# One tool -> one JSON line
mcp-inspector --cli <server> --method tools/call --tool-name my_tool --app-info
# {"hasApp":true,"toolName":"my_tool","resourceUri":"ui://...","csp":{...},"permissions":{...}}

# Every tool -> NDJSON, one line each, over a single connection
mcp-inspector --cli <server> --method tools/list --app-info | jq -c 'select(.hasApp)'

종료 코드는 각각의 결과를 구분해 줍니다. 앱이 포함된 도구는 0로 종료하고, 앱이 없는 도구는 2로 종료하며, 도구 자체가 존재하지 않는 경우에는 5로 종료하므로 오타가 "앱이 없음"으로 오해되는 일이 없습니다. 또한 UI 리소스를 읽을 수 없거나 형식이 잘못된 resourceUri와 같은 프로브 실패는 프로그램 실행을 중단시키는 대신 resourceError 필드에 해당 정보가 기록되므로, 단 하나의 오류 있는 도구로 인해 전체 목록의 처리가 중단되는 일이 없습니다.

tools/list --app-info는 상황과 관계없이 항상 NDJSON 형식으로 데이터를 출력하며, 각 도구에 대해 한 줄씩 표시됩니다. --format; --format json는 단일 도구에 대한 출력 형태만 변경해 줍니다. tools/call --app-info.

종료 코드와 오류 정보

0이 아닌 모든 종료 코드는 특정한 실패 유형에 해당하므로, 호출자는 복잡한 텍스트를 분석하지 않고도 실패 원인에 따라 적절한 처리를 수행할 수 있습니다.

코드	의미
0	성공
1	사용법 오류 또는 예기치 않은 오류(포괄적 오류)
2	도구에서 MCP 앱을 찾지 못함(--app-info 프로브)
3	서버에 인증이 필요함(401/403, WWW-Authenticate, OAuth)
4	서버에 연결할 수 없음(DNS, 연결 거부, 시간 초과, fetch failed)
5	도구 오류: tools/call이 isError: true를 반환했거나 도구를 찾지 못함

0이 아닌 종료 코드가 발생할 경우 CLI는 stderr에 단일 JSON 줄을 기록하기도 합니다.

{
  "error": {
    "code": "auth_required",
    "message": "Unauthorized",
    "status": 401,
    "url": "https://api.example/mcp"
  }
}

이 데이터가 한 줄로 구성되어 있으므로, 호출자는 2>&1 | tail -1 | jq .error을 사용하여 쉽게 파싱할 수 있습니다.

tools/call가 isError: true 값을 반환하더라도 해당 데이터는 출력되지만 종료 코드는 5가 되므로, && 연산자를 사용한 연쇄 처리는 실패한 호출에서는 계속 진행되지 않습니다.

스크립트 내의 권한 부여

기본적으로 CLI는 TUI와 동일한 로컬호스트 기반의 OAuth 흐름을 사용합니다. 즉, 브라우저를 열어 로컬호스트의 콜백을 기다리는 방식인데, 이는 CI 작업에서는 완료할 수 없는 방식입니다. 비대화형 실행 환경에서 일관된 동작을 보장하기 위해 두 가지 플래그가 제공됩니다.

• --stored-auth-only: 대화형 OAuth나 단계적 권한 부여 과정을 절대 시작하지 않으며, 브라우저도 자동으로 열지 않습니다. 공유 저장소에 토큰이 존재할 경우 이를 사용하고, 그렇지 않을 경우 즉시 auth_required 오류와 함께 실패합니다. 이것이 바로 CI에서 원하는 플래그입니다.
• --use-stored-auth: 해당 컴퓨터의 웹 인스펙터가 이미 획득한 토큰을 재사용하며, 갱신 토큰이 저장되어 있을 경우 먼저 해당 토큰을 갱신한 후 사용합니다.

이 두 플래그 중 어느 것도 사용되지 않고 stdin 또는 stderr에 TTY도 없는 경우, CLI는 아무도 완료할 수 없는 콜백을 기다리며 15분간 대기하는 대신 즉시 auth_required 오류와 함께 실패합니다.

전체 흐름, 웹과 CLI 간의 데이터 전달 과정, 그리고 --print-handoff에 대한 자세한 내용은 Authorization 문서를 참조하십시오.

활용 예시

CI 환경에서 서버를 검증하는 방법

set -euo pipefail

# Fail the build if the server can't be reached or doesn't expose the tool
mcp-inspector --cli --config ./ci-servers.json --server my-server \
  --stored-auth-only --method tools/list --format json \
  | jq -e '.result.tools | map(.name) | index("get_weather")' > /dev/null

실패 유형에 따라 브랜치를 생성하는 방법

if out=$(mcp-inspector --cli "$URL" --transport http --method tools/list 2>err.json); then
  echo "$out"
else
  case $? in
    3) echo "needs auth: run the web inspector once to sign in" ;;
    4) echo "server unreachable" ;;
    *) jq .error < err.json ;;
  esac
fi

UI가 있는 모든 도구 스모크 테스트

mcp-inspector --cli "$URL" --transport http --method tools/list --app-info \
  | jq -r 'select(.hasApp) | .toolName'

연결하지 않고 카탈로그 검사

mcp-inspector --cli --catalog ~/.mcp-inspector/mcp.json --method servers/list
mcp-inspector --cli --catalog ~/.mcp-inspector/mcp.json --method servers/show --server my-server

servers/show은 비밀 정보가 포함된 필드(env 값, 민감한 헤더 등)를 가리워줍니다. OAuth 클라이언트 시크릿도 마찬가지이지만, 리소스에 내장된 자격 증명은 제거해주지 않습니다. 서버 url(userinfo 또는 query 토큰)를 통해 전달되거나 stdio args를 통해 전달됩니다. 원시 URL과 detail 필드들은 이슈에 복사하기 전에 민감한 정보로 취급되어야 합니다.

프록시

원격 HTTP/SSE 서버에 대한 연결은 일반적인 프록시 변수들을 준수합니다. HTTPS_PROXY / HTTP_PROXY(그리고 그 소문자 형태들)는 프록시를 지정하며, NO_PROXY은 특정 호스트를 프록시 적용 대상에서 제외시킵니다. Inspector에만 해당하는 특별한 플래그는 필요하지 않으며, 프록시 에이전트는 필요할 때만 로드되므로 프록시를 사용하지 않아도 추가 비용이 발생하지 않습니다. 웹 클라이언트의 백엔드에도 동일한 원칙이 적용됩니다.