Claude Code MCP 시작 대기 시간, 제대로 설정하는 법

한 줄로 끝내는 Claude Code MCP 설정

첫 번째 턴에서 MCP 서버가 준비되기를 최대 5초까지 기다리게 하려면 CLAUDE_CODE_MCP_STARTUP_WAIT_MS=5000 claude -p "Run the scheduled check"를 사용합니다. MCP 서버가 하나도 준비되지 않은 상태에서도 작업을 시작할 수 있다면 CLAUDE_CODE_MCP_STARTUP_WAIT_MS=0으로 설정합니다.

Claude Code 2.1.274는 2026년 9월 17일 이 변수를 도입했습니다. 릴리스 노트는 두 가지를 분명히 정의합니다. 이 값은 첫 번째 비대화형 턴의 대기 시간을 밀리초 단위로 제한하며, 0은 기다리지 않는다는 뜻입니다. 새 변수의 기본값은 공개하지 않았습니다. 무인 작업에서는 값을 명시해 두어야 향후 기본값이나 머신 수준 환경 변수 때문에 시작 정책이 조용히 바뀌는 일을 막을 수 있습니다.

여기서 비대화형 실행은 CI 검사, cron 작업, SDK 기반 태스크처럼 -p 또는 --print로 시작한 실행을 뜻합니다. 대화형 터미널 세션은 이 설정의 대상이 아닙니다.

실무 기준은 간단합니다.

이 범위는 운영 권장값이지 Anthropic의 기본값이 아닙니다. 표준을 정하기 전에 직접 사용하는 서버를 측정해야 합니다.

Claude Code MCP 시작 대기는 무엇을 제어하나

첫 번째 턴을 출발 예정인 열차, 각 MCP 서버를 환승 승강장이라고 생각해 보겠습니다. CLAUDE_CODE_MCP_STARTUP_WAIT_MS는 환승 승객을 기다리기 위해 열차가 역에 얼마나 머물지를 정합니다. 승객이 역에 도착하려고 시도할 수 있는 시간, 탑승 후 작업에 걸리는 시간, 전체 여정이 끝나야 하는 시각까지 정하지는 않습니다.

이렇게 범위가 좁다는 점이 핵심입니다. 2.1.274 이전에는 운영자가 서로 다른 타이머를 제어하는 MCP_TIMEOUT을 대신 사용하는 경우가 많았습니다. 이제 예약 작업은 모든 서버 연결이나 이후의 툴 호출에 같은 제한 시간을 억지로 적용하지 않고도 첫 번째 턴에 짧은 준비 시간 창을 둘 수 있습니다.

네 개의 타이머에는 서로 다른 실패 기준이 필요합니다

가장 안전한 구성은 각 타이머에 이름을 붙이고 한 가지 역할만 맡기는 것입니다.

이와 별도로, 시작 시 연결을 차단 방식으로 일괄 처리할 때 적용되는 MCP_CONNECT_TIMEOUT_MS도 있으며 기본값은 5,000 ms입니다. MCP_CONNECTION_NONBLOCKING=0이나 alwaysLoad: true로 표시된 서버처럼 차단형 시작 동작에 쓰입니다. Anthropic의 환경 변수 문서는 이 값을 MCP_TIMEOUT과 명확히 구분합니다.

툴 호출의 경우 .mcp.json에서 특정 서버에 지정한 timeout 필드가 해당 서버의 MCP_TOOL_TIMEOUT을 재정의합니다. 데이터 웨어하우스 쿼리가 티켓 조회보다 더 오래 걸리는 것이 합리적인 상황에 유용합니다. 그렇더라도 새로 추가된 첫 번째 턴 대기 시간에는 영향을 주지 않습니다.

이 차이를 이해하면 0이 모든 상황에 통하는 가속 스위치가 아닌 이유도 분명해집니다. 툴 검색이 켜져 있을 때 프롬프트가 아직 연결 중인 서버를 나중에 필요로 하면 Claude Code는 ToolSearch 안에서 기다립니다. 툴 검색이 꺼져 있으면 WaitForMcpServers를 사용합니다. 입구의 대기를 건너뛰면 대기 시점이 작업 안쪽으로 옮겨갈 수 있습니다.

