Claude Code MCP가 연결됐는데 첫 질문에서 도구가 안 보일 때: 5초 스냅샷 확인

Short Answer. Claude Code의 첫 쿼리는 MCP 연결 배치를 무한히 기다리지 않는다. 공식 환경 변수 문서에 따르면 기본적으로 약 5초 동안 연결을 기다린 뒤 도구 목록을 스냅샷하며, 그 시점까지 연결되지 않은 서버는 백그라운드에서 계속 연결되더라도 다음 쿼리 전까지 보이지 않을 수 있다.

Question

claude mcp list에서는 서버가 보이는데 첫 질문에서 MCP 도구가 나타나지 않는다. 재설치해야 할까?

Scope

2026-10-07 기준 Claude Code의 로컬·원격 MCP 연결을 대상으로 한다. 아래 명령과 설정은 실제 비밀값을 포함하지 않는다.

Cause 1 — 첫 쿼리의 연결 대기 시간이 끝났다

Claude Code에는 MCP_CONNECT_TIMEOUT_MS가 있다. 공식 문서의 기본값은 5000ms다. 첫 질문이 도구 목록을 만들 때 아직 연결 중인 서버는 그 스냅샷에서 빠질 수 있다.

# 예: 연결이 느린 개발 환경에서만 임시 확인
export MCP_CONNECT_TIMEOUT_MS=10000
claude

값을 늘리는 것이 항상 해결책은 아니다. 서버 시작이 비정상적으로 느리다면 원인을 고치는 편이 우선이다. 이 변수는 “첫 질문이 얼마나 기다릴지”를 바꾸는 진단 수단으로 보는 게 안전하다.

Cause 2 — 서버 등록 상태와 실제 구성을 구분하지 않았다

claude mcp list
claude mcp get my-server

list로 등록된 서버를 확인하고, get으로 특정 서버 구성을 다시 읽는다. 프로젝트 범위 서버는 .mcp.json에 들어갈 수 있고, 사용자 범위 서버는 머신 전체에서 사용할 수 있다.

Cause 3 — 모든 MCP 도구가 처음부터 프롬프트에 들어오는 것은 아니다

Claude Code는 MCP 도구가 많을 때 tool search를 사용할 수 있다. ENABLE_TOOL_SEARCH 설정에 따라 모든 MCP 도구를 미리 로드하지 않고 필요할 때 검색하도록 동작할 수 있다. 따라서 “초기 프롬프트에 도구 설명이 없다”와 “서버 연결 실패”를 같은 문제로 보면 안 된다.

Cause 4 — 안전한 환경 상속 설정으로 필요한 변수가 사라졌다

CLAUDE_CODE_MCP_ALLOWLIST_ENV=1을 사용하면 stdio MCP 서버는 셸 환경 전체를 상속하지 않고 안전한 기본 환경과 서버에 명시한 env만 받는다. 이 상태에서 서버가 셸에만 존재하는 API key를 기대하면 연결은 실패할 수 있다.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "SERVICE_API_KEY": "${SERVICE_API_KEY}"
      }
    }
  }
}

Verification

claude mcp list에서 서버 등록을 확인한다.
claude mcp get my-server로 transport, command/URL, scope를 확인한다.
첫 질문 직후 안 보였다면 연결 완료 뒤 두 번째 질문에서 다시 확인한다.
필요하면 일시적으로 MCP_CONNECT_TIMEOUT_MS를 늘려 “느린 연결” 가설을 검증한다.
stdio 서버라면 필요한 환경 변수가 서버 구성에 명시돼 있는지 확인한다.

Do Not Confuse

등록됨: 설정에 서버가 존재한다.
연결됨: 클라이언트가 서버와 통신할 수 있다.
도구 발견됨: 현재 쿼리가 사용할 tool metadata를 확보했다.
도구 사용 허용됨: 권한 정책상 호출 가능하다.

Sources

Last verified: 2026-10-07. 실제 키·계정·로컬 사용자 경로는 공개하지 않는다.