클로드코드 MCP 연결 방법: claude mcp add 첫 실습

"MCP가 뭔지는 알겠는데, 터미널에서는 어떻게 붙이나요?"

결론부터 답해드리겠습니다. 명령어 한 줄입니다. 터미널에 claude mcp add --transport http 이름 주소를 치면 MCP 서버 하나가 등록됩니다. 붙었는지는 claude mcp list로 확인하고, 지울 때는 claude mcp remove 이름을 칩니다. 웹에서 커넥터를 골라 켜던 일을 터미널에서는 이 명령어가 대신합니다. 지난 레슨에서 클로드코드에 첫 질문을 던져 답을 받으셨다면, 오늘은 그 세션에 바깥 서비스 하나를 붙일 차례입니다. claude mcp add 문법만 급히 확인하러 오셨다면 이 레슨만 보셔도 됩니다.

claude mcp add

클로드코드에 MCP(Model Context Protocol) 서버 하나를 등록하는 명령어입니다. 등록하면 서버 주소가 설정 파일에 적히고, 클로드코드가 그 서버의 도구를 자기 도구 목록에 함께 올립니다. 웹에서 커넥터를 켜는 화면이 터미널에서는 이 한 줄로 대체됩니다.

웹 커넥터와 CLI 연결은 뭐가 다른가요?

바닥에 깔린 규격은 같습니다. AI 연결하기 트랙에서 클로드에 드라이브를 붙일 때 쓴 커넥터도 MCP 위에서 돌아갑니다. 공식 문서는 Anthropic 디렉터리의 커넥터가 클로드코드와 같은 MCP 인프라를 쓴다고 밝힙니다. 붙이는 자리만 달라진 셈입니다.

여기서 반가운 사실이 하나 있습니다. 웹에서 이미 붙여둔 커넥터는 터미널에서 다시 붙일 필요가 없습니다. claude.ai 구독 계정으로 로그인해 쓰고 있다면 웹에 추가해둔 커넥터가 자동으로 딸려 오기 때문입니다. 세션에서 /mcp를 쳐보면 claude.ai에서 왔다는 표시와 함께 목록에 나옵니다.

명령어로도 되는데 MCP는 왜 붙이나요?

헷갈리기 쉬운 지점을 짚겠습니다. 클로드코드는 MCP를 붙이지 않아도 이미 손이 있습니다. 파일을 읽는 Read, 고치는 Edit, 내용을 찾는 Grep, 명령을 실행하는 Bash가 처음부터 기본 도구로 들어 있습니다. 지난 레슨에서 "이 폴더에 뭐가 있어?"에 답이 온 것도 이 기본 도구가 한 일입니다. 그러면 MCP는 왜 필요할까요?

갈리는 지점은 하나입니다. 내 컴퓨터 안에서 끝나는 일이면 기본 도구로 충분합니다. 폴더를 뒤지고 파일을 고치는 일이 여기 해당합니다. 바깥 서비스가 쥔 데이터나 기능을 가져와야 하면 MCP가 필요합니다. 노션 문서나 이슈 트래커의 티켓처럼 내 하드디스크에 없는 것들입니다. 창고 물건은 직접 꺼내 오면 되지만 옆 건물 물건은 그쪽 담당자를 불러야 하는 것과 같습니다.

겹치는 구간도 있습니다. 깃허브가 대표적입니다. gh라는 명령줄 도구를 설치해 Bash로 부를 수도 있고, 공식 문서가 안내하는 GitHub MCP 서버를 붙일 수도 있습니다. 이때 클로드는 상황에 맞는 도구를 알아서 고릅니다. 특정 서버로 처리시키려면 질문에 그 서버 이름을 넣으면 됩니다. 어느 쪽으로 갔는지는 응답에서 구분됩니다. MCP 도구에는 mcp__서버이름__도구이름 형태로 이름표가 붙기 때문입니다.

그래도 애매하다면 아래 네 가지로 판단하시면 됩니다.

마지막 줄은 공식 문서가 명시하는 비용입니다. "일단 다 붙여놓자"가 답이 아닌 이유입니다.

실습: claude mcp add로 연결 1개 붙이기

준비물은 설치와 로그인이 끝난 클로드코드입니다. 아직 설치 전이시라면 클로드코드 설치 레슨을 먼저 보세요.