느린 서버로 직접 재현하는 테스트

MCP 초기화 응답만 지연하는 로컬 stdio 서버로 경계를 재현할 수 있습니다. 다음 코드를 slow-mcp.mjs로 저장합니다.

import readline from "node:readline";

const delay = Number(process.env.SLOW_MCP_DELAY_MS || 5000);
const lines = readline.createInterface({ input: process.stdin });
const send = message => process.stdout.write(JSON.stringify(message) + "\n");

lines.on("line", line => {
  const request = JSON.parse(line);
  if (request.method === "initialize") {
    setTimeout(() => send({
      jsonrpc: "2.0",
      id: request.id,
      result: {
        protocolVersion: request.params.protocolVersion,
        capabilities: { tools: {} },
        serverInfo: { name: "slow-ready", version: "1.0.0" }
      }
    }), delay);
  } else if (request.method === "tools/list") {
    send({ jsonrpc: "2.0", id: request.id, result: { tools: [] } });
  }
});

slow-mcp.json을 사용해 Claude Code가 이 서버를 바라보게 합니다.

{
  "mcpServers": {
    "slow-ready": {
      "type": "stdio",
      "command": "node",
      "args": ["./slow-mcp.mjs"],
      "env": { "SLOW_MCP_DELAY_MS": "5000" }
    }
  }
}

CLAUDE_CODE_MCP_STARTUP_WAIT_MS=1000 MCP_TIMEOUT=10000 claude -p "Reply with OK." --mcp-config ./slow-mcp.json --strict-mcp-config --output-format stream-json --verbose 명령으로 실행합니다.

--strict-mcp-config 플래그를 사용하면 테스트와 무관한 사용자·프로젝트 서버가 포함되지 않습니다. 스트림 형식에서는 초기 system/init 이벤트에 담긴 각 MCP 서버의 이름과 상태를 확인할 수 있습니다. 전달한 구성에 문제가 있으면 mcp_server_errors도 표시됩니다.

로컬 검사에서 확인한 결과

Claude Code 2.1.274의 인증 전 시작 검사에서는 5,000 ms 서버를 사용했습니다. 실행 환경에 로그인되어 있지 않아 인증 단계에서 중단됐습니다. 측정 범위는 시작 구간뿐이며, 바로 이 구간이 테스트하려던 경계입니다.

실제 시간에는 Claude Code와 npx 시작 오버헤드가 포함되므로 서비스 목표에 그대로 옮길 값은 아닙니다. 중요한 결과는 상태의 차이입니다. 0과 1,000 ms에서는 서버가 대기 중인 채로 첫 번째 턴 게이트가 열렸고, 7,000 ms에서는 같은 서버가 연결 상태로 보고됐습니다. 이 테스트는 모델 지연 시간이나 전체 작업 시간을 측정하지 않습니다.

본 작업 전에 준비 상태를 명시적으로 확인합니다

타임아웃은 “얼마나 기다릴 것인가?”에만 답합니다. 프로덕션 작업이라면 “어떤 툴이 필수인가?”에도 답해야 합니다.

두 단계로 게이트를 구성합니다.

1. 본 작업을 시작하기 전에 필수 원격 엔드포인트나 로컬 서버 명령 각각의 상태를 확인합니다. 구성되고 승인된 서버는 claude mcp list에서 연결됨, 인증 필요, 연결 실패 같은 상태를 보고합니다.
2. Claude Code 스트림에서 system/init.mcp_servers를 검사합니다. 지정한 서버의 status: "connected"를 필수 조건으로 두고, 해당 서버에 대한 mcp_server_errors 항목이 비어 있지 않으면 거부합니다. 캐시된 서버와 선택 서버는 명시적인 허용 목록에 따라 처리합니다.

