Claude Code MCP 서버 시작/연결 실패의 원인과 해결 방법
지금 장애가 있나요?
Claude Code 공식 상태는 정상입니다. 이 오류가 계속되면 구현(코드) 또는 사용자 환경 문제일 가능성이 높습니다.
Claude Code의 가동 상태 보기 →오류의 의미
설정한 MCP(Model Context Protocol) 서버가 시작 또는 연결에 실패한 상태입니다(예: "MCP server '…' failed to connect"). 보통 Claude Code 자체가 아니라 MCP 서버 측의 설정 문제(명령, 인수, 런타임, 환경 변수)입니다.
자주 있는 원인
- •.mcp.json / 설정의 명령 경로나 인수 오류
- •필요한 런타임(node / python / uvx) 미설치 또는 PATH 외부
- •필요한 환경 변수(API 키 등) 누락
- •MCP 서버 프로세스의 시작 실패 또는 크래시
- •stdio / SSE 종류나 URL 지정 오류
- •실행 권한 부족
해결 방법
- 1.`claude mcp list`로 등록 상태, `/mcp`로 연결 상태 확인
- 2.설정의 명령·인수·env 점검
- 3.필요한 런타임을 설치하고 PATH에 추가
- 4.해당 명령을 단독 실행해 시작되는지 확인
- 5.필요한 환경 변수(API 키 등) 설정
- 6.로그로 서버 측 오류 원인 파악
- 7.설정을 수정하고 Claude Code 재시작
기다리면 되는 경우 / 기다려도 안 되는 경우
MCP는 설정/환경 문제가 많아 기다려도 해결되지 않습니다. 설정과 런타임을 확인하세요. Anthropic 본체 장애와 무관하므로 본체가 정상이어도 MCP만 실패할 수 있습니다.
Claude Code을(를) 쓸 수 없을 때의 대체
관련 오류
자주 묻는 질문
MCP server failed은(는) 무엇인가요?
설정한 MCP(Model Context Protocol) 서버가 시작 또는 연결에 실패한 상태입니다(예: "MCP server '…' failed to connect"). 보통 Claude Code 자체가 아니라 MCP 서버 측의 설정 문제(명령, 인수, 런타임, 환경 변수)입니다.
MCP server failed은(는) 어떻게 해결하나요?
`claude mcp list`로 등록 상태, `/mcp`로 연결 상태 확인 / 설정의 명령·인수·env 점검 / 필요한 런타임을 설치하고 PATH에 추가 / 해당 명령을 단독 실행해 시작되는지 확인 / 필요한 환경 변수(API 키 등) 설정 / 로그로 서버 측 오류 원인 파악 / 설정을 수정하고 Claude Code 재시작