Claude Code 설정 파일에 주석을 한 줄만 작성했더니 등록된 MCP 서버가 모두 사라졌습니다: `.claude.json`의 은밀한 완전

Claude Code의 설정 파일에 주석(comment)을 단 한 줄만 작성했을 뿐인데, 등록했던 모든 MCP 서버가 사라졌습니다. 방아쇠는 rm이 아니었습니다.

심지어 git reset도 아닙니다. ~/.claude.json 파일에 자신만의 메모를 /* … */ 형식으로 추가하고 저장한 후 재시작했을 뿐입니다. 오류 메시지는 아무것도 출력되지 않았습니다.

본 기사는 이슈 #69354에서 보고된 이 사고의 발생 메커니즘, 사라진 내용을 복구하는 방법, 그리고 다시는 잃지 않기 위한 두 가지 습관을 정리합니다.

~/.claude.json은 JSON 형식입니다. JSON은 주석을 허용하지 않습니다. //나 /* */를 추가하면 파일 전체가 유효하지 않은(invalid) JSON이 되며, Claude Code는 이를 파싱할 수 없을 때 오류 메시지를 출력하는 대신 설정을 실질적으로 비어있는 상태로 덮어씁니다. 그 결과, 등록되어 있던 MCP 서버 정의가 하나도 남지 않고 사라집니다.

보고자는 "작동하던 ~/.claude.json에 블록 주석을 하나 추가하고 저장한 후 Claude Code를 재시작했더니, 설정이 조용히 사라지고 모든 MCP 서버를 잃었다"고 작성했습니다 (macOS・2.1.142).

두 가지 사실이 결합되어 사고가 발생합니다.

첫째, JSON 사양에는 주석 구문(comment syntax)이 없습니다. 설정 파일 편집에 익숙하면 '이 키는 무엇을 위한 것일까', '여기는 임시로 제외했어'와 같은 내용을 /* */로 메모하고 싶은 충동을 느끼지만, JSON에서는 이것이 유효하지 않은 문자입니다. 직접 확인해 볼 수 있습니다.