필수 서버가 대기 중이면 본 작업의 결과를 받기 전에 실행을 종료합니다. 선택 서버라면 성능 저하 모드를 기록하고 계속 진행합니다. 이렇게 해야 대기 설정이 정책 그 자체가 아니라 정책의 입력값으로 기능합니다.

디스커버리 캐시는 특히 주의해야 합니다. 툴 목록이 캐시된 원격 서버는 초기화 때 대기 중으로 보였다가 첫 툴 호출 시 연결될 수 있습니다. 선택 툴에는 유용한 동작이지만, 엄격한 준비 상태 약속을 충족하지는 못합니다. 필수 툴 게이트는 실제 연결을 요구하거나 별도의 상태 검사를 수행해야 합니다.

마지막으로 전체 프로세스에는 스케줄러 수준의 종료 시한을 둡니다. 시작 대기 시간만으로는 모델 요청, Bash 명령, 훅 또는 이후의 MCP 툴 호출이 남은 실행 시간을 모두 쓰는 일을 막을 수 없습니다.

비용보다 더 큰 효과는 빠른 실패입니다

컴퓨팅 절감 효과는 실제로 있지만 과장하기 쉽습니다. 매월 10,000개의 작업이 원래 30초를 모두 기다린다고 가정하고 첫 번째 턴 예산을 3초로 설정하면, 회수할 수 있는 최대 용량은 러너 시간 4,500분입니다.

현재 GitHub가 제시하는 표준 2코어 Linux 호스팅 러너 요금은 분당 $0.006, macOS 러너는 분당 $0.062입니다. 이 요율을 적용하면 4,500분은 포함된 무료 시간을 제외하기 전 기준으로 Linux $27 또는 macOS $279에 해당합니다. GitHub는 각 작업의 사용량을 1분 단위로 올림하므로, 전체 실행 시간이 같은 과금 구간에 머문다면 27초를 줄여도 청구액은 전혀 달라지지 않을 수 있습니다.

더 큰 효과는 운영에서 나옵니다. 준비 상태 검사에 3초 만에 실패하면 스케줄러가 재시도하거나, 담당자에게 알리거나, 대체 경로로 전환할 시간을 확보할 수 있습니다. 반대로 데이터베이스나 이슈 트래커 없이 조용히 시작한 작업은 그럴듯하지만 불완전한 결과를 만들 수 있습니다. 이를 찾아내고 되돌리는 비용은 러너 사용료보다 큽니다.

대용량 응답도 함께 제어하려면 별도의 출력 측면을 다룬 Claude Code 툴 출력 제한 가이드를 참고할 수 있습니다. 무인 설치와 네트워크 정책에는 이 준비 상태 게이트와 명령별 네트워크 접근을 함께 적용합니다.

특히 효과가 큰 일곱 가지 워크플로

1. 예약 재무·운영 보고서

재무 운영자가 오전 6시에 웨어하우스 MCP 서버가 필요한 보고서를 실행한다고 가정해 보겠습니다. 해당 서버를 필수로 지정하고, 측정한 콜드 스타트에 약간의 여유를 더한 뒤, 연결되지 않으면 중단합니다. 이점은 실행 시간을 줄이는 데 그치지 않습니다. 실시간 수치를 가져올 수 없는 상태에서 저장소 파일만으로 번듯한 보고서를 만드는 사고를 방지합니다.

2. 자동화된 풀 리퀘스트 위험 검사

플랫폼 팀이 위험도가 높은 풀 리퀘스트마다 Claude Code를 실행하고 GitHub, 이슈 트래커, 보안 스캐너의 툴을 사용한다고 가정합니다. 게이트에서 스캐너와 GitHub는 필수로, 이슈 트래커는 선택 사항으로 지정할 수 있습니다. 그러면 가장 중요한 근거가 조용히 빠진 리뷰 대신 원인을 빠르게 설명할 수 있는 실패 결과를 개발자에게 전달합니다.

3. 릴리스 조율 작업

