권한 부여

원격 MCP 서버에는 일반적으로 권한 부여가 필요합니다. Inspector는 세 가지 클라이언트 모두에서 전체 권한 부여 흐름을 구현합니다. 한 번의 로그인으로 얻은 토큰을 디스크에 공유하므로 모든 클라이언트에서 사용할 수 있습니다.

전체 흐름

연결 후 거부 응답 받기

Inspector가 서버 URL에 연결합니다. 서버는 401로 응답합니다. 응답에 WWW-Authenticate 헤더가 포함되어 있으면 보호된 리소스의 메타데이터 URL(resource_metadata)과 선택적으로 요청에 필요한 범위를 가리킵니다.

권한 부여 서버 검색하기

Inspector는 서버의 보호된 리소스 및 권한 부여 서버 메타데이터를 가져와 엔드포인트와 지원되는 권한 부여 방식을 확인합니다.

클라이언트 등록 또는 식별하기

Inspector는 구성된 메커니즘을 통해 권한 부여 서버에 자신을 식별합니다. 사용할 수 있는 메커니즘은 동적 클라이언트 등록, 사전 등록된 정적 클라이언트(--client-id / --client-secret), 클라이언트 ID 메타데이터 문서 (--client-metadata-url), 또는 기업 관리형 IdP입니다.

브라우저에서 권한 부여하기

Inspector가 권한 부여 URL을 엽니다. 사용자는 로그인하고 권한 부여에 동의합니다.

콜백 받기

권한 부여 서버가 권한 부여 코드를 담아 Inspector의 콜백 URL로 리디렉션합니다.

토큰 교환 및 재시도하기

코드를 토큰으로 교환하고 토큰을 저장한 다음, 원래 연결을 자동으로 다시 시도합니다. 세션 중간 챌린지인 경우에는 거부된 요청을 다시 시도합니다.

OAuth 흐름 완료 후의 연결 정보: 권한 부여 상태, 동적으로 등록된 클라이언트, 부여된 범위가 표시됩니다.

콜백 URL

웹 앱은 자체 URL에서 OAuth 콜백을 수신하지만, CLI와 TUI는 웹 앱과 별도인 두 번째 URL을 의도적으로 공유합니다.

환경	기본 콜백	이유
웹	http://localhost:6274/oauth/callback	기본 앱 서버가 이미 HTTP 리스너를 실행하고 있습니다.
CLI	http://127.0.0.1:6276/oauth/callback	실행 중인 웹 Inspector와 충돌하지 않도록 전용 루프백 리스너를 사용합니다.
TUI	http://127.0.0.1:6276/oauth/callback	CLI와 동일한 리스너를 사용합니다.

CLI 또는 TUI를 사용하기 전에 리디렉션 URI 사전 등록을 요구하는 IdP에 http://127.0.0.1:6276/oauth/callback을 등록하세요. 예측 가능한 기본값을 사용하는 이유는 한 번 등록한 뒤 계속 재사용할 수 있게 하기 위해서입니다.

--callback-url 또는 MCP_OAUTH_CALLBACK_URL로 기본값을 재정의할 수 있습니다.

콜백 URL은 localhost, 127.0.0.0/8, [::1] 중 하나인 루프백 호스트에 바인딩되어야 합니다. 리스너는 평문 http로 권한 부여 코드를 받으므로 루프백이 아닌 호스트는 오류와 함께 거부되며, 이를 우회하는 플래그는 없습니다. 브라우저가 다른 컴퓨터에서 실행된다면 해당 컴퓨터로 콜백 포트를 전달하세요. 아래에서 설명하는 --print-handoff는 바로 사용할 수 있는 portForwardCmd를 출력합니다.

리디렉션 URI는 등록된 값과 정확히 일치해야 합니다. http://localhost:6276/...와 http://127.0.0.1:6276/...는 같은 리스너에 도달하더라도 권한 부여 서버에는 서로 다른 URI입니다.

기본 포트는 한 번에 하나의 프로세스만 사용할 수 있습니다. 두 번째 흐름을 동시에 실행하면 EADDRINUSE 오류가 발생합니다. 인스턴스마다 서로 다른 고정 포트를 사용하거나, 권한 부여 서버가 동적 리디렉션 URI 등록을 지원한다면 http://127.0.0.1:0/oauth/callback을 사용해 운영 체제가 임시 포트를 할당하도록 하세요.

자격 증명 저장 위치

파일	내용
~/.mcp-inspector/storage/oauth.json	정규화된 서버 URL을 키로 사용하는 토큰 및 클라이언트 정보입니다. 파일 소유자만 접근할 수 있도록 기록됩니다.
~/.mcp-inspector/storage/client.json	설치 단위 클라이언트 설정(클라이언트 메타데이터 URL, 기업 IdP)입니다. 웹 클라이언트의 클라이언트 설정 대화 상자가 기록하는 파일과 같습니다.
카탈로그 파일에 있는 서버의 oauth 블록	서버별 클라이언트 ID/비밀 값, 범위, 기업 관리형 플래그 및 권한 상향 정책입니다.

oauth.json의 경로는 MCP_INSPECTOR_OAUTH_STATE_PATH, <MCP_STORAGE_DIR>/oauth.json(환경 변수 참조), 위의 기본 경로 순으로 결정됩니다. 세 클라이언트 모두 같은 방식으로 경로를 결정합니다. 명령줄의 --client-id / --client-secret / --client-metadata-url은 client.json 설정을 재정의합니다.

세션 중간 재권한 부여