cat > /tmp/sample.json <<'EOF'
{
"mcpServers": {
...

주석만 지우면 같은 내용이라도 문제없이 읽을 수 있습니다. 망가진 것은 내용 자체가 아니라, 주석이라는 단 한 줄입니다.

이슈에 달린 댓글에서 다른 사용자가 이 점을 정확하게 정리했습니다. 핵심은 '검증 없이 작성하는(write-without-validation)' 패턴이라고 합니다. 비록 주석이 JSON에서 지원되지 않더라도, 파싱에 실패한 파일을 파서가 조용히 덮어쓰게 해서는 안 된다는 지적입니다.

안전하게 설계되었다면, 로드에 실패하는 시점에서 '설정 파일이 손상되었습니다'라고 알려주고, 원래 파일에는 단 한 글자도 건드리지 않은 채 멈춰야 합니다. 하지만 현재 상황은 파싱에 실패한 후에도 쓰기(write) 측이 진행되어, 깨진 입력 대신 (실질적으로 비어있는) 설정으로 덮어쓰게 됩니다. 이렇게 재시작이라는 사소한 조작 후에 설정이 사라지는 것입니다.

Claude Code의 안전장치 중 상당수는 Claude의 도구 호출(Bash나 Write 또는 Edit 같은)을 PreToolUse hook에서 검사하고 막는 형태입니다. 하지만 이 사고는 Claude가 어떤 도구를 호출한 결과로 발생한 것이 아닙니다. Claude Code라는 앱 자체가, 시작할 때 자신의 설정 파일을 읽고 쓰는 과정에서 일어난 것입니다. 도구 호출을 감시하는 훅의 그물망에는 원리적으로 걸리지 않습니다.

git의 안전망도 소용이 없습니다. ~/.claude.json은 사용자의 홈에 있는 설정 파일이며, 보통 리포지토리 관리 하에 두지 않습니다. 따라서 'git 덕분에 복구할 수 있다'는 전제 자체가 여기서는 무효합니다.

사라져도 대부분의 경우, 설정 자체를 기억하지 못해도 되찾을 수 있습니다.

1. 셸 히스토리에서 등록 명령어를 찾아냅니다. MCP 서버를 CLI로 추가했다면, 그 당시의 명령어가 히스토리에 남아있습니다.

history | grep -E "claude mcp (add|add-json)"

나온 명령어를 그대로 다시 실행하면, 동일한 서버가 다시 등록됩니다.

2. 이전 복사본을 찾아봅니다. 에디터의 자동 저장 기록이나 클라우드 동기화 기록, ~/.claude.json.bak과 같은 백업 파일이 남아있을 수 있습니다.

ls -la ~/.claude.json* ~/.config/**/claude*.json 2>/dev/null

3. 프로젝트 측 설정을 확인합니다. MCP의 정의는 홈 디렉터리의 ~/.claude.json뿐만 아니라, 프로젝트의 .mcp.json에도 작성할 수 있습니다. 프로젝트 측에 남아있다면, 거기서 복사할 수 있습니다.

예방 1: JSON에 주석을 쓰지 않습니다. 이것이 가장 효과적입니다. 키의 의미를 남기고 싶다면, 주석 대신 설명을 겸하는 키 이름으로 지정하거나, 별도의 README 파일에 작성해야 합니다.

작성합니다. 어떻게든 주석이 포함된 설정을 다루고 싶다면, 그것은 JSONC나 YAML을 허용하는 다른 파일의 역할이며, ~/.claude.json에는 가져오지 않습니다.

예방 2: .claude.json을 실행할 때마다 자동으로 백업한다. 만일의 덮어쓰기에 대비하여 세대별 백업(世代バックアップ)을 생성합니다. 핵심은, 복사하기 전에 반드시 "올바른 JSON인가"를 검증하는 것입니다. 망가진 내용을 백업에 덮어씌워 버리면 본말전도이기 때문입니다.

#!/usr/bin/env bash
# ~/.claude/hooks/backup-claude-json.sh
# SessionStart에서 실행. 현재의 ~/.claude.json이 "올바른 JSON일 때만" 세대별 백업을 수행함.
...

settings.json의 hooks.SessionStart에 이 스크립트를 등록해 두면, 세션을 열 때마다 파일이 손상되지 않았을 때만 백업 세대가 늘어납니다. 만일 파일이 사라지더라도 가장 최근의 올바른 설정으로 되돌릴 수 있습니다.

본인의 Linux 환경에서 확인한 것은, 주석을 포함한 JSON은 유효하지 않다는 점(위의 json.load가 그 즉시 실패함)과, 복구 및 예방 절차가 성립한다는 점입니다. 재시작 시 실제로 빈 파일로 덮어씌워지는 순간은 실제 사용 중인 설정을 파괴할 위험이 있어 재현하지 않았습니다. 보고된 동작으로 취급하고 있습니다. 또한 "망가진 입력값으로 묵묵히 덮어쓰는" 동작 자체는 본래 Anthropic 측에서 수정해야 할 애플리케이션의 버그입니다(검증 후 작성하거나, 망가져 있다면 중단하도록 설계되어야 합니다). 이용자 측에서 할 수 있는 것은 위의 두 가지 습관을 통해 피해를 제로로 만드는 것입니다.

이 사고는 Write의 전체 치환으로 상태 파일이 사라지는 유형이나, git stash를 통한 백업을 버려버리는 유형과 마찬가지로, "일상에서 가장 무해해 보이는 조작"이 데이터 소실의 트리거가 되는 계통 중 하나입니다. 이러한 "설정으로 미리 방지할 수 있는 사고"를, 실제 기기에서 검증한 탐지, 복구, 예방의 형태로 하나씩 모은 가이드를 공개하고 있습니다.

• 무료 hook 모음 (MIT · 약 800건): cc-safe-setup (GitHub)
• 체계적으로 읽으려면: Claude Code 사고 방지 가이드 (Zenn · 총 43장 · ¥800) —— 본 기사의 .claude.json 사고도 데이터 소실, 폭주, 무단 과금 사고와 함께 증상별로 정리되어 있습니다.