설정 스코프
MCP 서버를 추가할 때 가장 자주 틀리는 결정이 "어느 스코프에 넣을 것인가"다. Claude Code는 서버를 세 가지 스코프로 등록할 수 있고, 스코프는 두 가지를 동시에 결정한다. 어떤 프로젝트에서 그 서버가 로드되는지, 그리고 설정이 팀과 공유되는지다. claude mcp add에 --scope 옵션으로 지정한다.
- 로컬(local)은 기본 스코프다. 서버를 추가한 그 프로젝트에서만 로드되고, 나에게만 보이며 다른 사람과 공유되지 않는다. 개인 실험용 서버나 공유하고 싶지 않은 자격증명이 든 서버에 쓴다.
- 프로젝트(project)는 프로젝트 루트의
.mcp.json에 기록된다. 이 파일을 깃에 커밋하면 팀 전체가 같은 서버 구성을 공유한다. "우리 팀 모두가 이 DB 서버를 써야 한다"가 프로젝트 스코프의 전형적 상황이다. - 사용자(user)는 내 모든 프로젝트에서 전역으로 로드된다. 어느 프로젝트에서 작업하든 항상 붙어 있어야 하는 개인 도구에 쓴다.
여기서 시험이 노리는 결정적 함정은 저장 위치다. 직관적으로는 "로컬은 .mcp.json, 프로젝트도 .mcp.json"이라고 착각하기 쉽지만 틀렸다. 정확한 매핑은 다음과 같다.
.mcp.json(프로젝트 루트, 커밋 대상)을 쓰는 것은 프로젝트 스코프 하나뿐이다.- 로컬 스코프와 사용자 스코프는 모두 홈 디렉터리의
~/.claude.json에 저장된다. 로컬은 그 프로젝트 경로를 키로 묶어 해당 프로젝트에서만 보이게 하고, 사용자는 전역 항목으로 둬 모든 프로젝트에서 보이게 한다.
# 터미널: 로컬 스코프 (기본값, 나에게만, 이 프로젝트만)claude mcp add my-tool -- npx -y some-mcp-server# 터미널: 프로젝트 스코프 (.mcp.json에 기록, 팀 공유)claude mcp add --scope project team-db --transport stdio -- npx -y mcp-server-sqlite ./data.db# 터미널: 사용자 스코프 (~/.claude.json 전역, 내 모든 프로젝트)claude mcp add --scope user my-search --transport http https://mcp.example.com/mcp즉 "로컬과 사용자가 같은 파일(~/.claude.json)에 들어가고, 프로젝트만 .mcp.json을 쓴다"가 이 절의 한 줄 요약이다. "로컬 스코프 서버는 .mcp.json에 저장된다"는 보기는 틀린 보기다.
선택 기준도 의사결정형으로 정리해 두자. 자격증명이 들어가거나 나만 쓰는 실험 서버는 로컬, 팀이 공유해야 하면 프로젝트, 어느 프로젝트에서나 항상 필요하면 사용자다. 비밀값이 든 서버를 프로젝트 스코프로 커밋하면 키가 저장소에 노출되므로, 그런 서버는 로컬에 두거나 환경변수 보간을 써야 한다. "민감 토큰이 든 서버를 팀과 공유하라"는 보기는 보안상 정답이 될 수 없다.
우선순위도 함께 묻는다. 같은 이름의 서버가 여러 스코프에 정의되면 더 좁고 구체적인 쪽이 이긴다. 일반적으로 로컬·프로젝트(즉 그 프로젝트에 한정된 설정)가 전역인 사용자 스코프보다 우선한다. 실무에서 "사용자 스코프에 넣었는데 어떤 프로젝트에서 다르게 동작한다"면, 그 프로젝트의 더 좁은 설정이 사용자 설정을 가리고 있을 가능성을 의심해야 한다. 핵심 원칙은 "좁은 스코프가 넓은 스코프를 덮어쓴다"이며, 이는 9장에서 본 settings.json·CLAUDE.md의 우선순위 원칙과 같은 결을 이룬다.
정리
- 스코프는 로컬(기본·개인·해당 프로젝트)·프로젝트(
.mcp.json·팀 공유)·사용자(전역·모든 프로젝트) 셋이며,--scope로 지정한다. - 저장 위치가 핵심 함정이다.
.mcp.json은 프로젝트 스코프 전용이고, 로컬과 사용자는 모두~/.claude.json에 저장된다. - 선택은 의사결정형이다. 비밀값·실험은 로컬, 팀 공유는 프로젝트, 어디서나 필요하면 사용자. 민감 토큰 서버를 프로젝트로 커밋하는 것은 안티패턴이다.
- 같은 이름이 충돌하면 더 좁은 스코프가 넓은 스코프를 덮어쓴다. 로컬·프로젝트가 사용자(전역)보다 우선한다.