MCP 서버 모니터링 완전 가이드

/mcp 명령으로 장애 진단·복구·운용 체크리스트

MCP 서버를 안정적으로 운용하기 위한 모니터링·진단 스킬을 습득합니다. 장애 발생 시에 원인을 특정하여 신속하게 복구할 수 있게 됩니다.

배경 지식

MCP 서버의 상태 전이

MCP 서버는 다음의 상태를 가집니다.

보충: 상태의 표시 형식은 Claude Code의 버전에 따라 다를 수 있습니다.

모니터링의 중요성

MCP 서버가 동작하지 않는 경우, Claude Code는 해당 서버가 제공하는 툴을 사용할 수 없게 됩니다. 개발 중에 서버가 단절되면 작업이 중단됩니다. 정기적인 상태 확인과 장애 시의 신속한 복구가 중요합니다.

장애의 종류

� 핵심 포인트
인증 에러는 /mcp에서 connected로 표시되어도 발생합니다. 실제로 툴을 실행하기 전까지는 감지할 수 없으므로, 서비스 연동 서버는 반드시 실제 조작으로 확인하세요.

따라하기

1단계: /mcp 커맨드로 상태를 확인한다

Claude Code의 대화 모드에서 현재 MCP 서버의 상태를 확인합니다. GitHub MCP 서버도 표시하려면, 4회차에서 작성한 인증 정보가 들어간 설정 파일을 --mcp-config로 읽어 들여 기동합니다(방법 C의 기동 스크립트를 사용하는 경우는 ./start-claude.sh도 가능합니다).

cd ~/mcp-workspace
claude --mcp-config ~/mcp-workspace/config/mcp-auth.json

대화 모드 내에서 실행합니다.

> /mcp

기대되는 출력 예시:

Manage MCP servers
2 servers

Project MCPs (.mcp.json)
filesystem · ✔ connected
github · ✔ connected

각 서버에 대해 서버명과 상태(✔ connected / ✘ failed)가 표시됩니다.

� 정상 상태의 베이스라인 기록
처음으로 모든 서버가 정상 접속된 출력 내용을 팀의 README나 운용 문서에 기록해두면, 장애 시에 빠르게 차이를 파악할 수 있습니다.

2단계: 의도적으로 장애를 발생시킨다 (기동 실패)

학습을 위해, 일부러 망가진 MCP 서버를 JSON 설정 파일에 추가하여 동작을 확인합니다. 대화 모드를 종료한 후, 존재하지 않는 커맨드의 서버를 추가합니다.

cat > ~/mcp-workspace/config/mcp-broken.json << 'EOF'
{
"mcpServers": {
"broken-server": {
"command": "nonexistent-command-12345",
"args": []
}
}
}
EOF

이 망가진 설정을 포함하여 Claude Code를 기동하고, 상태를 확인합니다.

claude --mcp-config ~/mcp-workspace/config/mcp-auth.json --mcp-config ~/mcp-workspace/config/mcp-broken.json

> /mcp

broken-server가 ✘ failed가 되어 있는 것을 확인합니다.
확인 후, 대화 모드를 종료하고, 테스트용 설정 파일을 삭제합니다.

rm ~/mcp-workspace/config/mcp-broken.json

3단계: 의도적으로 장애를 발생시킨다 (인증 에러)

2단계에서는 커맨드가 존재하지 않는 케이스를 시험했습니다. 다음은 서버 자체는 기동하지만 인증 정보가 잘못되어 있는 케이스를 시험합니다. 실제 운용에서도 토큰 만료나 복사 실수는 자주 있는 장애 원인입니다.

cat > ~/mcp-workspace/config/mcp-bad-auth.json << 'EOF'
{
"mcpServers": {
"github-bad": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "invalid_token_12345"
}
}
}
}
EOF

claude --mcp-config ~/mcp-workspace/config/mcp-bad-auth.json

인증 에러는 Step 2의 기동 실패와는 달리,