서버는 세션 중간에 401 또는 403 insufficient_scope로 단일 요청을 거부할 수 있습니다. Inspector는 연결을 끊지 않고 두 경우를 모두 처리합니다.

• 재권한 부여: 토큰이 만료되었거나 취소된 경우입니다. Inspector는 WWW-Authenticate 챌린지를 해석해 권한 부여 흐름을 다시 실행한 뒤 실패한 요청을 재시도합니다.
• 권한 상향: 요청에 현재 토큰이 보유하지 않은 범위가 필요한 경우입니다. Inspector는 기존 범위와 새로 필요한 범위의 합집합에 대해 권한을 다시 부여합니다. 따라서 새 토큰은 기존 토큰이 제공하던 모든 권한에 새로 필요한 범위까지 포함합니다.

웹 클라이언트에서는 재권한 부여 배너가 표시됩니다. CLI에서는 stderr에 다음 메시지가 표시됩니다.

Proceed with step-up authorization? [y/N]

계속하려면 y로 답하세요. 입력이 줄 바꿈으로 끝나거나 stdin이 닫힌다면 파이프 입력(echo y | ...)도 작동합니다. N 또는 응답 없는 EOF는 거부로 처리됩니다. TTY가 아닌 stdin에서 5초 동안 아무 입력도 보내지 않으면 명시적 거부와 구분되는 auth_required 오류가 발생합니다. 기업 관리형 권한 상향은 프롬프트 없이 자동으로 새 토큰을 발급합니다.

비대화형 및 CI 실행

대화형 OAuth를 사용하려면 stdin 또는 stderr가 TTY이거나 MCP_AUTO_OPEN_ENABLED=true여야 합니다. 2>&1 | tee처럼 stderr를 파이프로 리디렉션해도 stdin이 TTY로 유지되므로 작동합니다. 일반적인 CI 환경처럼 두 조건을 모두 충족하지 못하면, 아무도 완료하지 않을 콜백을 최대 15분 동안 기다리는 대신 CLI가 auth_required 오류와 함께 즉시 종료됩니다.

CI에서는 다음과 같이 명시적으로 실행하세요.

mcp-inspector --cli "$URL" --transport http --stored-auth-only --method tools/list

--stored-auth-only는 대화형 OAuth나 권한 상향을 시작하지 않고 브라우저도 열지 않습니다. 공유 저장소에 토큰이 있으면 사용하고, 없으면 즉시 실패합니다.

웹 클라이언트에서 CLI로 넘기기

일반적인 사용 사례는 이 컴퓨터의 웹 Inspector에서 사용자가 OAuth를 완료한 후 스크립트에서 해당 토큰을 사용하려는 경우입니다.

플래그	동작
--use-stored-auth	--server-url에 저장된 인증 정보를 읽어 Authorization: Bearer를 삽입합니다. 갱신 토큰이 저장되어 있으면 먼저 갱신 권한 부여를 실행하고 새 토큰을 삽입한 뒤 변경된 토큰을 저장합니다. 일치하는 항목이 없으면 저장된 서버 URL을 나열하고 종료 코드 3으로 종료합니다.
--wait-for-auth <sec>	--server-url의 토큰이 나타날 때까지 상태 파일을 폴링한 후 토큰을 삽입합니다. <sec>초 후 종료 코드 3으로 시간 초과됩니다. 사용자에게 로그인을 넘긴 뒤 사용하세요.
--list-stored-auth	{ oauthStatePath, storedServerUrls }를 출력한 후 연결하지 않고 종료합니다.
--print-handoff	--server-url에 대한 JSON 블록(deepLink, portForwardCmd, oauthStatePath, apiToken)을 출력한 후 종료합니다. 원격 스크립트가 브라우저 측 흐름을 제어하는 데 필요한 모든 정보입니다.
--relogin	연결하기 전에 이 서버 URL에 저장된 OAuth 정보를 삭제합니다. HTTP/SSE에서만 사용할 수 있습니다.

일반적인 원격 VM 실행 순서는 다음과 같습니다.

# On the VM: print what the human needs in order to complete OAuth in their browser
mcp-inspector --cli --server-url https://api.example/mcp --print-handoff

# Then block until the token lands, and run the call with it
mcp-inspector --cli --transport http --server-url https://api.example/mcp \
  --wait-for-auth 120 --method tools/list

핸드오프 블록의 deepLink는 브라우저를 연결된 Inspector로 바로 이동시킵니다. 자세한 내용은 딥 링크를 참조하세요.

저장된 항목에는 만료 시각이 기록되지 않으므로 저장된 갱신 토큰은 모든 --use-stored-auth 실행에서 사용됩니다. 회전식(일회용) 갱신 토큰에서는 두 가지 좁은 실패 가능 구간이 생깁니다. 동일한 상태 파일을 사용하는 두 호출이 토큰을 두고 경합할 수 있고, 갱신 성공 후 저장하기 전에 프로세스가 중단되면 회전된 토큰이 저장되지 않습니다. 두 경우 모두 발생 가능성은 낮으며, 문제가 생기면 웹 클라이언트에서 권한을 다시 부여해 복구할 수 있습니다.

권한 부여 상태 확인

• 웹: 연결 정보 패널에 검색 결과, 등록된 클라이언트, 부여된 범위 및 토큰 상태가 표시됩니다. 활성 서버의 OAuth 상태 지우기 기능도 제공합니다.
• TUI: Auth 탭(a)에 같은 필드가 표시되며 같은 방식으로 상태를 지울 수 있습니다.
• CLI: --list-stored-auth는 디스크에 저장된 정보를 표시하고, --relogin은 해당 정보를 삭제한 뒤 처음부터 다시 시작합니다.