Claude Code에 MCP 서버 연동하기 - 외부 도구를 붙여 쓴 기록

Claude Code에 MCP 서버 연동하기 - 외부 도구를 붙여 쓴 기록

개발 도구 사용기

공식 문서와 실제 연동 경험을 기준으로 정리했습니다.

Claude Code를 쓰다 보면 "이 작업까지 도구가 직접 해 주면 좋겠다" 싶은 순간이 옵니다. 브라우저를 열어 확인한다거나, 외부 서비스의 데이터를 가져온다거나 하는 일들입니다. 이때 쓰는 것이 MCP(Model Context Protocol) 서버 연동입니다. 이 글은 MCP가 무엇이고, 서버를 어떻게 추가·관리하는지를 공식 문서 기준으로 정리하고, 직접 붙여 쓰며 느낀 점을 덧붙인 기록입니다. 명령과 화면은 도구 버전에 따라 달라질 수 있으니, 정확한 내용은 본문에 적은 공식 문서를 함께 확인하시길 권합니다.

MCP가 무엇인가

MCP(Model Context Protocol)는 AI 도구와 외부 기능을 잇는 연동 표준입니다. MCP 서버를 하나 붙이면, 그 서버가 제공하는 도구·데이터를 Claude Code가 직접 불러 쓸 수 있게 됩니다. 예를 들어 파일 시스템 서버를 붙이면 파일을 읽고 쓰는 도구가, 브라우저 자동화 서버를 붙이면 페이지를 열어 확인하는 도구가 늘어나는 식입니다.

핵심은 "표준"이라는 점입니다. 서버마다 연결 방식을 새로 배우는 대신, 같은 방법으로 추가하고 같은 방법으로 관리합니다. 그래서 한 번 익혀 두면 다른 서버도 같은 흐름으로 붙일 수 있습니다.

서버를 추가하는 법

서버 추가는 claude mcp add 명령으로 합니다. 서버가 어디서 실행되느냐에 따라 전송 방식(transport)이 갈립니다.

전송 방식	쓰임
stdio	내 컴퓨터에서 프로세스로 실행하는 로컬 서버
HTTP	원격에 호스팅된 서버 (현재 권장 방식)
SSE	원격 서버용 옛 방식 (점차 HTTP로 대체)

로컬 프로세스(stdio) 서버를 붙일 때는 명령 앞에 -- 구분자를 꼭 넣습니다. 이 구분자 뒤의 내용을 전부 "실행할 서버 명령"으로 넘기기 때문입니다. 빠뜨리면 뒤따르는 옵션을 Claude Code가 자기 옵션으로 잘못 해석할 수 있습니다.

# 로컬(stdio) 서버 — '--' 뒤가 실행 명령
claude mcp add 파일서버 -- npx -y 서버패키지명

# 원격(HTTP) 서버
claude mcp add --transport http 서버이름 https://example.com/mcp

# 환경 변수와 함께 (예: API 키 전달)
claude mcp add --env API_KEY=값 서버이름 -- npx -y 서버패키지명

설정 범위 세 가지 — 어디까지 적용할까

같은 서버라도 "어디에 등록하느냐"에 따라 적용 범위가 달라집니다. 세 가지를 구분해 두면 개인용과 팀 공유용을 깔끔하게 나눌 수 있습니다.

범위	적용 대상	쓰기 좋은 경우
local (기본값)	현재 프로젝트, 나만	개인 실험·자격증명 포함 설정
project	현재 프로젝트, 팀 전체	.mcp.json으로 저장소에 공유
user	모든 프로젝트, 나만	어디서나 쓰는 개인 도구

범위는 --scope 플래그로 지정합니다. 생략하면 local입니다. 팀과 공유하려면 --scope project로 추가하는데, 이때 설정은 프로젝트 루트의 .mcp.json 파일에 저장되어 저장소에 함께 커밋됩니다. 모든 프로젝트에서 쓰고 싶다면 --scope user로 둡니다.

팀 공유용 .mcp.json 서버는 받는 사람 쪽에서 처음 쓸 때 한 번 승인을 거치도록 되어 있습니다. 출처를 모르는 서버가 자동으로 붙는 일을 막기 위한 안전장치라고 이해하면 됩니다.

연동한 도구는 어떻게 불리나

서버를 붙이면 그 서버가 제공하는 도구가 Claude Code 안에서 보이게 됩니다. 이때 이름이 서로 겹치지 않도록 서버 이름이 앞에 붙는 형태로 정리됩니다.

