클로드 코드 MCP 서버 연결하기 — 추가부터 상태 확인·제거까지

클로드 코드 MCP가 하는 일 — 바깥 도구를 잇는 표준 연결

클로드 코드는 처음부터 파일 읽기, 파일 고치기, 명령 실행 같은 도구를 갖고 있다. MCP 서버(바깥 도구를 클로드에게 내주는 프로그램이나 온라인 서비스)를 붙이면 그 밖의 도구도 쓸 수 있다. 공식 빠른 시작은 이슈 추적기 검색, 데이터베이스 조회, 웹 브라우저 조작을 예로 든다.

공식 참조 문서가 권하는 연결 시점은 단순하다. 다른 도구의 자료를 채팅창에 자꾸 복사해 붙여 넣고 있다면 그 도구를 연결할 때다. 연결하면 클로드가 붙여 넣은 글이 아니라 그 시스템을 직접 읽고 다룬다.

MCP 서버의 세 가지 모양

서버는 어디에서 돌아가느냐에 따라 모양이 다르다. 처음에는 아래 두 가지만 알면 된다.

• 원격 HTTP 서버: 인터넷 주소(URL)로 접속하는 서버다. 공식 문서가 원격 서버에 권하는 방식이다.
• 로컬 stdio 서버: 내 PC에서 프로그램으로 실행되는 서버다. stdio는 프로그램끼리 표준 입력 · 출력으로 말을 주고받는 방식이다. 브라우저, 내 파일, 내 PC의 데이터베이스처럼 가까이 있는 것을 다룰 때 쓴다.

그 밖에 SSE 방식은 지원 중단 예정이라 HTTP를 대신 쓰라고 안내한다. WebSocket 방식은 서버가 먼저 소식을 보내야 할 때 쓰며, 명령이 아니라 JSON 설정으로만 넣는다.

서버 설명서가 Claude Desktop이나 다른 프로그램용으로만 쓰여 있어도 괜찮다. 설명서에서 셋 중 무엇이 있는지 찾으면 된다.

1. https://로 시작하는 주소가 있으면 원격 서버다. --transport http로 넣는다.
2. npx -y … 같은 실행 명령이 있으면 로컬 서버다. 그 명령을 통째로 -- 뒤에 붙인다.
3. mcpServers로 시작하는 JSON 덩어리가 있으면 그 안쪽 항목만 claude mcp add-json에 넘긴다.

--(빼기 두 개)는 클로드 코드의 옵션과 서버 실행 명령을 가르는 칸막이다. 이것을 빼먹으면 클로드 코드가 서버의 옵션까지 자기 옵션으로 읽는다.

정리하면 원격 서버는 «이름 + 주소», 로컬 서버는 «이름 + -- + 실행 명령»으로 넣는다. 이 글의 첫 예시는 원격 HTTP 서버라서 주소 하나만 있으면 된다.

첫 MCP 서버 연결하기 — 추가 · 확인 · 사용 · 제거 4단계

공식 빠른 시작은 첫 연습용으로 Claude Code 문서 MCP 서버를 쓴다. Claude Code 문서 전체를 검색하는 온라인 서버이고, 로그인이나 따로 할 설정이 없다. 단계는 어떤 서버든 같다.

1. 프로젝트 폴더에서 터미널을 열고 아래 명령을 실행한다. claude 대화 안이 아니라 터미널에서 친다.

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

claude-code-docs는 직접 정해 붙이는 이름이다. docs라고 해도 똑같이 돈다. 이 이름은 나중에 지우거나 확인할 때 부르는 이름이 된다.

잘 됐으면 Added HTTP MCP server claude-code-docs with URL: https://code.claude.com/docs/mcp to local config가 나온다. 다음 줄에는 File modified:와 함께 설정이 저장된 파일 경로가 보인다.

1. 연결 상태를 확인한다.

claude mcp list

