요약: Claude Code 6월 하순 업데이트에는 MCP 인증 관련 개선이 여러 개 들어갔습니다. claude mcp login/logout, headless 환경의 브라우저 없는 인증, MCP OAuth 재시도, headersHelper 401/403 자동 재연결, 인증이 필요한 MCP 서버에 대한 startup notice가 대표적입니다. MCP 서버를 한두 개 붙여 보는 단계라면 작게 보일 수 있지만, 팀에서 검색·이슈·배포·문서 도구를 MCP로 연결했다면 인증 운영 기준을 새로 잡아야 합니다.
MCP를 붙인 에이전트가 실패하면 사용자는 보통 “모델이 못 한다”고 느낍니다. 하지만 실제 원인은 토큰 만료, OAuth 브라우저 팝업 실패, SSH/headless 환경에서 callback을 못 받는 문제, headers helper가 stale credential을 계속 쓰는 문제인 경우가 많습니다. 특히 원격 서버, tmux, CI-like runner, container workspace에서는 브라우저를 열 수 없거나 열어도 사람이 접근하기 어렵습니다.
최근 Claude Code 릴리스는 이 영역을 집중적으로 손봤습니다. 6월 22일에는 claude mcp login과 claude mcp logout이 추가되어 interactive /mcp 메뉴를 열지 않고 CLI에서 MCP 서버 인증을 처리할 수 있게 됐습니다. --no-browser와 stdin redirect를 통해 SSH 환경에서도 인증 URL을 복사해 완료하는 흐름을 지원합니다. 6월 24일에는 MCP OAuth discovery와 token request가 transient network error 후 한 번 재시도하도록 개선됐고, headless 환경에서는 브라우저 팝업 대신 URL 붙여넣기 프롬프트로 바로 넘어갑니다. 6월 25일에는 headersHelper auth가 tool call에서 401/403을 받으면 helper를 다시 실행하고 재연결하도록 개선됐습니다.
이제 팀 문서에서 “Claude Code를 열고 /mcp 메뉴에서 알아서 로그인”이라고 쓰는 방식은 부족합니다. 로컬 GUI 환경에서는 가능하지만 원격 SSH, tmux, dev container에서는 재현성이 떨어집니다. 대신 서버별 인증 명령을 문서화하세요.
예시는 단순합니다. “GitHub MCP 인증: claude mcp login github”, “사내 검색 MCP 인증: claude mcp login internal-search --no-browser”처럼 적습니다. 실제 서버 이름은 팀 설정에 맞춰야 합니다. 로그아웃도 중요합니다. 권한이 바뀌었거나 장비를 반납하거나 토큰이 꼬였을 때 claude mcp logout을 실행하는 절차를 둬야 합니다.
headless 환경에서는 URL 복사 흐름을 전제로 해야 합니다. 브라우저가 뜨지 않는다고 실패 처리하지 말고, 인증 URL을 로컬 브라우저에서 열어 코드를 붙여넣는 절차를 써야 합니다. 이 흐름을 문서화하면 원격 개발 장비에서도 MCP 온보딩이 훨씬 빨라집니다.
MCP OAuth는 네트워크 상태에 민감합니다. discovery endpoint가 잠깐 실패하거나 token request가 timeout되면 인증이 실패한 것처럼 보일 수 있습니다. 6월 24일 개선은 이런 transient network error에 대해 discovery와 token request를 한 번 재시도합니다. 이것만으로도 “처음엔 실패했는데 다시 하니 됨” 같은 노이즈가 줄어듭니다.
headersHelper 개선은 더 중요합니다. 일부 MCP 서버는 매 요청마다 helper를 통해 header를 만들거나 토큰을 주입합니다. 이 helper가 만료된 토큰을 계속 반환하면 tool call은 401 또는 403을 냅니다. 이전에는 사용자가 직접 재로그인하거나 세션을 재시작해야 했을 수 있습니다. 이제 tool call이 401/403을 받으면 helper가 다시 실행되고 reconnect가 자동으로 진행됩니다.
하지만 자동 복구가 있다고 해서 운영자가 손을 놓으면 안 됩니다. 자동 재연결이 반복된다면 토큰 TTL, refresh 권한, helper 스크립트의 cache 위치, clock skew, proxy 인증 문제를 봐야 합니다. 자동 복구는 사용자 경험을 부드럽게 만들 뿐, 근본 원인을 숨기면 안 됩니다.
6월 25일 릴리스에는 MCP servers need authentication 상태를 startup notice로 보여주고 /mcp를 안내하는 개선도 있습니다. 이건 작은 UX 개선처럼 보이지만 팀 운영에는 큽니다. 에이전트가 작업 중간에 tool call을 시도한 뒤 인증이 안 되어 실패하는 것보다, 시작 시점에 “이 MCP는 인증이 필요하다”고 알려주는 편이 훨씬 낫습니다.
팀에서는 이 startup notice를 온보딩 체크포인트로 쓰면 됩니다. 새 개발자가 Claude Code를 열었을 때 인증 필요한 MCP 목록이 보이면, 작업을 시작하기 전에 login을 완료하게 합니다. 특히 이슈 트래커, 문서 검색, 코드 검색, cloud inventory 같은 도구는 작업 도중에 실패하면 맥락이 끊깁니다.
또한 인증이 필요 없는 MCP와 필요한 MCP를 나누세요. 공개 문서 검색이나 로컬 파일 인덱스는 인증이 없을 수 있습니다. 반면 GitHub, Linear, Jira, 사내 wiki, cloud resource MCP는 권한이 필요합니다. 이 차이를 settings와 README에 명확히 적어 두면 “왜 내 Claude만 도구를 못 쓰지?”라는 질문이 줄어듭니다.
MCP tool call이 실패하면 먼저 에러를 분류합니다. 401은 인증이 없거나 만료된 경우가 많고, 403은 인증은 됐지만 권한이 부족한 경우가 많습니다. 404는 서버 URL 또는 tool path가 틀렸을 가능성이 큽니다. 5xx와 timeout은 서버 또는 네트워크 문제입니다.
401/403이면 바로 토큰을 새로 발급하기보다 Claude Code가 helper 재실행과 reconnect를 시도했는지 로그를 봅니다. 반복 실패한다면 claude mcp logout 후 claude mcp login으로 새로 연결합니다. headless 환경에서는 --no-browser를 사용합니다. 그래도 403이면 사용자 권한, 조직 policy, OAuth scope, MCP 서버 allowlist를 확인합니다.
404나 URL 관련 오류라면 최근 릴리스에서 MCP HTTP 404 에러가 URL과 MCP config 힌트를 보여주도록 개선된 점을 활용하세요. 에러 메시지에 나온 URL을 settings와 비교하고, proxy나 base path가 바뀌었는지 확인합니다.
MCP 인증은 생산성 문제가 아니라 권한 위임 문제입니다. Claude Code가 MCP를 통해 접근하는 범위는 사용자의 계정 권한과 연결됩니다. 따라서 “로그인만 되면 끝”이 아닙니다. 최소 권한 scope를 쓰고, 개인 토큰보다 OAuth 또는 short-lived credential을 선호하고, 사내 MCP는 서버 측 audit log를 남기는 편이 좋습니다.
특히 배포, 결제, 고객 데이터, production DB와 연결되는 MCP는 별도 approval gate를 둬야 합니다. 인증이 되어 있다고 해서 에이전트가 자유롭게 mutation을 실행하면 안 됩니다. 읽기 전용 MCP와 쓰기 가능한 MCP를 분리하고, tool 이름에서도 위험도가 드러나게 하는 것이 좋습니다.
claude mcp login / claude mcp logout 절차를 README에 적습니다.--no-browser 인증 흐름을 기본 문서에 포함합니다.MCP는 에이전트의 팔과 다리입니다. 팔과 다리가 자주 빠지면 모델 두뇌가 좋아도 업무가 끊깁니다. 이번 Claude Code 업데이트를 계기로 MCP 인증을 “개인이 알아서 로그인”에서 “팀이 재현 가능하게 운영하는 절차”로 올려두는 것이 좋습니다.