Claude Code MCP 스코프 정리

이 글에서 다루는 내용

이 글에서는 Claude Code에서 MCP 서버를 추가할 때 고르게 되는 세 가지 스코프(Local, Project, User)가 각각 무엇인지, 그리고 그 설정이 실제로 어느 파일에 어떻게 저장되는지를 정리합니다. Local과 User가 같은 ~/.claude.json 파일을 쓰면서도 어떻게 구분되는지, projects 키가 왜 절대 경로인지, ~/.claude.json과 .mcp.json의 JSON 형식이 어떻게 다른지를 실제 샘플과 함께 살펴봅니다. 마지막으로 각 스코프별로 조회·추가·삭제·변경을 하는 CLI 명령어까지 한 번에 정리합니다.

MCP 스코프란

MCP(Model Context Protocol) 서버를 Claude Code에 연결할 때, 그 설정을 "어디까지 적용할지" 정하는 것이 스코프입니다. claude mcp add 명령에 --scope(축약 -s) 플래그로 지정하며, 생략하면 기본값은 Local입니다. 핵심 세 가지는 다음과 같습니다.

Local (기본값)

현재 프로젝트에서 나에게만 보이는 비공개 스코프입니다. 새 MCP 서버를 팀에 공유하기 전에 혼자 실험하거나 테스트할 때 적합합니다. 스코프를 생략하면 자동으로 적용됩니다.

Project

레포 루트의 .mcp.json에 저장되고 버전 관리(git)에 커밋되는 스코프입니다. 팀 표준 도구처럼 모든 팀원이 동일하게 써야 하는 서버에 사용합니다. 단, 모두에게 공유되므로 비밀값은 직접 넣지 말고 환경변수 참조를 쓰는 것이 안전합니다.

User (글로벌)

내 모든 프로젝트에서 사용 가능한 개인 전역 스코프입니다. 개인용 노트 시스템이나 자주 쓰는 개발 도구처럼 어디서든 필요한 서버에 적합합니다.

스코프별 저장 경로

세 스코프의 저장 위치와 공유 범위를 정리하면 다음과 같습니다.

스코프	플래그	저장 경로	공유 범위
Local (기본값)	-s local	~/.claude.json (프로젝트 경로별 저장)	현재 프로젝트, 비공개
Project	-s project	.mcp.json (레포 루트, git 커밋)	팀 전체 공유
User (글로벌)	-s user	~/.claude.json (전역 저장)	내 모든 프로젝트

Local과 User는 왜 경로가 같을까

Local과 User는 둘 다 물리적으로 같은 파일인 ~/.claude.json에 저장됩니다. 차이는 파일 안에서 어떻게 구조화되느냐에 있습니다. ~/.claude.json 하나에 여러 영역이 나뉘어 있는데, User는 파일 최상위에, Local은 projects 아래 프로젝트 경로별로 들어갑니다.

{
  // User 스코프: 최상위 → 모든 프로젝트에서 보임
  "mcpServers": {
    "my-global-tool": { }
  },

  // Local 스코프: projects 아래 프로젝트 경로를 키로 저장
  "projects": {
    "/Users/me/repo-a": {
      "mcpServers": {
        "experiment-tool": { }   // repo-a 에서만 보임
      }
    },
    "/Users/me/repo-b": {
      "mcpServers": { }          // repo-b 에서만 보임
    }
  }
}

즉 "같은 파일"이지만 저장되는 위치(키)와 적용 범위가 다른 셈입니다.

projects 키는 절대 경로다

projects 아래의 키는 Claude Code를 실행한 작업 디렉터리(보통 레포 루트)의 절대 경로(absolute path)입니다. 이 구조 때문에 몇 가지 실무적인 특징이 생깁니다.

경로가 곧 식별자이므로, 디렉터리를 옮기거나 이름을 바꾸면 Claude Code는 그것을 다른 프로젝트로 인식합니다. 기존 경로에 저장됐던 Local 스코프 MCP 설정, 허용된 도구(allowedTools), trust 설정 등이 따라오지 않습니다. 또한 MCP 서버뿐 아니라 그 프로젝트의 여러 상태(허용 도구 목록, 신뢰 설정, 캐시 등)도 이 경로 키 아래에 함께 저장됩니다. 심볼릭 링크나 다른 마운트 경로로 같은 레포에 접근하면 경로 문자열이 달라져 별개 프로젝트처럼 취급될 수 있으니, 항상 같은 경로로 접근하는 것이 안전합니다.

두 파일의 JSON 형식 차이

서버 정의 블록 자체는 동일한 형식이지만, 그것을 감싸는 구조(중첩 위치)가 다릅니다.

.mcp.json(Project 스코프)은 mcpServers가 파일 최상위에 바로 옵니다. MCP 전용 파일이라 구조가 단순합니다.

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

