인증

인증 (Authorization)

MCP Inspector가 OAuth를 수행하고, 세션 중에 재인증하며, 클라이언트들 사이에 토큰을 공유하는 방법을 다루는 문서예요. 원격 MCP 서버는 보통 인증을 요구합니다.

출처: 문서

본문

원격 MCP 서버는 보통 인증을 요구해요. Inspector는 세 클라이언트 모두에서 완전한 인증 흐름을 구현하며, 결과 토큰을 디스크에 공유해서 한 번 로그인하면 어디서든 사용할 수 있게 합니다.

흐름, 처음부터 끝까지

1단계: 연결하고 거부받기

Inspector가 서버 URL에 연결합니다. 서버는 401로 답해요. 응답이 WWW-Authenticate 헤더를 지니면, 이는 보호 리소스 메타데이터 URL(resource_metadata)과 선택적으로 요청에 필요한 스코프를 가리킵니다.

2단계: 인증 서버 발견

Inspector는 서버의 보호 리소스 및 인증 서버 메타데이터를 가져와 엔드포인트와 지원되는 그랜트를 배웁니다.

3단계: 클라이언트 등록 또는 식별

Inspector는 구성된 메커니즘 중 하나로 인증 서버에 자신을 식별해요. 동적 클라이언트 등록, 사전 등록된 정적 클라이언트(--client-id/--client-secret), Client ID Metadata Document(--client-metadata-url), 또는 엔터프라이즈 관리 IdP 중 하나죠.

4단계: 브라우저에서 인증

Inspector가 인증 URL을 엽니다. 여러분이 로그인하고 동의합니다.

5단계: 콜백 수신

인증 서버가 인증 코드를 담아 Inspector의 콜백 URL로 리다이렉트해요.

6단계: 교환하고 재시도

코드가 토큰으로 교환되고, 토큰이 지속되며, 원래 연결(또는 세션 중 챌린지의 경우 거부된 요청)이 자동으로 재시도됩니다.

콜백 URL (Callback URLs)

Web 앱은 자신의 URL에서 OAuth 콜백을 듣는 반면, CLI와 TUI는 의도적으로 두 번째 콜백을 공유합니다.

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 등록을 지원할 때 OS가 할당하는 임시 포트용 http://127.0.0.1:0/oauth/callback을 사용하세요.

자격 증명이 사는 곳

oauth.json의 경로는 순서대로 해석됩니다. MCP_INSPECTOR_OAUTH_STATE_PATH, 그다음 <MCP_STORAGE_DIR>/oauth.json(환경 변수 참고), 마지막으로 위의 기본값. 세 클라이언트 모두 같은 방식으로 해석합니다. 명령줄의 --client-id/--client-secret/--client-metadata-url은 client.json을 덮어써요.

세션 중 재인증 (Mid-session re-authorization)

서버가 세션 중 단일 요청을 401 또는 403 insufficient_scope으로 거부할 수 있으며, Inspector는 연결을 끊지 않고 둘 다 처리해요.

• 재인증: 토큰이 만료됐거나 취소됨. Inspector가 WWW-Authenticate 챌린지를 파싱해 흐름을 다시 실행하고, 실패한 요청을 재시도해요.
• 스텝업(Step-up): 요청에 현재 토큰이 지니지 않는 스코프가 필요함. Inspector가 보유 스코프와 요구 스코프의 합집합으로 재인증해서, 새 토큰이 이전 토큰이 다뤘던 모든 것에 더해 새로 필요한 스코프까지 덮습니다.

web 클라이언트에서는 이것이 재인증 배너로 표면화되고, CLI에서는 stderr에 프롬프트가 나타나요.

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

y로 답하면 계속됩니다. 파이프 입력(echo y | ...)도, 줄바꿈으로 끝나거나 stdin이 닫히면 작동해요. N, 또는 답 없이 EOF는 거부합니다. 5초 안에 아무것도 보내지 않는 비-TTY stdin은 명시적 거부와 구별되는 auth_required로 실패해요. 엔터프라이즈 관리 스텝업은 프롬프트 없이 조용히 다시 발급합니다.

비상호작용 및 CI 실행

상호작용 OAuth는 stdin 또는 stderr에 TTY가 있어야 하거나, MCP_AUTO_OPEN_ENABLED=true가 필요해요. 2>&1 | tee처럼 stderr를 파이프로 리다이렉트해도 stdin이 TTY로 남아 있으므로 여전히 동작합니다. 둘 다 아닐 때(일반적인 CI 형태), CLI는 아무도 완료하지 않을 콜백을 최대 15분 기다리는 대신 auth_required로 빠르게 실패합니다.

CI에서는 명시적으로 하세요.

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

--stored-auth-only는 상호작용 OAuth나 스텝업을 시작하지 않고, 브라우저를 열지 않으며, 토큰이 있으면 공유 저장소를 쓰고, 그렇지 않으면 즉시 실패해요.

Web 클라이언트에서 CLI로 핸드오프

흔한 경우: 사람이 이 머신의 web Inspector에서 OAuth를 완료했고, 이제 스크립트가 그 토큰을 사용하려 해요.

전형적인 원격 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로 곧장 이동시켜요. Deep links를 참고하세요.

저장된 항목은 만료를 기록하지 않으므로, 저장된 리프레시 토큰은 모든 --use-stored-auth 실행에서 사용됩니다. 회전(일회용) 리프레시 토큰에서는 두 개의 좁은 실패 창이 열려요. 같은 상태 파일에 대한 동시 호출 두 개가 토큰을 놓고 경쟁할 수 있고, 성공적인 리프레시와 기록 사이의 크래시가 회전된 토큰을 저장하지 않은 채 둘 수 있습니다. 둘 다 드물어요. web 클라이언트에서 재인증해 복구하세요.

인증 상태 검사하기

• Web: Connection Info 패널이 발견 결과, 등록된 클라이언트, 부여된 스코프, 토큰 상태를 보여 주고, 활성 서버에 대해 Clear OAuth state를 제공해요.
• TUI: Auth 탭(a)이 같은 필드를 보여 주고 같은 방식으로 상태를 지웁니다.
• CLI: --list-stored-auth가 디스크에 있는 것을 보여 주고, --relogin은 버리고 다시 시작합니다.

더 알아보기 (Learn more)

• MCP Inspector
• CLI 클라이언트
• TUI 클라이언트
• 보안 모범 사례