mcp__<서버이름>__<도구이름>
# 예) github 서버의 목록 조회 도구
mcp__github__list_prs

도구 외에 두 가지가 더 있습니다. 서버가 제공하는 리소스는 프롬프트 안에서 @서버이름:... 형태로 참조할 수 있고, 서버가 정의한 프롬프트는 /mcp__서버__프롬프트처럼 슬래시 명령으로 부를 수 있습니다. 도구·리소스·프롬프트 세 가지를 한 서버가 함께 제공할 수 있다는 점만 알아 두면 됩니다.

서버 관리 — 목록, 상태, 제거

붙인 서버는 명령으로 확인하고 정리합니다.

claude mcp list # 붙인 서버 목록
claude mcp get 서버이름 # 특정 서버 상세
claude mcp remove 서버이름 # 서버 제거

세션 안에서는 /mcp 명령으로 연결 상태를 한눈에 봅니다. 연결됨·인증 필요·연결 실패 같은 상태가 표시되고, 인증이 필요한 원격 서버라면 이 화면에서 로그인 절차를 진행합니다.

연결됨도구를 바로 쓸 수 있는 정상 상태

인증 필요원격 서버 로그인(OAuth) 또는 토큰이 필요한 상태

연결 실패서버가 응답하지 않는 상태 — 명령·URL·실행 여부 확인

붙이면서 걸렸던 점

• -- 구분자 빠뜨림 — 로컬 서버를 붙일 때 가장 자주 한 실수였습니다. 명령 뒤 옵션이 엉뚱하게 해석되면 십중팔구 이 구분자 누락이었습니다.
• 첫 실행이 느림 — 패키지를 내려받아 실행하는 서버는 처음 한 번이 오래 걸려 연결 대기 시간을 늘려야 할 때가 있었습니다. 두 번째부터는 빨라졌습니다.
• 신뢰할 수 있는 서버만 — MCP 서버는 외부 콘텐츠를 끌어오기도 해서, 출처가 분명하고 신뢰할 수 있는 서버만 붙이는 편이 안전했습니다. 공식 문서도 이 점을 강조합니다.
• 범위 헷갈림 — 분명히 추가했는데 다른 프로젝트에서 안 보일 때가 있었습니다. local로 붙인 서버는 그 프로젝트에서만 보이기 때문이었고, 어디서나 쓰려면 user 범위로 다시 붙이면 됐습니다.

자주 묻는 질문

Q. 로컬 서버와 원격 서버는 어떻게 고르나요?

내 컴퓨터에서 직접 실행하는 도구라면 stdio(로컬), 외부에 호스팅된 서비스라면 HTTP(원격)를 씁니다. 같은 기능을 두 방식으로 제공하는 서버도 있으니, 서버 안내에 적힌 권장 방식을 따르면 됩니다.

Q. 추가한 서버를 팀과 공유할 수 있나요?

--scope project로 추가하면 설정이 프로젝트 루트의 .mcp.json에 저장되어 저장소로 공유됩니다. 받는 사람은 처음 쓸 때 한 번 승인을 거칩니다.

Q. 연결이 안 될 때는 무엇부터 보나요?

세션에서 /mcp로 상태를 먼저 확인합니다. "인증 필요"면 로그인을, "연결 실패"면 명령·URL과 서버 실행 여부를 점검합니다. 로컬 서버라면 같은 명령을 터미널에서 직접 실행해 보는 것도 도움이 됐습니다.

마무리

MCP 서버 연동은 "Claude Code가 할 수 있는 일의 범위"를 넓히는 작업에 가깝습니다. 추가하는 방법(claude mcp add)과 적용 범위(local·project·user), 그리고 상태를 보는 법(/mcp)까지만 익혀 두면, 필요한 서버를 그때그때 같은 흐름으로 붙일 수 있습니다. 처음에는 자주 쓰는 서버 하나를 골라 로컬로 붙여 보는 것부터 권합니다.

이 글의 기능 설명은 Claude Code 공식 문서를 기준으로 정리했습니다. 명령이나 화면은 버전에 따라 달라질 수 있으니, 최신 내용은 공식 문서에서 직접 확인하시길 권합니다.

• MCP 개요·관리 문서: code.claude.com/docs/en/mcp
• MCP 빠른 시작 문서: code.claude.com/docs/en/mcp-quickstart

※ 본 글은 공개된 공식 문서와 개인적인 사용 경험을 바탕으로 정리한 정보성 콘텐츠입니다. 도구의 기능·화면·명령은 버전에 따라 달라질 수 있으며, 특정 결과를 보장하지 않습니다.