잘 됐으면 claude-code-docs 줄 끝에 체크 표시와 함께 Connected가 보인다. 이 표시가 나와야 바로 쓸 수 있는 상태다. Windows 10 기본 콘솔처럼 오래된 창에서는 체크 표시가 다른 기호로 보일 수 있다.

1. 대화를 시작하고, 새 서버를 이름으로 불러 일을 시킨다.

claude

Use the claude-code-docs server to look up what MCP_TIMEOUT does

위 문장은 공식 안내의 예시 그대로다. 같은 뜻으로 한국어로 물으려면 아래처럼 쓴다.

claude-code-docs 서버로 MCP_TIMEOUT이 무슨 설정인지 찾아 줘.

평소에는 서버 이름을 말하지 않아도 클로드가 알맞은 도구를 고른다. 여기서 이름을 넣는 까닭은 웹 검색 같은 다른 도구가 아니라 새 서버를 거치게 하려는 것이다. 처음 쓸 때 권한을 묻는 창이 뜨면 승인한다.

잘 됐으면 클로드의 출력에 서버 이름이 붙은 도구 호출이 보인다. 그래야 답이 클로드가 원래 아는 지식이 아니라 MCP 서버에서 왔다는 것을 알 수 있다.

1. 연습이 끝났으면 서버를 지운다. 이 단계는 골라서 하면 된다.

claude mcp remove claude-code-docs

잘 됐으면 Removed MCP server "claude-code-docs" from local config가 나온다. 쓰지 않는 서버는 지우는 편이 낫다. 연결된 서버마다 도구 이름과 서버 안내가 매 대화에 실려 클로드의 컨텍스트 창(한 번에 기억하며 다룰 수 있는 대화 분량)을 조금씩 차지하기 때문이다.

이 글을 정리한 Windows PC에서도 같은 순서로 확인했다. 실제 설정을 건드리지 않도록 설정 폴더 위치를 정하는 CLAUDE_CONFIG_DIR를 빈 시험 폴더로 지정하고 돌렸다. 1단계는 위와 같은 Added HTTP MCP server … 문구로 끝났다. 2단계 claude mcp list는 Connected를 보여 줬다. 4단계 뒤 다시 목록을 열자 No MCP servers configured가 나왔다. 3단계 대화는 이 시험에서 돌리지 않았다.

인용 — Claude Code Docs «Connect Claude Code to tools via MCP»

«Verify you trust each server before connecting it.» — 서버를 연결하기 전에 그 서버를 믿을 수 있는지 하나하나 확인하라.

같은 문서는 바깥 내용을 가져오는 서버가 프롬프트 인젝션(외부 글에 숨긴 지시로 AI를 속이는 공격) 위험에 노출될 수 있다고 덧붙였다.

MCP 서버를 어디에 저장하나 — 클로드 코드 MCP 범위 세 가지

claude mcp add는 서버 정보를 설정 파일에 적는다. 어느 파일에 적느냐를 범위(scope · 서버가 어디까지 보이고 누구와 나눠 쓰는지 정하는 칸)라고 한다. 범위는 세 가지다.

• local: 기본값이다. 나만, 이 프로젝트에서만 쓴다. ~/.claude.json 안의 이 프로젝트 항목에 저장된다.
• project: 프로젝트 맨 위 폴더의 .mcp.json에 저장된다. 저장소에 올리면 프로젝트를 받은 사람 모두가 같은 서버를 쓴다.
• user: 나만 쓰지만 내 모든 프로젝트에서 보인다. ~/.claude.json의 맨 위 mcpServers 칸에 저장된다.

Windows에서 ~/.claude.json은 %USERPROFILE%\.claude.json이다. 보통 C:\Users\내이름\.claude.json 자리다. 앞 글들에서 본 ~/.claude/settings.json과 파일 이름도 자리도 다르니 헷갈리지 않게 한다.

범위 바꾸기와 .mcp.json 직접 쓰기

