Claude Code MCP 재연결: 도구 목록 변경과 장애 복구를 점검하는 법 | DAKER 커뮤니티

Claude Code MCP 재연결: 도구 목록 변경과 장애 복구를 점검하는 법

Claude Code MCP 재연결이란, 원격 MCP 서버가 끊겼을 때 Claude Code가 재시도하고 도구 목록 변경을 세션 중 갱신하는 흐름을 의미합니다. 2026년 6월 23일 기준 공식 문서는 HTTP/SSE 서버의 자동 재연결, list_changed 알림, claude mcp login 재인증 경로를 구분해 설명합니다.

_클로드 코드 MCP 연결 장애와 도구 갱신을 한눈에 보는 대표 카드._

Claude Code MCP 장애는 왜 먼저 분류해야 하나요?

한 줄 요약: MCP 문제가 생기면 "서버 끊김", "stdio 프로세스 종료", "인증 오류", "tool 목록 변경"을 먼저 나눠야 복구 시간이 줄어듭니다.

MCP는 Claude Code가 Sentry, GitHub, DB, 내부 도구 같은 외부 시스템을 쓰게 해주는 연결층입니다. 그래서 MCP 장애를 단순히 "도구가 안 보인다"로만 보면 원인을 놓치기 쉽습니다. 원격 서버가 잠깐 끊긴 것인지, 로컬 stdio 프로세스가 죽은 것인지, OAuth가 만료된 것인지, 서버가 새로운 tool 목록을 보낸 것인지가 각각 다릅니다.

관련해서 DAKER의 Claude Code worktree skills 로딩은 팀 절차가 세션에 제대로 올라오는지 확인하는 법을 다뤘고, Claude Code auto mode git 안전장치는 자동 실행 중 멈춰야 할 경계를 다뤘습니다. 이번 글은 MCP 운영자가 세션 장애를 보고 어디부터 확인할지에 초점을 둡니다.

MCP list_changed와 자동 재연결은 무엇이 다른가요?

list_changed는 서버가 tools, prompts, resources 목록 변경을 알리는 신호입니다. 연결이 살아 있는 상태에서 기능 목록만 바뀌는 상황에 가깝습니다. 반면 자동 재연결은 HTTP 또는 SSE MCP 서버가 끊겼을 때 Claude Code가 다시 붙으려는 복구 흐름입니다.

상황	Claude Code 처리	사람이 확인할 것
`list_changed` 알림	세션을 유지한 채 도구 목록 자동 갱신	서버가 의도한 tool 변경인지
HTTP/SSE 서버 끊김	지수 백오프로 최대 5회 재연결	5xx, timeout, 네트워크 상태
시작 시 transient error	v2.1.121 기준 최대 3회 재시도	서버 부팅 시간과 health check
인증 또는 not-found 오류	자동 재시도 대상 아님	OAuth, 서버 이름, URL, scope 설정
stdio 서버 종료	자동 재연결 안 함	로컬 프로세스 로그와 재시작

단계별 사용법: MCP가 안 보이면 무엇부터 보나요?

/mcp 또는 상태 화면에서 서버가 pending, failed, connected 중 무엇인지 확인합니다.
HTTP/SSE 서버라면 잠시 pending인지, 5회 재시도 후 failed인지 나눕니다.
stdio 서버라면 로컬 프로세스가 종료됐는지 로그를 봅니다.
인증 오류라면 claude mcp login <name>으로 재인증이 필요한지 확인합니다.
tool 목록이 바뀐 직후라면 서버가 list_changed 알림을 보냈는지 확인합니다.
재현 가능한 장애라면 서버 이름, 전송 방식, 오류 종류, 마지막 정상 시각을 기록합니다.

_HTTP/SSE, stdio, 인증 오류, tool 목록 변경을 구분하는 비교표 이미지._

짧은 예시: 운영자에게 넘길 장애 메모는 어떻게 쓰나요?

MCP 서버: sentry-prod
전송 방식: HTTP/SSE
증상: Claude Code에서 도구가 pending 후 failed
확인: 5xx와 timeout이 3분 동안 반복됨
인증: OAuth 오류 메시지는 없음
다음 액션: 서버 health check, tool list 변경 여부, 최근 배포 확인

이 정도 메모면 "Claude가 도구를 못 씁니다"보다 훨씬 빨리 복구 방향을 잡을 수 있습니다. 인증 오류라면 서버 로그보다 claude mcp login <name> 재인증이 먼저일 수 있고, stdio라면 원격 서버가 아니라 로컬 프로세스 로그가 우선입니다.

팀 적용 체크리스트는 무엇인가요?

MCP 서버별 전송 방식: HTTP, SSE, stdio를 기록했는가
OAuth가 필요한 서버와 필요 없는 서버를 분리했는가
claude mcp login <name> 재인증 절차를 문서화했는가
tool 목록 변경 배포 시 list_changed 알림을 테스트했는가
5xx, timeout, auth, not-found를 같은 장애로 묶지 않았는가
stdio 서버는 자동 재연결을 기대하지 않도록 runbook에 적었는가

공식 출처는 어디에서 확인했나요?

2026년 6월 23일 기준 Claude Code MCP documentation과 CLI reference를 확인했습니다. 공개 본문에는 DAKER 운영 정책에 맞춰 DAKER 내부 링크만 연결했습니다.

FAQ

MCP 서버가 끊기면 Claude Code가 항상 복구하나요?

아닙니다. HTTP/SSE 서버는 자동 재연결 대상이지만, stdio 서버는 로컬 프로세스라 자동 재연결되지 않습니다.

`list_changed`는 장애 복구 기능인가요?

장애 복구라기보다 도구 목록 갱신 기능입니다. 서버가 tools, prompts, resources 변경을 알리면 Claude Code가 세션을 유지한 채 목록을 새로 봅니다.

인증 오류도 재시도하면 해결되나요?

대부분 아닙니다. 공식 문서 기준 인증 오류와 not-found 오류는 설정 변경이 필요하므로 자동 재시도 대상이 아닙니다.

CLI에서 MCP 인증을 다시 하려면 어떻게 하나요?

원격 MCP 서버가 OAuth를 쓰고 있다면 claude mcp login <name>을 확인하세요. SSH 환경에서는 브라우저 없이 인증 URL을 받아 처리하는 옵션도 고려할 수 있습니다.

다음 MCP 장애를 만났을 때는 먼저 전송 방식과 오류 종류를 나눈 뒤, 재연결 대기인지 재인증인지부터 판단해 보세요.