Claude Code MCP 설정: claude mcp add·스코프·전송 방식 완전 정리

Claude Code(터미널 CLI)에서 MCP 서버를 붙이면 GitHub·DB·브라우저 같은 외부 도구를 Claude가 직접 다룰 수 있습니다. 이 글은 앱/데스크톱 연결 개요(별도 글)와 달리, Claude Code CLI에서 서버를 추가·관리하는 법을 스코프·전송 방식 중심으로 정리합니다. (기준 시점: 2026년 6월, 출처: Claude Code 공식 문서 "Connect Claude Code to tools via MCP")

먼저 정할 것 — 스코프 3가지

MCP 서버는 세 가지 스코프로 설정할 수 있고, 스코프가 "어느 프로젝트에서 로드되는지"와 "팀과 공유되는지"를 결정합니다.

• local(기본값): 추가한 프로젝트에서만 로드되고 나에게만 보입니다. Claude Code가 ~/.claude.json에 해당 프로젝트 경로 아래 저장합니다.
• project: 프로젝트 루트의 .mcp.json에 저장되어 git에 커밋할 수 있습니다. 저장소를 클론한 팀원 모두가 같은 서버 설정을 갖게 됩니다.
• user: 내 모든 프로젝트에서 쓸 수 있는 전역 설정입니다(역시 ~/.claude.json에 저장).

local·user는 각 기기의 ~/.claude.json에 저장되어 동기화되지 않습니다. 팀과 동일 설정을 공유하려면 project 스코프 + .mcp.json 커밋이 정석입니다. 관리자는 엔터프라이즈 레벨에서 managed configuration으로 서버를 배포할 수도 있습니다.

서버 추가에서 사용까지

기본 추가 명령은 claude mcp add이며, 전송 방식과 스코프를 함께 지정합니다.

# local 스코프(기본) + http 전송
claude mcp add --transport http stripe https://mcp.stripe.com

# 스코프를 명시
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

이미 JSON 설정이 있으면 claude mcp add-json으로 그대로 추가할 수 있습니다. 추가 후에는 claude mcp list로 전체 목록을, claude mcp get <이름>으로 특정 서버의 상태·세부를 확인합니다. 인증이 필요한 서버는 세션 안에서 /mcp 슬래시 명령으로 상태를 보고 OAuth 인증을 처리합니다.

stdio 서버의 도구는 세션 시작 시점에 발견됩니다. 세션 도중에 서버를 추가했다면 새 세션을 시작해야 도구가 잡힙니다.

전송 방식 — stdio와 http

전송 방식은 두 가지입니다. stdio 서버는 내 컴퓨터에서 로컬 프로세스로 실행되며, 직접 시스템 접근이나 커스텀 스크립트에 적합합니다. Claude Code는 이 프로세스 환경에 CLAUDE_PROJECT_DIR(프로젝트 루트)를 주입하므로, 서버가 작업 디렉터리에 의존하지 않고도 프로젝트 기준 경로를 해석할 수 있습니다(Node는 process.env.CLAUDE_PROJECT_DIR, Python은 os.environ["CLAUDE_PROJECT_DIR"]).

http 서버는 원격 서비스에 연결하며 로컬 프로세스가 필요 없습니다. 과거의 SSE 전송은 deprecated되었으니, 연결 오류가 난다면 --transport sse 대신 --transport http(streamable HTTP)로 전환하세요.

자주 쓰는 명령과 주의점

Claude Code는 MCP 관련으로 claude mcp add, claude mcp list, claude mcp get, claude mcp remove, claude mcp add-json, claude mcp add-from-claude-desktop, claude mcp serve 등을 제공합니다. 세션 안에서는 /mcp로 서버 상태와 OAuth 인증을 다룹니다.

흔한 실수는 설정 변경 후 재시작을 잊는 것입니다. .mcp.json을 직접 편집하거나 참조된 환경변수를 바꿔도 현재 실행 중인 세션에는 반영되지 않습니다. 변경 뒤에는 Claude Code를 재시작하거나, 최소한 /mcp로 해당 서버를 끊고 다시 연결하세요. 서버를 여러 개 붙여도 됩니다 — Tool Search가 기본 활성이라 도구 정의 로딩을 지연시켜 서버가 늘어도 컨텍스트 영향이 적습니다.

함께 보면 좋은 글

MCP 개념은 MCP란 무엇인가, 앱·데스크톱 등 4가지 연결 방법 개요는 MCP 연결·사용법, 용도별 서버는 추천 MCP 서버에서 다룹니다.