반면 ~/.claude.json(User + Local 스코프)은 MCP 전용이 아니라 Claude Code의 종합 설정 파일이라, mcpServers가 두 군데에 중첩되어 들어갑니다.

{
  "numStartups": 34,
  "theme": "dark",
  "oauthAccount": { },            // MCP와 무관한 다른 설정들

  "mcpServers": {                 // User 스코프 (최상위)
    "global-tool": { }
  },

  "projects": {
    "/home/me/repo-a": {
      "allowedTools": [],
      "history": [ ],
      "mcpServers": {             // Local 스코프 (projects 경로 아래 중첩)
        "experiment-tool": { }
      }
    }
  }
}

구분	.mcp.json	~/.claude.json
용도	MCP 서버 전용	Claude Code 전체 설정 (MCP는 일부)
mcpServers 위치	파일 최상위 1곳	최상위(user) + projects.<경로> 아래(local)
그 외 필드	없음	OAuth 세션, 테마, 히스토리, 캐시 등 다수

두 파일 샘플 JSON

Project 스코프 — .mcp.json

프로젝트 루트에 두고 git에 커밋하는 파일입니다. stdio 방식(로컬 프로세스 실행)과 http 방식(원격 서버 연결)을 함께 담을 수 있습니다.

{
  "mcpServers": {
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "${DB_URL}"],
      "env": {
        "DB_URL": "${DATABASE_URL}"   // 환경변수 참조 → 비밀값을 파일에 직접 안 넣음
      }
    },
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    }
  }
}

command/args/env는 stdio 서버용, url은 http/원격 서버용입니다. git에 커밋되어 팀 전원이 공유하므로 ${VAR} 또는 ${VAR:-기본값} 형태의 환경변수 확장으로 비밀값을 파일 밖으로 빼는 것이 좋습니다.

User + Local 스코프 — ~/.claude.json

홈 디렉터리에 있는 종합 설정 파일입니다. 최상위 mcpServers가 User 스코프, projects.<경로>.mcpServers가 Local 스코프입니다.

{
  "numStartups": 34,
  "theme": "dark",
  "oauthAccount": { "emailAddress": "me@example.com" },

  "mcpServers": {                 // User 스코프
    "my-notes": {
      "type": "stdio",
      "command": "node",
      "args": ["/Users/me/tools/notes-mcp/server.js"]
    }
  },

  "projects": {
    "/Users/me/work/repo-a": {
      "allowedTools": [],
      "history": [],
      "mcpServers": {             // Local 스코프
        "experiment-db": {
          "type": "stdio",
          "command": "node",
          "args": ["./local-server.js"]
        }
      }
    }
  }
}

스코프별 조회·추가·삭제·변경 명령어

Claude Code의 MCP CLI는 추가·조회·삭제 명령은 있지만 "변경" 전용 명령은 없습니다. 변경은 보통 같은 이름으로 다시 추가(덮어쓰기)하거나 파일을 직접 편집합니다.

추가 (Add)

# Local (기본값)
claude mcp add --transport http stripe https://mcp.stripe.com

# Project (팀 공유, .mcp.json)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# User (모든 프로젝트)
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

# JSON으로 한 번에
claude mcp add-json weather-api '{"type":"http","url":"https://api.weather.com/mcp"}' --scope user

조회 (Query)

조회 명령은 스코프별 필터가 따로 없고, 현재 컨텍스트에서 보이는 서버를 한꺼번에 보여줍니다.

claude mcp list          # 전체 목록 (모든 스코프 통합)
claude mcp get github    # 특정 서버 상세

삭제 (Delete)

claude mcp remove github

같은 이름의 서버가 여러 곳에 정의되면 우선순위 순으로 가장 높은 소스의 정의가 사용됩니다. Project 스코프 서버는 .mcp.json에서 항목을 직접 지우는 것이 가장 확실합니다.

변경 (Modify)

전용 edit 명령이 없으므로 두 가지 방법을 씁니다. 같은 이름·같은 스코프로 다시 add 하거나(덮어쓰기), 스코프별 파일을 직접 편집합니다.

claude mcp remove stripe
claude mcp add --transport http stripe --scope user https://mcp.stripe.com

요약 표

작업	명령	스코프 지정
추가	claude mcp add ... / claude mcp add-json ...	`--scope local
조회(목록)	claude mcp list	스코프 필터 없음, 통합 표시
조회(상세)	claude mcp get <name>	—
삭제	claude mcp remove <name>	우선순위 기반 / project는 파일 직접 편집 권장
변경	동일 이름 재추가 또는 파일 직접 편집	재추가 시 add의 --scope 따름

한 가지 주의점은 --transport, --env, --scope, --header 같은 옵션은 모두 서버 이름 앞에 와야 하고, --(이중 대시)로 서버에 넘길 실제 명령·인자를 분리한다는 점입니다. 예를 들어 stdio 서버는 claude mcp add --scope user myserver -- npx server 형태가 됩니다.