Claude Code MCP idle timeout: 원격 도구 멈춤을 5분 안에 끊는 법 | DAKER 커뮤니티

Claude Code MCP idle timeout: 원격 도구 멈춤을 5분 안에 끊는 법

Claude Code 원격 MCP 도구가 응답 없이 멈추면 이제 운영자가 기다림의 기준을 먼저 정해야 합니다. MCP idle timeout이란 원격 MCP 도구가 응답이나 진행 알림 없이 멈춘 시간을 기준으로 호출을 중단하는 안전장치입니다. 2026년 6월 30일 기준 공식 문서와 v2.1.187 릴리스 확인 후, 팀 MCP 런북에 바로 넣을 점검 순서를 정리했습니다.

한 줄 요약: 원격 MCP 장애는 "도구가 느린가"가 아니라 "진행 신호가 있는가"로 먼저 구분해야 합니다.

관련해서 먼저 보면 좋은 DAKER 글은 MCP 서버 연결과 MCP 재연결 점검입니다.

_이미지: 클로드 코드 MCP idle timeout으로 원격 도구 멈춤을 판단하는 대표 카드._

문제 상황: MCP 도구가 멈췄을 때 무엇부터 확인해야 할까?

원격 이슈 트래커, 모니터링, 데이터베이스 MCP를 붙이면 Claude Code가 외부 시스템을 직접 읽고 처리할 수 있습니다. 하지만 HTTP, SSE, WebSocket 기반 MCP 서버가 응답 없이 멈추면 긴 세션 전체가 기다림에 묶입니다.

운영 기준은 단순합니다. 도구가 오래 걸려도 진행 알림이 있으면 기다릴 수 있고, 아무 응답도 없으면 timeout으로 끊고 재시도 또는 서버 점검으로 넘겨야 합니다.

핵심 개념: CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT은 무엇을 바꾸나?

공식 문서 기준 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT은 원격 MCP 도구 호출의 idle timeout을 밀리초로 정합니다. 기본값은 300000ms, 즉 5분입니다. 대상은 HTTP, SSE, WebSocket, claude.ai connector 서버이며, stdio나 IDE 서버에는 적용되지 않습니다.

전체 실행 제한인 MCP_TOOL_TIMEOUT과도 다릅니다. MCP_TOOL_TIMEOUT은 벽시계 기준 최대 실행 시간이고, idle timeout은 응답 또는 progress notification이 없는 침묵 시간을 봅니다.

상황	먼저 볼 설정	판단 기준
서버 시작이 느림	`MCP_TIMEOUT`	연결 단계가 끝나는가
도구 실행이 오래 걸림	`MCP_TOOL_TIMEOUT`	총 실행 시간이 허용 범위인가
원격 도구가 침묵함	`CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT`	응답/진행 알림 없이 5분을 넘는가

_이미지: MCP 연결, 실행, idle timeout을 나눠 장애를 분류하는 워크플로._

단계별 사용법: 팀 MCP 런북에 어떻게 넣을까?

claude --version으로 v2.1.187 이상인지 확인합니다.
/mcp 또는 claude mcp list로 대상 서버가 remote transport인지 확인합니다.
장기 실행 도구라면 MCP 서버가 progress notification을 보내는지 운영자에게 묻습니다.
침묵형 도구가 정상적으로 5분 이상 걸린다면 서버별 timeout 설계를 다시 합니다.
정말 필요할 때만 CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT=0으로 idle check를 끄고, 이유를 런북에 남깁니다.

짧은 예시: 느린 리포트 MCP를 구분하는 프롬프트

긴 리포트 생성 도구를 붙였다면 이렇게 요청해 보세요.

/mcp에서 analytics 서버 상태를 확인하고, 리포트 도구가 progress notification을 보내는지 먼저 판단해줘. 5분 침묵 timeout이 반복되면 서버 로그 확인 항목만 요약해줘.

이 프롬프트의 목적은 Claude에게 "다시 호출해 봐"가 아니라 "연결, 실행, 침묵"을 나눠 보게 하는 것입니다.

팀 적용 체크리스트: idle timeout을 끄기 전에 무엇을 확인할까?

remote MCP 서버인지, local stdio 서버인지 구분했습니다.
장기 작업 도구가 진행 알림을 보내는지 확인했습니다.
401/403 같은 인증 오류와 침묵 timeout을 섞어 보지 않았습니다.
timeout 값을 늘릴 때는 서버별 근거와 담당자를 남겼습니다.
DAKER의 Claude Code sandbox.credentials처럼 비밀값 보호 설정도 함께 점검했습니다.

공식 출처: 어떤 기준으로 확인했나?

이 글은 2026년 6월 30일 기준 Claude Code MCP Reference, Environment variables 문서, Anthropic Claude Code GitHub Releases v2.1.187을 확인해 작성했습니다. 공개 본문에는 DAKER/DACON 정책에 따라 외부 URL을 노출하지 않았습니다.

자주 묻는 질문

MCP_TOOL_TIMEOUT과 MCP_TOOL_IDLE_TIMEOUT은 같은 설정인가요?

아닙니다. MCP_TOOL_TIMEOUT은 전체 실행 시간이고, CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT은 원격 도구가 응답 없이 침묵한 시간을 기준으로 합니다.

idle timeout을 0으로 꺼도 되나요?

가능하지만 기본값을 먼저 유지하는 편이 안전합니다. 끄는 경우에는 해당 도구가 진행 알림 없이 오래 걸리는 이유와 담당자를 남겨야 합니다.

모든 MCP 서버에 적용되나요?

아닙니다. 공식 문서 기준 HTTP, SSE, WebSocket, claude.ai connector 같은 원격 서버에 적용되고 stdio나 IDE 서버에는 적용되지 않습니다.

MCP 장애가 나면 먼저 재설치해야 하나요?

아닙니다. 먼저 /mcp, 서버 상태, 인증, timeout 종류를 분리하세요. 재설치는 설정 파일과 인증 상태를 확인한 뒤 마지막에 판단하는 편이 좋습니다.

오늘 팀 MCP 런북에 "연결 timeout, 실행 timeout, idle timeout" 세 줄을 나눠 적어두면 다음 장애 때 훨씬 빨리 원인을 좁힐 수 있습니다.