Claude Code에 MCP 서버 연결하기: local·project·user 범위와 .mcp.json 관리

Claude Code에 MCP 서버를 하나 붙이는 일은 명령 한 줄이면 끝나지만, 팀에서 쓰기 시작하면 질문이 생긴다. 이 설정이 내 컴퓨터에만 있는지 저장소에 공유되는지, 토큰은 어디에 두는지, 팀원이 받은 설정이 왜 바로 동작하지 않는지. 이 글은 Claude Code MCP 문서를 기준으로 범위 세 가지의 차이와 .mcp.json을 팀 저장소에서 관리하는 방법을 정리한다. 읽고 나면 개인용·팀 공유용·전역 서버를 구분해 등록하고 비밀값을 커밋하지 않는 구성을 만들 수 있다.

전송 방식별 등록 명령

# 원격 HTTP 서버
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 헤더가 필요한 HTTP 서버
claude mcp add --transport http internal-api https://mcp.example.com/mcp \
  --header "Authorization: Bearer $INTERNAL_TOKEN"

# 로컬 stdio 서버: -- 뒤가 실행 명령
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=$AIRTABLE_API_KEY \
  -- npx -y airtable-mcp-server

# 확인·조회·삭제
claude mcp list
claude mcp get airtable
claude mcp remove airtable

stdio 서버에서 --는 생략할 수 없다. 이 구분자가 없으면 서버 명령의 -y 같은 옵션을 Claude Code가 자기 옵션으로 해석한다. 이미 Claude Desktop에 등록한 서버가 있다면 claude mcp add-from-claude-desktop으로 가져올 수 있고, JSON 한 덩어리로 넣으려면 claude mcp add-json을 쓴다.

세 가지 범위와 우선순위

--scope(-s)를 생략하면 local로 등록된다.

같은 이름의 서버가 여러 범위에 있으면 local → project → user → 플러그인 제공 서버 → claude.ai 커넥터 순으로 앞의 것이 쓰인다. 이 순서를 이용하면 팀 공용 .mcp.json의 설정을 개인 local 설정으로 덮어써 테스트할 수 있다. 반대로 팀원이 예전에 같은 이름으로 local 등록해 둔 서버가 있으면 저장소의 새 설정이 무시되므로, "나만 안 된다"는 문의가 오면 claude mcp get <이름>으로 어느 범위 설정이 적용됐는지부터 확인한다.

팀 공유용 .mcp.json 작성하기

project 범위로 등록하면 .mcp.json이 생기고 이 파일을 커밋한다. 토큰을 파일에 직접 쓰지 않도록 문서가 지원하는 환경 변수 확장을 쓴다. ${VAR}는 환경 변수 값으로, ${VAR:-기본값}은 변수가 없을 때 기본값으로 바뀐다. 확장은 stdio 서버의 command·args·env, HTTP 서버의 url·headers에서 동작한다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
    },
    "internal-docs": {
      "type": "http",
      "url": "${DOCS_MCP_URL:-https://docs-mcp.internal.example.com}/mcp",
      "timeout": 600000
    },
    "db-readonly": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@example/postgres-mcp", "--read-only"],
      "env": { "DATABASE_URL": "${READONLY_DATABASE_URL}" }
    }
  }
}

문서에는 보안상 원격 서버의 url·headers에서 빈 값으로 처리되는 변수 목록도 있다. ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, HTTPS_PROXY, NPM_TOKEN 등은 원격 서버로 새어 나가지 않도록 확장되지 않는다. 헤더에 이런 이름의 변수를 쓰고 인증이 안 된다면 전용 변수 이름으로 바꾼다.

저장소 README에는 필요한 환경 변수 이름과 발급 방법을 적어 둔다. 데이터베이스 서버를 공유한다면 읽기 전용 계정을 쓰는 이유와 설정은 데이터베이스 MCP 서버 보안을, 저장소의 다른 비밀값을 AI 도구가 읽지 못하게 막는 방법은 시크릿·.env 차단 설정을 참고한다.

팀원이 처음 받았을 때의 승인 절차

.mcp.json의 서버는 대화형 세션에서 처음 쓰기 전에 승인을 요구한다. 저장소에 누군가 추가한 서버가 사용자 모르게 실행되지 않게 하는 장치다. 승인 선택을 되돌리려면 다음을 실행한다.

claude mcp reset-project-choices

문서에 따르면 claude -p 비대화형 실행, Agent SDK 세션, 클라우드 세션, --strict-mcp-config 세션 등에서는 이 승인 단계가 생략된다. CI에서 Claude Code를 돌린다면 저장소의 .mcp.json 서버가 승인 없이 실행된다는 뜻이므로, PR에서 .mcp.json 변경을 CODEOWNERS 리뷰 대상으로 지정해 두는 것이 안전하다.

느린 서버와 큰 응답 다루기

출력 한도를 무작정 올리기보다 도구가 반환하는 양을 줄이는 쪽이 컨텍스트 사용량에도 유리하다. 문서에 따르면 5만 자를 넘는 텍스트 결과는 파일로 저장되고, 1만1천 자를 넘는 오류 메시지는 앞뒤 5천 자만 남는다.

연결이 안 될 때 확인 순서

1. 세션 안에서 /mcp로 서버 상태와 오류 메시지를 본다.
2. claude mcp get <이름>으로 어느 범위 설정이 적용됐는지, 명령·URL이 의도대로 확장됐는지 확인한다.
3. 환경 변수가 Claude Code를 실행한 셸에 실제로 있는지 확인한다. 토큰 끝에 줄바꿈이 섞이면 Claude Code가 공백 경고를 띄운다.
4. stdio 서버라면 등록한 명령을 터미널에서 직접 실행해 본다. 서버 자체 문제는 MCP Inspector로 분리해 확인한다.

GitHub 서버를 예로 한 전체 연결 과정은 GitHub MCP 서버로 이슈·PR·코드 검색 연결하기에서 볼 수 있다.