오늘 붙일 서버는 공식 문서가 첫 예시로 쓰는 클로드코드 문서 MCP 서버입니다. 고른 이유는 세 가지입니다. 가입도 API 키도 필요 없고, 원격 서버라 내 컴퓨터에 아무것도 설치하지 않으며, 내 파일이나 계정을 건드리지 않아 뭔가 망가질 위험이 없습니다.

스텝 1: 서버 등록

이 명령은 claude 세션 안이 아니라 터미널에서 칩니다. 대화를 시작하기 전에 설정을 하는 단계이기 때문입니다.

claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp

한 토막씩 뜯어보겠습니다.

• claude mcp add, 서버를 등록하는 명령입니다.
• --transport http, 내 컴퓨터에서 돌리는 프로그램이 아니라 주소로 접속하는 원격 서버라는 표시입니다. 짧게 -t http로 써도 같습니다.
• claude-code-docs, 직접 지어 붙이는 이름입니다. docs라고 해도 똑같이 동작합니다. 응답의 도구 이름표로 쓰이고 지울 때도 이 이름으로 부릅니다.
• 마지막이 서버가 열려 있는 주소입니다.

성공하면 Added HTTP MCP server claude-code-docs with URL: ... to local config라는 줄과, 방금 고쳐진 설정 파일 경로를 알려주는 File modified: 줄이 뜹니다.

스텝 2: 붙었는지 확인

Added가 떴다고 접속까지 된 것은 아닙니다. 이 명령은 설정을 저장할 뿐 주소나 자격 증명이 맞는지 검사하지 않습니다.

claude mcp list

이름 옆에 상태가 함께 나옵니다. 오늘 붙인 서버가 claude-code-docs: ... (HTTP) - ✔ Connected처럼 보이면 성공입니다.

윈도우 10 기본 콘솔처럼 오래된 화면에서는 ✔ 대신 √, ✘ 대신 ×로 보입니다. 같은 뜻입니다.

스텝 3: 연결된 도구로 질문 하나

이제 세션을 열고 써봅니다.

claude

입력창에 이렇게 칩니다.

claude-code-docs 서버로 MCP_TIMEOUT이 무슨 일을 하는지 찾아줘

허가를 묻는 창이 뜨면 승인하시면 됩니다. 평소에는 서버 이름을 부를 필요가 없습니다. 클로드가 알아서 맞는 도구를 고르기 때문입니다. 여기서 이름을 부른 이유는 답이 웹 검색 같은 다른 도구로 새지 않게 하려는 것입니다. 도구 호출에 claude-code-docs 이름표가 붙어 있으면 그 답이 MCP 서버에서 왔다는 증거입니다.

스텝 4: 확인과 해제

등록만큼 자주 쓰는 것이 확인과 해제입니다.

claude mcp list                    # 등록된 서버 전체와 각각의 상태
claude mcp get claude-code-docs    # 서버 하나의 상세 정보와 저장된 범위
claude mcp remove claude-code-docs # 등록 해제

세션 안에서는 /mcp를 칩니다. 목록을 보고 서버를 골라 다시 연결하거나 인증할 수 있습니다. 잠깐만 꺼두고 싶다면 이 화면에서 토글로 끄면 설정을 잃지 않고 연결만 멈춥니다. 실습이 끝났다면 지워두시길 권합니다. 안 쓰는 서버도 매 세션 자리를 차지하기 때문입니다.

등록한 서버는 어디에 저장되나요?

claude mcp add는 옵션을 주지 않으면 로컬 범위로 저장합니다. 나만 볼 수 있고 등록한 폴더에서만 켜지는 범위입니다. 공식 한국어 문서는 이를 범위(scope)라고 부르고 세 가지를 둡니다.

혼자 쓰신다면 로컬과 사용자 둘만 알면 됩니다. 폴더를 옮겨 다녀도 늘 붙어 있게 하려면 --scope user를 붙입니다.

claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp

범위는 등록하는 순간 정해집니다. 바꾸려면 지우고 다시 등록해야 합니다. 윈도우에서 ~/.claude.json은 보통 C:\Users\사용자이름\.claude.json입니다. 직접 고칠 일은 없지만 어디에 적히는지 알아두면 안 보일 때 찾을 곳이 생깁니다.

자주 걸리는 문제