범위는 넣을 때 정해진다. 바꾸려면 지우고 새 범위로 다시 넣는다. 모든 프로젝트에서 쓰고 싶다면 아래 두 줄을 차례로 실행한다.

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

잘 됐으면 다른 프로젝트 폴더에서 claude mcp list를 실행해도 이 서버가 보인다. 어느 범위에 들어 있는지는 claude mcp get claude-code-docs로 확인한다. 이 글을 정리한 PC에서는 Scope: Local config (private to you in this project) 줄이 보였다.

팀과 나눠 쓸 서버는 프로젝트 맨 위 폴더에 .mcp.json을 직접 만들어도 된다. 공식 빠른 시작의 예시는 아래와 같다.

{
  "mcpServers": {
    "claude-code-docs": {
      "type": "http",
      "url": "https://code.claude.com/docs/mcp"
    },
    "playwright": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}

원격 서버는 url을, 로컬 서버는 command와 args를 적는다. 저장한 뒤에는 클로드 코드를 새로 시작한다. .mcp.json은 대화를 시작할 때 읽기 때문이다. 처음 보는 프로젝트 서버라면 승인을 묻는 창이 뜬다. 남의 저장소가 내 동의 없이 내 PC에서 프로그램을 띄우지 못하게 하는 장치다.

같은 이름의 서버가 여러 곳에 있으면 우선순위가 가장 높은 한 곳의 정의만 쓴다. 순서는 local → project → user → 플러그인 서버 → claude.ai 커넥터다. 칸을 섞어 합치지는 않는다.

위 네 가지는 모두 공식 문서에 방법이 있다. claude.ai에서 연결한 커넥터는 같은 계정으로 클로드 코드에 로그인하면 따로 넣지 않아도 /mcp 목록에 나온다. 커넥터를 연결하고 끊는 법은 클로드 커넥터 — 구글 드라이브·지메일·캘린더 연결과 끊기에 정리했다.

클로드 코드 MCP 서버가 연결 안 될 때와 알아 둘 주의

먼저 상태부터 본다. 대화 안에서는 /mcp, 터미널에서는 claude mcp list를 쓴다. 상태 표시의 뜻은 아래와 같다.

• Connected: 쓸 준비가 됐다.
• Needs authentication: 서버에는 닿았지만 브라우저 로그인이나 토큰(서비스가 발급하는 접속 열쇠 문자열)이 필요하다.
• Failed to connect: 서버가 응답하지 않았다.
• Pending approval: 아직 승인하지 않은 프로젝트 범위 서버다.
• Disabled for this project: 이 프로젝트에서 꺼 둔 서버다.

실제 화면에서는 각 상태 앞에 체크나 가위표 같은 작은 기호가 함께 붙는다. /mcp처럼 대화 안에서 치는 명령은 클로드 코드 슬래시 명령 모음 — 상황별로 자주 쓰는 것부터에 따로 모아 두었다.

그다음 증상에 맞춰 아래 순서로 확인한다.

1. No MCP servers configured가 뜨면 다른 폴더에서 서버를 넣었는지 본다. local 범위 서버는 넣은 프로젝트에서만 보인다. 지금 폴더에서 다시 넣거나 --scope user로 넣는다.
2. 설정 파일을 손으로 고쳤는데 안 보이면 파일 위치를 본다. ~/.claude/mcp.json이나 ~/.claude/.mcp.json은 읽지 않는다. 맞는 곳은 ~/.claude.json과 프로젝트의 .mcp.json이다.
3. Failed to connect가 뜨면 claude mcp get 서버이름으로 자세한 오류를 본다. 원격 서버는 주소가 열리는지 PowerShell에서 아래처럼 확인한다.

curl.exe -I https://code.claude.com/docs/mcp

PowerShell에서는 curl 대신 curl.exe를 쳐야 진짜 curl이 돈다. 404나 405가 나오면 서버는 살아 있다. 401이나 403이 나오면 로그인이나 토큰이 필요하다는 뜻이다.

1. 로컬 서버가 안 뜨면 설정에 적은 실행 명령을 터미널에서 직접 돌려 오류 문구를 본다. claude mcp get에 보이는 명령이 직접 친 것과 다르면 --를 빼먹었을 가능성이 크다.
2. 시작할 때 시간 초과가 나면 MCP_TIMEOUT(서버 시작을 기다리는 시간을 밀리초로 정하는 환경 변수)을 늘린다. 기본 시작 제한은 30초다. PowerShell에서는 아래처럼 쓴다.

$env:MCP_TIMEOUT = "60000"; claude

같은 이름 오류가 뜰 때와 도구가 안 보일 때

같은 이름으로 다시 넣으면 already exists in local config 오류가 난다. 이 글을 정리한 PC에서도 같은 명령을 두 번 실행하자 MCP server claude-code-docs already exists in local config가 나왔다. 먼저 claude mcp remove로 지우거나 다른 이름을 쓴다.

연결은 됐는데 도구가 하나도 없다면 /mcp에서 그 서버를 골라 도구 목록을 본다. 비어 있으면 API 키 같은 환경 변수(프로그램에 넘기는 설정값)가 빠진 경우가 많다. claude mcp add에 --env KEY=value를 붙여 넘긴다.

알아 둘 주의도 있다. 첫째, 서버는 직접 만들었거나 믿을 수 있는 제공자의 것만 쓴다. Anthropic은 디렉터리에 올릴 커넥터를 등록 기준으로 심사하지만, MCP 서버의 보안을 감사하거나 관리하지는 않는다. 둘째, .mcp.json만 읽어서는 대화에 실리는 서버를 다 볼 수 없다. 다른 범위의 서버, claude.ai 커넥터, 플러그인 서버도 함께 실린다.

셋째, MCP 도구도 권한 규칙으로 묶을 수 있다. 한 서버의 도구 전체는 mcp__서버이름__*, 도구 하나는 mcp__서버이름__도구이름 모양으로 적는다. 허용 · 확인 · 거부 규칙을 정하는 법은 클로드 코드 권한 모드 — 묻게 할 일과 맡길 일 나누기에 있다.

넷째, 출력이 큰 도구를 조심한다. MCP 도구의 출력이 10,000 토큰을 넘으면 경고가 뜨고, 기본 상한은 25,000 토큰이다. 상한은 MAX_MCP_OUTPUT_TOKENS 환경 변수로 바꾼다. 다섯째, 원격 서버를 지워도 그 서비스에 남은 로그인 허가까지 거둬지지는 않는다. 서비스 쪽 허가까지 거두려면 지우기 전에 claude mcp logout 서버이름을 먼저 실행한다.

표의 위 두 줄은 «서버가 제자리에 적혀 있느냐»의 문제다. 아래 네 줄은 «적힌 서버가 실제로 뜨느냐»의 문제다. 처음에는 claude mcp list의 상태 표시와 claude mcp get의 오류 문구, 이 두 가지만 봐도 대부분 원인이 보인다. 클로드 코드 설치부터 낯설다면 클로드 코드 설치·요금제·첫 사용 (2026) — Windows에서 시작하기를 먼저 보면 된다.

자주 묻는 것

MCP 서버와 claude.ai 커넥터는 무엇이 다른가요?

커넥터는 claude.ai에서 추가한 MCP 서버를 부르는 이름입니다. claude.ai 구독 계정으로 클로드 코드에 로그인하면 따로 넣지 않아도 클로드 코드에서 쓸 수 있습니다. API 키로 로그인했다면 커넥터를 불러오지 않습니다.

Claude Desktop에 넣어 둔 서버를 그대로 가져올 수 있나요?

claude mcp add-from-claude-desktop 명령으로 고른 서버를 가져올 수 있습니다. 다만 이 기능은 macOS와 WSL(Windows에서 리눅스를 돌리는 기능)에서만 됩니다. 이름에 공백 같은 글자가 든 서버는 가져오지 못합니다.

서버를 지우지 않고 잠시 끌 수 있나요?

대화 안에서 /mcp 창을 열고 그 서버를 끄면 됩니다. 설정은 그대로 남고 연결만 멈춥니다. 이 선택은 프로젝트마다 ~/.claude.json에 기록됩니다.

MCP 서버 설정 파일은 어디에 있나요?

local과 user 범위는 홈 폴더의 .claude.json에, project 범위는 프로젝트 맨 위 폴더의 .mcp.json에 있습니다. Windows에서는 사용자 폴더 바로 아래의 .claude.json입니다. ~/.claude 폴더 안의 mcp.json은 읽지 않습니다.

서버를 많이 연결하면 무엇이 달라지나요?

연결된 서버마다 도구 이름과 서버 안내가 대화에 실려 컨텍스트 창을 조금씩 차지합니다. 기본으로 켜진 도구 검색 기능이 도구의 자세한 정의를 필요할 때까지 미뤄 부담을 줄이지만, 쓰지 않는 서버는 지우는 편이 낫습니다.

정리 — 넣고, 목록에서 확인하고, 안 쓰면 지운다

MCP는 클로드 코드가 바깥 도구와 자료를 쓰게 잇는 공개 표준이다. 원격 서버는 claude mcp add --transport http 이름 주소로, 로컬 서버는 -- 뒤에 실행 명령을 붙여 넣는다. 넣은 뒤에는 claude mcp list에서 Connected를 확인한다. 나만 이 프로젝트에서 쓰면 local, 팀과 나누면 project, 모든 프로젝트에서 쓰면 user 범위다. 연결이 안 되면 상태 표시, claude mcp get의 오류, 파일 위치, -- 빠짐 순서로 본다. 서버는 믿을 수 있는 것만 붙인다. 명령과 동작은 판마다 바뀔 수 있으니, 이 글은 2026년 11월 2일 기준으로 읽고 쓰기 전에 공식 문서를 한 번 더 확인한다. 지금 하나만 해 본다면, 문서 서버를 넣고 목록에서 Connected가 보이는지부터 확인하자.

참고 자료

1. Claude Code Docs. Connect Claude Code to tools via MCP — MCP 정의와 쓰임 · 서버 모양(HTTP 권장 · SSE 지원 중단 예정 · stdio · WebSocket) · -- 구분자 · 다른 클라이언트용 설명서 옮기기 · 관리 명령 · 상태 표시 · 끄기 · 범위 표와 우선순위 · 환경 변수 · 인증 · claude.ai 커넥터 · Claude Desktop 가져오기 · 출력 한도 · 도구 검색 · 신뢰 경고(2026-11-02 확인). code.claude.com
2. Claude Code Docs. Connect to MCP servers — 첫 서버 4단계(문서 MCP 서버 · 추가 · 상태 확인 · 사용 · 제거) · 상태 표 · 설정 파일 위치(Windows 포함) · 범위 바꾸기 · .mcp.json 직접 쓰기와 승인 · 문제 해결(30초 시작 제한 · MCP_TIMEOUT · curl.exe · -- 빠짐)(2026-11-02 확인). code.claude.com
3. Claude Code Docs. Security — MCP 보안 — 직접 만든 서버나 믿는 제공자의 서버 권장 · 디렉터리 등록 심사는 하지만 보안 감사·관리는 하지 않음 · .mcp.json만 봐서는 모든 서버가 안 보임(2026-11-02 확인). code.claude.com
4. Claude Code Docs. Configure permissions — MCP 도구 권한 규칙 mcp__<server>__* 와 mcp__<server>__<tool> 모양(2026-11-02 확인). code.claude.com
5. Claude Code 문서. MCP 서버에 연결하기 — 한국어판 용어(범위 · 구성 파일 · 상태 표시기 · 컨텍스트 윈도우)(2026-11-02 확인). code.claude.com