claude mcp add 로 등록했는데 목록에 안 보인다 — 기본 scope 는 local

MCP 서버를 등록했다. 성공 메시지가 떴다. 그런데 목록에 없다.

$ claude mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse
# 같은 셸에서
$ claude mcp list
# atlassian 없음

새 세션에서 mcp__atlassian__* 도구도 노출되지 않는다. 사용자 설정 파일을 뒤져도 없다.

$ jq '.mcpServers | keys' ~/.claude/.claude.json
# atlassian 없음

등록이 실패한 것처럼 보이지만 아니다. 다른 곳에 저장돼 있다.

원인 — 기본 scope 가 local

$ claude mcp add --help | grep -A2 scope
  -s, --scope <scope>  Configuration scope (local, user, or project) (default: "local")

local 은 project-level, 즉 cwd 별이다. 등록 내용은 여기 들어간다.

~/.claude/.claude.json → projects."<cwd>".mcpServers

그 cwd 에서 연 세션에서만 노출된다. 다른 디렉터리에서 열면 안 보이고, 최상위 mcpServers 를 조회해도 안 나온다.

어디 들어갔는지 확인하려면 이렇게 찾는다.

$ jq '[.projects | to_entries[] | select(.value.mcpServers | has("atlassian"))] | .[].key' ~/.claude/.claude.json
"/home/user"    # 홈 디렉터리에서 add 한 경우

projects."<cwd>".mcpServers.<name> 에 있으면 local scope 다. 홈에서 등록했다면 홈에서 연 세션에서만 보인다. 프로젝트 디렉터리로 들어가는 순간 사라진다.

증상이 “등록이 안 됐다”로 보이는 이유가 이것이다. 사람은 보통 홈에서 등록하고 프로젝트에서 쓴다.

해결 — `--scope user`

claude mcp add --scope user --transport sse atlassian https://mcp.atlassian.com/v1/sse

user scope 는 ~/.claude/.claude.json 의 최상위 mcpServers 에 들어간다. 모든 cwd, 모든 세션에서 노출된다.

특정 프로젝트에서만 쓸 MCP 가 아니라면 항상 이쪽이다. 나는 이후로 --scope user 를 습관처럼 붙인다.

잘못 등록된 것 옮기기

local 로 들어간 걸 user 로 옮기려면 두 단계다.

# 1. local 제거 — 등록했던 그 cwd 로 이동해야 한다
cd /home/user
claude mcp remove atlassian

# 2. user 로 재등록 — 어디서 실행해도 된다
claude mcp add --scope user --transport sse atlassian https://mcp.atlassian.com/v1/sse

1번에서 cd 를 빼먹으면 “그런 서버 없다”는 말을 듣는다. local 항목은 그 cwd 컨텍스트에서만 보이기 때문이다. 위의 jq 명령으로 어느 디렉터리에 들어갔는지 먼저 찾는 게 확실하다.

OAuth 는 다시 해야 한다. scope 를 옮겨도 인증이 따라오지 않는다. /mcp → 서버 선택 → 브라우저 OAuth 를 다시 진행한다.

설정 디렉터리를 여러 개 쓰는 경우

용도별로 CLAUDE_CONFIG_DIR 을 나눠 쓴다면, MCP 등록도 디렉터리별로 따로 해야 한다. --scope user 는 그 config dir 안에서의 user 를 뜻한다.

# 기본 설정
claude mcp add --scope user --transport sse atlassian https://mcp.atlassian.com/v1/sse

# 별도 설정 디렉터리
CLAUDE_CONFIG_DIR=~/.claude-alt claude mcp add --scope user --transport sse atlassian https://mcp.atlassian.com/v1/sse

OAuth 토큰도 디렉터리별로 별도다. 이건 불편이 아니라 요구사항이다. 계정을 분리하려고 config dir 을 나눈 건데 자격증명이 섞이면 분리의 의미가 없다.

정리

claude mcp list 에 안 보인다고 등록에 실패한 게 아니다. 어느 scope 에 들어갔는지부터 확인한다.

jq '[.projects | to_entries[] | select(.value.mcpServers | has("<name>"))] | .[].key' ~/.claude/.claude.json

여기서 경로가 나오면 local 이다. 그리고 앞으로는 --scope user 를 기본으로 친다.

원인 — 기본 scope 가 local

해결 — --scope user

잘못 등록된 것 옮기기

설정 디렉터리를 여러 개 쓰는 경우

정리

해결 — `--scope user`