• /mcp에 "No MCP servers configured"라고 나온다. 다른 폴더에서 등록하셨을 가능성이 큽니다. 로컬 범위는 등록한 폴더에 묶입니다. 지금 폴더에서 다시 등록하시거나 --scope user로 등록하세요.
• 등록은 됐는데 ✘ Failed to connect이 뜬다. 주소를 먼저 의심해 보세요. claude mcp list는 상태 뒤에 서버가 돌려준 오류를 함께 보여줍니다. 없는 경로를 적어 404가 돌아온 경우라면 /mcp에서 그 서버를 골랐을 때 MCP endpoint not found at ... 안내가 뜹니다. claude mcp get 이름으로 주소를 확인한 뒤 지우고 다시 등록하세요.
• "Connection timed out"이 뜬다. 시작 대기 시간이 기본 30초입니다. MCP_TIMEOUT=60000 claude처럼 밀리초 단위로 늘려 실행해 보세요. PowerShell에서는 $env:MCP_TIMEOUT = "60000"; claude로 씁니다.
• npx로 도는 서버가 안 뜬다. npx로 실행되는 서버는 Node.js 18 이상이 필요합니다. 처음에는 패키지를 내려받느라 잠시 실패로 보이기도 하니 기다렸다가 claude mcp list를 다시 쳐보세요.
• 붙기는 했는데 도구가 하나도 없다. 서버가 요구하는 환경 변수, 대개 API 키가 빠졌을 때입니다. --env KEY=값을 붙여 다시 등록하세요.
• 회사 계정에서 등록 자체가 막힌다. 관리자가 쓸 수 있는 서버를 제한해둔 경우입니다. Cannot add MCP server "이름": not allowed by enterprise policy처럼 정책 때문이라고 명시된 메시지가 뜹니다. 내 실수가 아니니 담당자에게 문의하세요.

안전 수칙 하나만 짚겠습니다. 아무 서버나 붙이지 마세요. Anthropic은 디렉터리 등재 기준으로 커넥터를 검토하지만 개별 MCP 서버를 보안 감사하지는 않는다고 공식 문서가 명시합니다. 바깥 콘텐츠를 끌어오는 서버일수록 그 콘텐츠에 숨은 지시문이 섞여 들어올 위험이 있습니다. 신뢰할 수 있는 회사가 공식으로 운영하는 서버만 붙이세요.

저는 터미널 쪽을 먼저 겪었습니다. 그때는 이게 맞게 하는 건지 확신이 없었습니다. 한 번 붙이면 계속 붙어 있는 건지 매번 해야 하는 건지도 몰랐고, 붙인 다음에 잘 된 건지 확인할 방법도 몰라서 그냥 시켜 보고 되면 된 거구나 했습니다.

그래서 이 레슨의 3단계를 넣었습니다. 붙인 다음에 claude mcp list로 확인하는 습관 하나가 그 불안을 없앱니다. 저는 그 명령이 있는 줄 몰라서 한참을 확인 없이 썼습니다.

인증이 필요한 서버를 붙였을 때 브라우저 창이 저절로 뜨는 것도 처음에는 신기했습니다. 터미널에 친 한 줄이 브라우저를 여는 게 어색했는데, 지금 보면 승인은 사람이 눈으로 보고 눌러야 하니 그 자리가 맞습니다.

트랙 완주: 브라우저 밖으로 나온 여섯 계단

이 트랙에서 밟은 계단을 돌아보겠습니다. 아래 여섯 가지가 다 됐는지 확인해 보세요. 하나라도 비어 있다면 그 레슨으로 돌아가시면 됩니다.

• 1. 클로드 제품군, 내 일에 맞는 제품 하나를 골랐다.
• 2. 데스크톱 앱과 로컬 폴더, 앱에서 내 컴퓨터 폴더를 연결해봤다.
• 3. 터미널 첫걸음, 터미널을 열고 최소 명령어 세 개를 쳐봤다.
• 4. 클로드코드 설치, claude가 로그인된 상태로 실행되는 화면을 봤다.
• 5. 첫 실행, 첫 질문을 던지고 응답을 받았다.
• 6. 오늘, claude mcp add로 서버를 등록하고 ✔ Connected를 확인했다.

여기까지 오셨다면 브라우저 밖으로 나오는 일은 끝났습니다. 트랙을 시작할 때는 터미널이 낯설었을 텐데 지금은 그 화면에서 AI에게 질문을 던지고 바깥 서비스까지 붙이고 계십니다. 파일을 직접 고치고 명령을 실행하는 이야기는 클로드코드 트랙에서 이어집니다.