Claude Code에서 MCP 서버 인증이 필요할 때 해결법

Claude Code에서 원격 MCP 서버가 "needs authentication"(인증 필요) 상태가 되는 것은, 서버가 401 Unauthorized나 403 Forbidden으로 응답했는데 Claude Code가 저장된 OAuth 토큰으로 이를 해결하지 못했을 때입니다. 로그인하면 해결됩니다. 세션에서 /mcp를 실행하고 브라우저 단계를 따르거나, 셸에서 claude mcp login <name>을 실행하세요. Sume 호스팅 MCP 서버라면 두 가지를 먼저 확인하세요. 로그인을 끝까지 마쳤는지, 그리고 액세스 토큰이 만료되지 않았는지입니다. 현재 코드에서 토큰은 한 시간 동안 유효하고 Sume는 리프레시 토큰을 발급하지 않습니다.

Claude Code 동작은 2026-09-27에 확인한 MCP 문서에서 가져왔으며, 버전에 따라 달라집니다. Sume 쪽 내용은 MCP 빠른 시작과 OAuth와 API 키에서, 토큰 수명은 현재 서버 코드에서 가져왔습니다. Sume 기초 페이지는 호스팅 MCP가 여전히 동작하지만 현재 주 연동 경로는 아니라고 설명합니다.

Claude Code는 왜 서버에 인증이 필요하다고 하나요?

상태 코드와 서버를 연결한 방식에 따라 다릅니다.

Sume 서버는 왜 계속 로그인하라고 하나요?

• 서버를 추가만 하고 로그인하지 않은 경우입니다. claude mcp add는 설정을 쓸 뿐이고, 로그인은 별도 단계입니다. 현재 코드에서 Sume는 토큰 없는 요청에 OAuth 메타데이터를 가리키는 401로 응답하므로, 빠른 시작의 두 번째 명령어인 claude mcp login sume을 실행하세요.
• 토큰이 만료된 경우입니다. 현재 코드에서 Sume MCP 액세스 토큰은 한 시간 동안 유효하고 토큰 응답에 리프레시 토큰이 없으므로, Claude Code가 먼저 시도하는 갱신은 성공할 수 없습니다. 만료되거나 폐기된 토큰은 토큰이 없을 때와 같은 401을 받습니다. 플로 자체는 Sume MCP 서버 OAuth 플로에서 다룹니다.

다시 로그인하려면 어떻게 하나요?

• 세션에서: /mcp를 실행하고 브라우저에 나오는 단계를 따르세요. 로그인한 뒤 리다이렉트가 실패하면, 주소 표시줄의 콜백 URL 전체를 Claude Code가 보여 주는 프롬프트에 붙여 넣으세요.
• 셸에서: claude mcp login sume을 실행하세요. SSH 환경에서는 브라우저를 여는 대신 인가 URL을 출력합니다. 그 URL을 자신의 머신에서 연 뒤 리다이렉트 URL을 다시 붙여 넣으세요. ssh -t로 접속하고, 그 프롬프트를 강제로 띄우려면 --no-browser를 넘기세요.
• Sume 동의 페이지에서 Read는 켜진 채 고정되고 Write는 기본적으로 꺼져 있습니다. Claude가 쓰기·유료 도구를 실행해야 할 때만 Write를 켜세요. 읽기 전용 토큰은 그런 도구에서 insufficient_scope를 받습니다. 현재 Sume 코드는 이를 HTTP 403이 아니라 실패한 도구 결과 안에 담아 반환하므로, 로그인 만료가 아니라 권한 문제입니다. claude mcp logout sume을 실행한 뒤 Write를 켜고 다시 로그인하세요. 다른 해결 방법은 Sume MCP insufficient_scope·누락 도구·타임아웃 해결에서 다룹니다.
• claude mcp list로 서버가 연결됨으로 표시되는지 확인한 뒤, Claude에게 mcp_health나 tools_list를 호출해 달라고 하세요.

claude -p와 CI에는 무엇을 써야 하나요?

API 키입니다. 비대화형 모드에는 /mcp 패널이 없어 Claude Code가 OAuth 플로를 대신 실행해 줄 수 없고, 어차피 현재 코드에서 Sume 토큰은 한 시간만 유효합니다. Sume는 자동화를 위해 API 키 원격 MCP를 유지합니다. 키는 Authorization: Bearer나 x-api-key 중 하나로 보내고 둘 다 보내지는 마세요(현재 코드는 둘 다 담은 요청을 거부합니다). 이 세션에는 쓰기·유료 도구를 포함한 전체 호스팅 도구 세트가 보입니다. 키는 CI 시크릿 저장소에 두고, 절대 채팅에 붙여 넣지 마세요.

claude mcp add --transport http sume https://mcp.sume.com/mcp \
  --header "Authorization: Bearer $SUME_API_KEY"

키 헤더를 설정하면 무엇이 달라지나요?

이제 거부된 키는 인증 필요가 아니라 연결 실패로 표시되며, Claude Code는 OAuth로 전환하지 않습니다. 키를 확인하거나, 헤더를 제거하고 OAuth로 로그인하세요. 기존 항목을 어느 쪽으로 바꾸든 먼저 제거해야 합니다. 같은 스코프에 이미 있는 이름으로 claude mcp add를 실행하면 실패하고, claude mcp remove sume은 Claude Code가 그 서버용으로 저장한 OAuth 토큰도 함께 삭제합니다. 나머지 설정은 Claude Code·Cursor·Codex를 호스팅 MCP로 Sume에 연결에 있습니다.