클로드 코드(Claude Code)에서 MCP 서버를 추가하다 보면 의외로 막히는 지점이 있습니다. 분명 추가했는데 다른 프로젝트에서는 안 보이거나, 팀원에게 공유했더니 “안 뜬다”는 답이 돌아오거나, 어디에 깔린 건지 본인도 헷갈릴 때입니다. 원인은 거의 항상 설정 파일 위치(scope)를 잘못 잡았기 때문입니다. 클로드 코드의 MCP 설정은 위치 세 곳이 분명히 구분되어 있고, 어디에 두느냐에 따라 적용 범위와 공유 방식이 완전히 달라집니다. 위치별 차이부터 추가·확인 명령까지 한 번에 정리해 드립니다.
목차
한눈에 보는 MCP 설정 위치 3가지
클로드 코드는 MCP 서버 설정을 세 가지 scope로 나눠서 관리합니다. 어디에 둘지부터 정확히 정해 두시면 이후 운영이 훨씬 수월해집니다.
| 구분 | local (기본값) | user | project |
|---|---|---|---|
| 적용 범위 | 현재 프로젝트, 본인만 | 모든 프로젝트, 본인만 | 해당 프로젝트, 팀 전체 |
| 저장 파일 | .claude/settings.local.json | ~/.claude.json (또는 ~/.claude/settings.json) | .mcp.json (프로젝트 루트) |
| 버전 관리 | 커밋 안 함 (.gitignore) | 본인 머신에만 존재 | Git 커밋해 팀과 공유 |
| 대표 용도 | 임시 테스트, 개인 오버라이드 | 자주 쓰는 개인 서버 | 팀 공통 도구 |
| scope 우선순위 | 가장 높음 | 가장 낮음 | 중간 |
한 줄로 정리하시면, 혼자 잠깐 쓰면 local, 모든 프로젝트에서 쓰면 user, 팀 공유는 project입니다. 공식 문서는 Claude Code MCP 문서에서 확인하실 수 있습니다.
local scope: 가장 간단한 시작점
아무 옵션 없이 추가하면 local scope로 들어갑니다. 본인의 현재 프로젝트에서만 동작하고, Git에는 올라가지 않습니다.
claude mcp add my-server -- npx my-mcp-package
위 명령은 --scope local을 명시하지 않은 것과 동일합니다. 새 MCP 서버를 처음 시도할 때, 또는 본인 프로젝트에서만 잠깐 써 볼 때 가장 부담이 적은 선택입니다. 설정은 해당 프로젝트의 .claude/settings.local.json에 들어가므로, 다른 프로젝트로 옮기면 따라가지 않습니다.
user scope: 본인의 모든 프로젝트에서 쓰고 싶을 때
자주 쓰는 MCP 서버라면 user scope가 답입니다. 한 번 추가하면 본인의 어떤 프로젝트에서든 동일하게 호출됩니다.
claude mcp add --scope user my-server -- npx my-mcp-package
설정은 홈 디렉터리의 ~/.claude.json에 저장됩니다. 본인 머신에만 존재하므로 팀과 공유되지 않습니다. 깃허브 연동, 일반 검색, 자주 쓰는 데이터 조회처럼 “어느 프로젝트에서든 항상 켜져 있길 바라는 도구”를 user scope에 두시는 것이 자연스럽습니다.
project scope: 팀과 함께 쓰는 도구
해당 저장소에서 작업하는 모든 사람이 동일한 MCP 서버를 쓰도록 만들고 싶으시면 project scope를 사용하십시오. 설정 파일이 프로젝트 루트의 .mcp.json에 저장되며, Git에 커밋해 팀과 공유합니다.
claude mcp add --scope project my-team-server -- npx my-mcp-package
새로 합류한 팀원이 저장소를 클론하면 클로드 코드가 자동으로 .mcp.json을 인식하고 같은 MCP 서버를 사용할 수 있게 됩니다. 사내 DB 조회 도구, 프로젝트 전용 모니터링 연동, 사내 위키 검색 같은 “프로젝트와 묶여 있는 도구”를 둘 자리입니다.
scope가 충돌할 때의 우선순위
같은 이름의 MCP 서버가 여러 위치에 존재하면 scope 간 우선순위에 따라 한 가지가 적용됩니다. 클로드 코드는 일반적으로 다음 순서를 따릅니다.
- 1. 조직(Managed) 설정 — 회사가 통제하는 정책
- 2. 명령행 인자(CLI 옵션) — 해당 세션 한정
- 3. 프로젝트 로컬 오버라이드 —
.claude/settings.local.json - 4. 프로젝트 공유 설정 —
.claude/settings.json,.mcp.json - 5. 사용자 글로벌 설정 —
~/.claude.json - 6. 빌트인 기본값
핵심은 “더 좁은 scope가 더 넓은 scope를 덮어쓴다”입니다. 같은 이름의 서버를 user와 project 양쪽에 두면 project 쪽이 적용되고, project와 local에 같이 두면 local이 적용됩니다. 의도와 다른 서버가 잡힌다면 가장 먼저 우선순위 충돌부터 의심해 보십시오.
현재 등록된 MCP 서버 확인하는 법
설정이 제대로 들어갔는지, 어떤 scope로 들어갔는지는 한 줄 명령으로 확인할 수 있습니다.
claude mcp list
이 명령은 현재 활성화된 MCP 서버와 scope를 함께 보여 줍니다. 추가했는데 안 보인다면 scope를 잘못 지정했거나, 다른 프로젝트 디렉터리에 들어가 있을 가능성이 큽니다.
서버 정보가 잘못 들어갔다면 다음으로 제거할 수 있습니다.
claude mcp remove 서버이름
scope가 헷갈릴 때는 --scope 옵션을 함께 지정해 정확한 위치에서 제거하시는 편이 안전합니다.
설정 파일 직접 편집해도 되나요
가능합니다. 다만 권장은 claude mcp 명령을 통한 추가·삭제입니다. 직접 편집할 때 주의할 점은 다음과 같습니다.
- JSON 문법 오류: 마지막 콤마, 중괄호 짝, 따옴표 등 사소한 문법 오류 하나로 클로드 코드 실행이 막힐 수 있습니다.
- 경로와 따옴표: Windows 경로의 백슬래시는 JSON에서 이스케이프(
\\) 처리해야 합니다. - API 키 노출:
.mcp.json은 Git에 커밋되는 파일이므로 환경변수(${MY_API_KEY}) 형태로 빼두시는 것이 안전합니다. 키를 그대로 적어 두면 그대로 저장소에 노출됩니다. - 설정 후 재시작: 새 서버를 추가하면 클로드 코드 세션을 한 번 재시작해야 안정적으로 인식됩니다.
실무에서 흔한 시나리오 4가지
각 scope를 언제 써야 할지 헷갈리실 때 참고하시면 좋은 패턴입니다.
- “사내 DB 조회 도구를 우리 팀 모두에게 깔고 싶다” → project scope,
.mcp.json커밋 - “내 깃허브 토큰으로 깃허브 MCP를 항상 쓰고 싶다” → user scope
- “새 MCP를 잠깐 테스트해 보고 싶다” → local scope (기본값)
- “팀 공통 도구지만 내 머신에서는 다른 옵션으로 띄우고 싶다” → project로 기본값을 두고, local에 동일 이름으로 오버라이드
안 보일 때 점검 순서
“분명 등록했는데 안 뜬다”는 상황에서 빠르게 원인을 좁히는 방법입니다.
- 1. 현재 작업 중인 디렉터리가 맞는지 확인 (다른 프로젝트로 들어가 있을 수 있음)
- 2.
claude mcp list로 등록 여부와 scope 확인 - 3. project scope라면
.mcp.json이 실제로 프로젝트 루트에 있는지 확인 - 4. 같은 이름의 서버가 여러 scope에 있는지(우선순위 충돌) 확인
- 5. 클로드 코드 세션을 완전히 재시작
- 6. 그래도 안 되면
claude --debug로 띄워 로드되는 MCP 서버 확인
자주 묻는 질문
같은 MCP를 user와 project 양쪽에 두면 어떻게 되나요?
project 쪽이 적용됩니다. 더 좁은 scope가 더 넓은 scope를 덮어쓰는 규칙 때문입니다. 의도적으로 user 설정을 쓰시려면 project 설정을 제거하시거나 다른 이름을 쓰셔야 합니다.
.mcp.json을 Git에 올렸는데 팀원에게는 안 보입니다.
두 가지를 확인하십시오. 첫째, 팀원이 저장소 루트에서 클로드 코드를 실행하고 있는지. 둘째, .mcp.json이 .gitignore에 잡혀 커밋되지 않았는지. 일부 템플릿이 .claude/ 전체를 무시하도록 설정되어 있는 경우가 있습니다.
API 키를 .mcp.json에 그대로 적어도 되나요?
권장하지 않습니다. ${API_KEY} 같은 환경변수 참조 형태로 분리하시고, 실제 값은 본인의 셸 환경 또는 .env에 두시는 것이 안전합니다.
local scope는 .claude/settings.local.json에 들어가는데, 이 파일은 다른 설정과 섞여 있어 헷갈립니다.
맞습니다. 같은 파일에 권한·환경변수·MCP 설정이 함께 저장되므로, 직접 편집보다는 가급적 claude mcp 명령을 통해 관리하시는 편이 실수 위험이 적습니다.
정리
클로드 코드의 MCP 설정은 local·user·project 세 위치만 정확히 구분하시면 헤맬 일이 줄어듭니다. 혼자 잠깐 쓸 것은 local, 모든 프로젝트에서 쓸 것은 user, 팀과 공유할 것은 project에 두십시오. 추가는 claude mcp add --scope ..., 확인은 claude mcp list 한 줄이면 충분합니다. 같은 이름이 여러 scope에 있을 때 좁은 쪽이 우선한다는 규칙만 기억하시면 충돌 상황도 빠르게 정리됩니다.