릴리스 관리자가 예약 에이전트로 병합된 작업, 진행 중인 인시던트, 배포 상태를 비교합니다. 각 데이터 소스에 준비 상태 규칙을 붙일 수 있습니다. 배포 MCP 서버가 다운되면 릴리스가 안전하다는 인상을 주는 릴리스 노트를 작성하기 전에 작업이 중단됩니다.

4. 야간 지원 티켓 분류

지원 팀이 작업을 실행해 티켓을 묶고, 계정 이력을 살펴보고, 답변 초안을 작성합니다. 헬프데스크와 고객 데이터 서버는 필수이고 Slack은 선택 사항일 수 있습니다. 제한된 대기 시간은 큐가 계속 흐르게 하며, 준비 상태 규칙은 데이터 소스가 없을 때 비공개 고객 맥락을 추측하는 일을 막습니다.

5. 인시던트 대응 도우미

온콜 엔지니어가 알림에서 비대화형 진단 실행을 시작합니다. 짧은 시작 예산을 두면 로그와 메트릭에 실제로 접근할 수 있는지 바로 드러납니다. 필수 서버 중 하나라도 사용할 수 없다면 래퍼가 즉시 수동 런북으로 전환할 수 있으므로, 일부 정보만으로 진단하느라 인시던트 대응 시간을 허비하지 않습니다.

6. 자동 확장 임시 러너

팀이 에이전트 작업마다 새 컨테이너를 실행합니다. 로컬 stdio 서버는 패키지 로딩, 인증 도우미 또는 스키마 탐색 때문에 콜드 스타트 비용이 발생할 수 있습니다. 이 시작 시간을 측정하면 실제로 필요한 7초 준비 예산과 비정상 서버를 감추기 위한 영구적인 우회책을 구분할 수 있습니다.

7. 멀티테넌트 에이전트 제품

제품이 고객별로 서로 다른 MCP 연결을 제공합니다. 어떤 테넌트에는 Salesforce가 필요하고, 다른 테넌트에는 Linear가 필요하며, 외부 툴이 전혀 필요 없는 테넌트도 있습니다. 실행별 필수 서버 목록을 두면 같은 오케스트레이션 계층에서 테넌트마다 짧은 대기 시간을 선택할 수 있고, 가장 느린 연동을 모든 사용자의 기본값으로 만들지 않아도 됩니다.

제품으로 만들 만한 세 가지 아이디어

1. Claude Code CI용 MCP 준비 상태 게이트

가장 유망한 기회입니다. 필수 서버 정책을 읽고, 명시적인 대기 시간으로 Claude Code를 시작하고, system/init을 기록한 뒤, 에이전트 결과를 받기 전에 기계가 읽을 수 있는 준비 상태 실패를 반환하는 소형 러너 래퍼입니다.

수요층은 좁지만 사업성은 충분합니다. claude code automation은 미국에서 월간 검색량 약 140회, 제안 데이터 기준 연간 증가율 200%, CPC $10.88를 기록합니다. Claude Code를 자동 실행하는 방법과 Claude Code에서 MCP를 구성하는 방법을 묻는 사람도 있습니다. 모두 이 설정 문제를 직접 드러내는 검색입니다.

판매 가능한 최소 버전은 정책 파일, GitHub Actions 주석, 실행별 JSON 증거를 제공하는 CLI입니다. 관건은 유통입니다. Anthropic이 더 풍부한 기본 준비 상태 정책을 추가할 수 있으므로, 여러 에이전트 런타임을 지원하고 실행 이력과 알림을 제공하는 데 지속 가능한 가치가 있어야 합니다.

2. 타임아웃 정책 린터

셸 스크립트, CI 파일, 설정, .mcp.json을 검사해 서로 다른 타이머가 뒤섞인 구성을 찾아내는 툴입니다. 필수 툴이 있는데 시작 대기 시간을 0으로 둔 경우, 작업 종료 시한은 짧은데 툴 타임아웃은 28시간으로 둔 경우, 선택 연동에 상한을 두지 않은 경우 등을 표시할 수 있습니다.

정확히 일치하는 키워드인 mcp server timeout은 미국에서 월간 검색량 약 10회이며, 보고된 연간 추세는 -67%입니다. 관련 검색어로 MCP_TOOL_TIMEOUT이 있고, Claude Code 타임아웃을 늘리는 방법을 묻는 사람들도 있습니다. 준비 상태 게이트의 기능으로 넣을 만큼의 수요는 있지만 독립 기업을 세울 정도는 아닙니다.

MVP에는 GitHub Actions, 일반적인 셸 문법, Claude Code MCP 구성용 파서와 함께 단호한 수정 제안이 필요합니다. 문제는 잘못된 확신입니다. 런타임 측정 없이는 정적 구성만으로 서버의 실제 콜드 스타트 분포를 알 수 없습니다.

3. 예약 에이전트 시작 텔레메트리

system/init 이벤트를 연결 지연 시간, 대기 상태, 잘못된 구성, 성능 저하 실행을 보여 주는 타임라인으로 바꾸는 제품입니다. 플랫폼 팀은 JSONL 파일을 일일이 읽는 대신 여러 저장소의 추세와 알림에 비용을 지불할 것입니다.

이 아이디어도 claude code automation의 월간 검색량 140회를 공유합니다. 여기에 claude code browser automation이 40회를 더하며, 이 검색어 역시 제안 데이터에서 연간 증가율 200%를 보입니다. 더 큰 흐름은 팀들이 Claude Code를 반복 실행 가능한 작업으로 옮기면서 시작 증거가 운영 문제로 바뀌고 있다는 점입니다.

MVP는 이벤트 수집기, 필수·선택 서버 맵, 준비 상태가 서비스 목표를 벗어났을 때 보내는 알림으로 구성됩니다. 관건은 데이터 민감도입니다. MCP 이름과 툴 메타데이터는 내부 시스템을 드러낼 수 있으므로, 정보 가림과 자체 호스팅은 나중에 붙일 엔터프라이즈용 장식이 아니라 제품의 기본 요소입니다.

한계와 현실적인 결론

이 제어 변수는 신뢰할 수 있는 자동화를 구성하는 작지만 중요한 한 부분만 해결합니다. 고장 난 MCP 서버를 복구하거나, 만료된 커넥터를 다시 인증하거나, 이후의 툴 호출 시간을 줄이거나, Claude Code 프로세스 전체를 중단하지는 못합니다.

첫 번째 유의미한 동작에 MCP가 필요한 작업이라면 0을 사용하지 마십시오. 초기화 시 pending 상태가 나타날 수 있고, 툴을 검색하는 순간 다시 기다릴 수 있습니다. 불안정한 서버가 정상처럼 보일 때까지 값을 늘리는 방법도 피해야 합니다. HTTP와 SSE 서버는 첫 연결의 일시적 실패를 재시도하지만, 인증 오류와 찾을 수 없음 오류는 구성을 수정해야 합니다. 대기 시간을 늘리면 그 사실을 늦게 알게 될 뿐입니다.

stdio 서버는 세션 도중 연결이 끊겨도 자동으로 다시 연결되지 않습니다. 넉넉한 시작 시간 창을 줬다고 해서 10분 뒤에도 정상이라는 보장은 없습니다.

가장 좋은 정책은 엄격하고 단순합니다. 첫 번째 턴에는 짧고 명시적인 대기 시간을 두고, 필수 서버의 이름을 지정하고, 상태 게이트와 별도의 툴 타임아웃, 전체 작업 종료 시한을 구성합니다. 이 조합은 원인을 알 수 없는 지연 대신 조치 가능한 실패를 만듭니다.

월요일에는 예약된 Claude Code 작업 하나를 골라 필수 MCP의 콜드 스타트를 측정하고, 실제 상황에 맞는 가장 짧은 대기 시간을 설정한 다음, 필수 서버가 대기 중이면 결과를 신뢰하기 전에 실패하도록 만드십시오. 에이전트 워크플로 전반에 이런 신뢰성 계층을 구축하려면 프로덕션 시스템 구축을 도와드릴 수 있습니다.