한눈에 보기
- 이 글에서 클로드 코드(Claude Code)에 MCP 서버를 붙이는 법을 처음부터 옮겼어요. MCP 가 뭔지, 명령 한 줄로 붙이고 확인하는 법, 로그인이 필요한 서버, 범위와 설정 파일, 막힐 때 볼 곳까지예요.
- 순서 터미널에서 claude mcp add 로 붙이고, claude mcp list 로 상태를 보고, 클로드 코드 안에서 /mcp 로 관리해요.
- 주의 서버는 믿을 수 있는 곳만 붙여요. 붙인 서버마다 컨텍스트를 조금씩 차지하니 안 쓰는 건 지워요.
- 읽는 법 “처음이라면”만 따라 해도 서버 하나를 붙여 써 볼 수 있어요. “익숙해졌다면”은 팀과 나눠 쓸 때, “더 깊이”는 권한·토큰·컨텍스트를 손볼 때 보면 돼요.
이 글 순서
클로드 코드를 쓰다 보면 다른 프로그램에 있는 내용을 복사해서 대화 창에 붙여 넣는 일이 자꾸 생겨요. 노션에 적어 둔 기획서, 오류 알림 서비스에 쌓인 오류 기록, 브라우저로 열어 봐야 하는 화면 같은 것들이요. MCP 는 이걸 클로드 코드가 직접 가져다 보게 해 주는 연결이에요. 공식 문서도 다른 도구의 자료를 대화 창에 복사해 넣고 있다면 그때가 서버를 붙일 때라고 적었어요.
클로드 코드 공식 문서의 MCP 빠른 시작(mcp-quickstart)과 MCP 참고 문서(mcp), 권한(permissions)·VS Code·변경 기록 쪽을 2026년 10월 8일에 읽고 옮겼어요. 캡처는 한국어 문서에서 했고, 명령 이름과 버전 숫자는 영어 문서와 맞춰 봤어요. 터미널 그림은 클로드 코드 2.1.292 가 깔린 윈도우 PC 에서 같은 날 돌린 출력이에요. 설정을 바꾸지 않는 도움말(--help)과 버전 확인, 주소에 연결되는지 보는 명령만 돌렸고, 서버를 실제로 붙이는 claude mcp add 는 이 PC 에서 돌리지 않았어요. 그래서 붙인 뒤에 나오는 문구는 문서에 적힌 대로 옮겨요. 문서에 없는 것은 “미확인”으로 적었어요.
MCP 가 뭔가요
클로드 코드는 내가 말로 요청한 일을 Claude 라는 AI 가 대신 하는 프로그램이에요. 기본으로는 내 컴퓨터의 파일을 읽고 고치고, 터미널 명령을 돌리고, 웹 페이지를 읽을 줄 알아요. 여기서 끝이 아니라 바깥 도구를 더 붙일 수 있는데, 그 붙이는 규격이 MCP 예요.
MCP 는 Model Context Protocol 의 줄임말이에요. 프로토콜은 “서로 이렇게 주고받자”고 정해 둔 약속이에요. 콘센트 모양이 정해져 있어서 어느 가전이든 꽂으면 전기가 들어오는 것처럼, 이 약속을 지킨 프로그램이면 클로드 코드에 꽂아 쓸 수 있어요. 문서는 MCP 를 “AI 도구 통합을 위한 오픈 소스 표준”이라고 소개해요.
꽂는 쪽 프로그램을 MCP 서버라고 불러요. 서버라고 하면 큰 컴퓨터가 떠오르지만, 여기서는 “클로드 코드에 도구를 내주는 프로그램”이라는 뜻이에요. 노션 서버를 붙이면 노션 문서를 읽는 도구가, 브라우저 서버를 붙이면 웹 페이지를 열고 누르는 도구가 생기는 식이에요.
문서가 드는 용도는 개발 일이 많아요. 이슈 관리 도구에 적힌 일감을 읽고 바로 고치기, 오류 알림 서비스의 기록 살피기, 데이터베이스(자료를 표로 쌓아 두는 프로그램)에 물어보기 같은 거예요. 개발을 안 하는 분이라도 쓸 데가 있어요. 노션 페이지 내용을 정리해 달라고 하거나, 브라우저로 사이트를 열어 제목과 내용을 확인해 달라고 하는 일이요. Gmail·구글 캘린더 같은 것은 claude.ai 쪽에서 연결하면 클로드 코드에도 따라오는데, 아래 “claude.ai 커넥터” 부분에 적었어요.
서버는 크게 두 종류예요. 하나는 그 회사가 인터넷에 띄워 둔 서버에 주소로 접속하는 원격 서버(http), 다른 하나는 내 컴퓨터에서 작은 프로그램으로 켜지는 로컬 서버(stdio)예요. stdio 는 프로그램끼리 글자를 주고받는 기본 통로 이름인데, “내 컴퓨터에서 켜는 쪽”이라고만 기억하면 충분해요. 붙이는 명령 형식이 둘이 조금 달라서 아래에서 따로 다뤄요.
처음이라면: 하나 붙이기
문서의 빠른 시작은 첫 서버로 “클로드 코드 문서 MCP 서버”를 권해요. 클로드 코드 문서를 찾아 주는 서버인데, 로그인도 특별한 설정도 필요 없어서 연습용으로 알맞다고 적혀 있어요. 준비물은 둘이에요.
- 클로드 코드가 깔려 있고 로그인돼 있을 것. 아직이라면 윈도우 설치 글부터 보세요.
- 터미널을 프로젝트 폴더에서 열어 둘 것. 터미널은 마우스 대신 글자로 컴퓨터에 일을 시키는 까만 창이고, 윈도우에서는 PowerShell 이에요. 문서는 빈 폴더라도 된다고 적었어요.
먼저 내 클로드 코드에 mcp 명령이 있는지 봐요. 이 PC 에서 돌려 본 화면이에요.
claude mcp --helpclaude mcp 아래에 어떤 명령이 있는지 영어 설명과 함께 보여 달라는 줄이에요. 설정은 아무것도 바뀌지 않아요. add(더하기), list(목록), get(하나 자세히), remove(지우기), login·logout(로그인·로그아웃)이 앞으로 쓸 것들이에요.
이제 서버를 더해요. 여기서 가장 많이 헷갈리는 곳이 하나 있어요. 이 명령은 클로드 코드 대화 창 안이 아니라 터미널(PowerShell)에 쳐요. 문서도 “claude 세션 내부가 아니라 터미널에서, 대화를 시작하기 전에 구성한다”고 적어 뒀어요.
claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcpclaude-code-docs 라는 이름으로, 저 주소에 있는 원격 서버를 등록하라는 줄이에요. 문서가 명령을 한 조각씩 풀어 둔 부분을 캡처했어요.
- claude mcp add: 서버를 등록하는 명령이에요.
- --transport http: 내 컴퓨터에서 켜는 프로그램이 아니라 주소로 붙는 서버라는 뜻이에요.
- claude-code-docs: 내가 지어 붙이는 이름이에요. docs 라고 지어도 똑같이 돌아요. 이 이름이 Claude 의 답에 도구 라벨로 붙고, 지울 때도 이 이름을 써요.
- 마지막 주소: 서버가 있는 곳이에요.
잘 되면 “Added HTTP MCP server claude-code-docs with URL: … to local config” 와 “File modified:” 한 줄이 나온다고 문서에 적혀 있어요. local config 는 “나에게, 이 프로젝트에서만” 등록됐다는 뜻이에요. 다른 폴더에서 클로드 코드를 켜면 이 서버는 없어요. 모든 폴더에서 쓰고 싶으면 아래 “범위”에서 다루는 --scope user 를 붙여요.
상태 글자 읽기
등록했다고 바로 되는 건 아니에요. 문서도 “Added 는 저장됐다는 뜻이지 돌아간다는 뜻이 아니다”라고 적었어요. 연결이 되는지는 터미널에서 이렇게 봐요.
claude mcp list등록된 서버 목록과 함께 서버마다 연결 상태를 보여 달라는 줄이에요. 도움말 설명에 따르면 승인된 서버는 이때 실제로 접속해 보고(health-check) 상태를 적어요.
| 보이는 글자 | 뜻 | 할 일 |
|---|---|---|
| ✔ Connected | 쓸 준비 끝 | 그대로 쓰기 |
| ! Needs authentication | 닿긴 하는데 로그인 필요 | /mcp 에서 Authenticate |
| ✘ Failed to connect | 서버가 대답 안 함 | 주소·명령 확인(아래 “막힐 때”) |
| ⏸ Pending approval | .mcp.json 서버를 아직 승인 안 함 | claude 를 켜서 승인 |
출처: 클로드 코드 문서 mcp-quickstart. 10월 8일 확인.
윈도우 10 의 옛 콘솔 창처럼 특수 글자를 못 그리는 창에서는 ✔ 대신 √, ✘ 대신 × 가 보인다고 문서에 적혀 있어요. 모양이 달라도 뜻은 같아요.
Connected 가 뜨면 써 봐요. 클로드 코드를 켜고, 이 서버를 써서 찾아 달라고 이름을 넣어 요청해요.
claude
Use the claude-code-docs server to look up what MCP_TIMEOUT does첫 줄은 클로드 코드를 켜는 명령, 둘째 줄은 켜진 뒤 입력 칸에 치는 프롬프트예요. 문서 예시 그대로 영어인데, “claude-code-docs 서버로 MCP_TIMEOUT 이 뭘 하는지 찾아 줘”처럼 한국어로 써도 돼요. 평소에는 서버 이름을 안 넣어도 Claude 가 알맞은 도구를 스스로 골라요. 연습 때만 이름을 넣어서, 웹 검색 같은 다른 도구가 대신 답하지 않게 하는 거예요.
Claude 가 서버 도구를 처음 쓸 때 허락을 물으면 승인해요. 답 중간에 도구를 호출한 줄이 서버 라벨을 달고 보이면, 그 답이 Claude 가 원래 알던 게 아니라 MCP 서버에서 온 거예요.
쓰고 나서 지우기
연습이 끝났으면 지워도 돼요.
claude mcp remove claude-code-docsclaude-code-docs 라는 이름의 서버 등록을 지우라는 줄이에요. “Removed MCP server … from local config” 가 나온다고 문서에 적혀 있어요. 원격 서버를 지우면 그 서버에 쓰던 로그인 정보(OAuth 토큰)도 같이 지워져요.
안 쓰는 서버를 지우는 데는 이유가 있어요. 붙어 있는 서버마다 도구 이름과 서버 안내문이 매번 대화에 실려서 컨텍스트를 조금씩 차지한다고 문서에 적혀 있어요. 컨텍스트는 Claude 가 한 번에 기억하며 볼 수 있는 글의 양이에요. 책상이 넓어도 안 쓰는 물건을 계속 올려 두면 좁아지는 것과 같아요.
익숙해졌다면: 로컬 서버
문서 서버 하나를 붙여 봤다면 다음은 나머지 두 종류예요. 먼저 내 컴퓨터에서 켜지는 로컬 서버예요. 브라우저, 내 파일, 내 컴퓨터의 데이터베이스처럼 “내 컴퓨터에 있는 것”을 만져야 할 때 써요. 빠른 시작은 Playwright MCP 서버를 예로 들어요. Claude 가 브라우저를 열고 누르고 읽게 해 주는 서버이고, 계정이 필요 없어요.
claude mcp add playwright -- npx -y @playwright/mcp@latestplaywright 라는 이름으로, 뒤의 명령을 돌려서 켜지는 서버를 등록하라는 줄이에요. 문서는 원격 서버 명령과 세 가지가 다르다고 짚어요.
- --transport 가 없어요. 안 적으면 로컬(stdio)로 알아들어요.
--(하이픈 두 개) 뒤에 적은 것이 클로드 코드가 서버를 켤 때 돌리는 명령이에요.- -y 는 npx 에게 “설치할까?” 묻지 말고 받으라는 뜻이에요.
npx 는 Node.js 라는 프로그램에 딸려 오는 명령이에요. 인터넷에서 프로그램을 받아 바로 돌려 줘요. 그래서 이 예시는 Node.js 18 이상이 깔려 있어야 돌아가요. 깔려 있는지는 node --version 으로 봐요. 이 PC 에서는 v24.19.0 이 나왔어요(아래 “막힐 때” 그림 맨 위 두 줄). Playwright 서버는 컴퓨터에 이미 깔린 크롬을 움직인다고 적혀 있어요.
-- 가 왜 필요한지는 참고 문서에 한 번 더 나와요.
-- 앞은 클로드 코드에게 하는 말이고, 뒤는 서버 프로그램에게 그대로 넘기는 말이에요. 이걸 빼먹으면 서버 쪽 옵션(예: --port 8080)을 클로드 코드가 자기 옵션인 줄 알고 읽으려 해요. 한 가지 더, 서버에 비밀 값(API 키)을 넘기는 --env 는 이름 바로 앞에 두면 안 된다고 적혀 있어요. 이름까지 KEY=value 로 읽고 거절하기 때문이에요. 명령 도움말에 실린 예시처럼 이름을 먼저 쓰면 걱정이 없어요.
claude mcp add my-server -e API_KEY=내키 -- npx my-mcp-server도움말 예시를 그대로 옮긴 거예요. my-server 라는 이름으로, API_KEY 라는 환경 변수에 내 키를 담아 서버를 켜라는 줄이에요. 환경 변수는 프로그램이 켜질 때 읽어 가는 “이름이 붙은 값”이에요. -e 는 --env 를 줄인 것이고, -s 는 --scope, -t 는 --transport, -H 는 --header 를 줄인 거예요.
로컬 서버는 처음 확인할 때 ✘ Failed to connect 가 뜰 수 있어요. npx 가 프로그램을 받는 중이라 그래요. 문서는 잠깐 기다렸다가 claude mcp list 를 다시 치라고 해요.
로그인이 필요한 서버
센트리(오류 알림 서비스), 리니어(일감 관리), 노션 같은 서비스는 MCP 서버 앞에 로그인을 걸어 둬요. OAuth 라는 방식인데, 내 비밀번호를 클로드 코드에 주지 않고 그 서비스 화면에서 “이 프로그램이 내 계정을 써도 된다”고 허락하는 거예요. 붙이는 명령은 앞과 같고 주소만 달라요.
claude mcp add --transport http sentry https://mcp.sentry.dev/mcpsentry 라는 이름으로 센트리의 원격 서버를 등록하라는 줄이에요. 노션이라면 참고 문서 예시대로 claude mcp add --transport http notion https://mcp.notion.com/mcp 예요. 붙인 직후 claude mcp list 에 ! Needs authentication 이 뜨는 게 정상이라고 문서에 적혀 있어요.
- 클로드 코드를 켜고 입력 칸에 /mcp 를 쳐요. MCP 서버를 관리하는 창이 열려요.
- 목록에서 sentry 를 고르고 Enter, 그다음 Authenticate 를 골라요.
- 브라우저가 열리면 센트리에 로그인하고 연결을 허락해요.
- 클로드 코드로 돌아오면 상태가 연결됨으로 바뀌어요.
클로드 코드를 켜지 않고 터미널에서 바로 로그인하는 명령도 있어요.
claude mcp login sentrysentry 서버의 로그인 과정을 터미널에서 시작하라는 줄이에요. 원격 접속(SSH)처럼 브라우저가 없는 곳에서는 주소만 출력해 주고, 그 주소를 내 컴퓨터 브라우저에서 연 뒤 돌아온 주소를 붙여 넣으라고 해요. 로그인을 지우려면 claude mcp logout sentry 예요. 브라우저가 자동으로 안 열리면 터미널에 나온 주소를 복사해 직접 열면 된다고 적혀 있어요.
로그인 대신 고정된 토큰을 받는 서버도 있어요. 토큰은 비밀번호 대신 쓰는 긴 키 문자열이에요. 이런 서버는 붙일 때 --header “Authorization: Bearer 토큰” 을 같이 적어요. 문서는 claude mcp add 가 토큰이 맞는지 따지지 않고 저장만 한다고 적었어요. 틀린 토큰도 저장은 되고, 나중에 연결이 실패(401)로 떠요.
claude.ai 커넥터
개발 도구보다 Gmail·구글 캘린더 같은 것을 붙이고 싶다면 길이 하나 더 있어요. claude.ai 웹의 커넥터 설정(claude.ai/customize/connectors)에서 연결해 둔 것은, 같은 계정으로 로그인한 클로드 코드에 자동으로 따라와요. /mcp 목록에서 claude.ai 에서 온 것이라는 표시와 함께 보여요. Team·Enterprise 요금제는 관리자만 커넥터를 더할 수 있다고 적혀 있어요.
조건이 있어요. 구독 로그인(/login 으로 claude.ai 계정)으로 쓰는 중이어야 해요. API 키 환경 변수가 켜져 있거나, 클라우드 회사를 거쳐 쓰거나, claude setup-token 으로 만든 토큰으로 쓰면 커넥터를 안 가져와요. 커넥터가 안 보이면 /status 로 지금 무엇으로 로그인했는지부터 보라고 문서에 적혀 있어요. 로그인 방식을 보는 법은 클로드 코드 사용량 확인 글의 “로그인 방식” 부분에 있어요.
문서는 Gmail·구글 캘린더·Microsoft 365 처럼 Anthropic 이 돌리는 커넥터는 클로드 코드에서 직접 로그인할 수 없다고 적었어요. 그 서비스가 claude.ai 쪽으로만 돌아오는 주소를 받아 주기 때문이에요. 이런 건 claude mcp add 로 붙이지 말고 claude.ai 에서 연결하면 돼요.
범위 세 가지
서버를 여러 폴더에서 쓰거나 팀과 공유할 때 볼 부분이에요. 서버를 어디에 적어 두느냐를 “범위(scope)”라고 불러요. 세 가지예요.
윈도우에서 ~/.claude.json 은 내 사용자 폴더 바로 아래의 .claude.json(C:\Users\사용자이름\.claude.json)이에요. ~ 는 “내 홈 폴더”를 줄여 쓰는 기호예요. 문서는 이 파일을 손으로 고칠 필요는 없고, 위치만 알면 문제를 찾을 때 도움이 된다고 적었어요.
claude mcp add --scope user --transport http claude-code-docs https://code.claude.com/docs/mcp같은 문서 서버를 user 범위로, 그러니까 내 모든 프로젝트에서 쓰게 등록하라는 줄이에요. --scope project 로 바꾸면 프로젝트 맨 위 폴더의 .mcp.json 에 적혀요. 이 파일을 깃(코드 변경 기록 도구)에 올려 두면, 저장소를 받은 팀원이 클로드 코드를 켤 때 승인 창이 뜨고 승인하면 같이 쓰게 돼요.
범위는 붙일 때 정해지고 나중에 옮기는 명령은 없어요. 바꾸려면 지우고 다시 더해요.
claude mcp remove claude-code-docs --scope locallocal 범위에 있는 claude-code-docs 만 지우라는 줄이에요. 같은 이름이 여러 범위에 있을 때 --scope 없이 지우려 하면 “exists in multiple scopes” 라고 알려 준다고 문서에 적혀 있어요.
같은 이름의 서버가 여러 곳에 있으면 local, project, user 순으로 앞의 것 하나만 써요. 설정을 섞어 합치지 않고 앞의 것을 통째로 써요. 그 뒤로 플러그인이 넣은 서버, claude.ai 커넥터 순이에요. 회사가 관리 설정으로 넣은 서버는 이것들보다 앞선다고 적혀 있어요(2.1.259 부터).
local 범위는 프로젝트 폴더에 묶여요. 깃 저장소 안이면 저장소 맨 위 폴더, 아니면 명령을 친 그 폴더예요. 다른 폴더에서 클로드 코드를 켜고 “서버가 없다”고 하는 가장 흔한 이유가 이거라고 문서에 적혀 있어요.
.mcp.json 직접 쓰기
명령 대신 파일을 직접 써도 돼요. 팀과 공유하는 project 범위의 .mcp.json 이 손으로 쓰기 가장 알맞은 파일이라고 문서에 적혀 있어요. JSON 은 이름과 값을 중괄호로 묶어 적는 글 형식이에요.
{
"mcpServers": {
"claude-code-docs": {
"type": "http",
"url": "https://code.claude.com/docs/mcp"
}
}
}mcpServers 안에 서버 이름을 적고, 그 안에 종류(type)와 주소(url)를 적은 형식이에요. 로컬 서버라면 url 대신 command(켜는 프로그램)와 args(그 프로그램에 넘길 말)를 적어요.
지켜야 할 것이 몇 가지 있어요.
- 원격 서버인데 type 을 빼먹으면 안 돼요. type 이 없으면 로컬 서버로 읽어서, url 만 있는 줄은 오류로 건너뛴다고 적혀 있어요. 문서들에 나오는 streamable-http 는 http 와 같은 뜻으로 받아 줘요.
- 파일은 클로드 코드를 켤 때 읽어요. 고친 뒤에는 클로드 코드를 나갔다가 다시 켜요.
- 처음 보는 .mcp.json 서버는 켤 때 승인을 물어요. 남이 만든 저장소를 받았다고 내 컴퓨터에서 프로그램이 멋대로 켜지지 않게 하려는 장치예요. 놓쳤으면 /mcp 에서 승인하고, 예전에 거절한 걸 되돌리려면 claude mcp reset-project-choices 예요.
- 파일에 쓴 줄 하나가 잘못돼도 그 줄만 건너뛰고 나머지는 읽어요. 어느 항목이 틀렸는지는 claude mcp list 에 경고로 나와요.
파일 위치도 자주 틀려요. 문서는 ~/.claude/.mcp.json, ~/.claude/mcp.json, %APPDATA%\Claude\mcp.json 같은 곳은 읽지 않는다고 적었어요. 읽는 곳은 홈의 .claude.json 과 프로젝트 맨 위의 .mcp.json 둘뿐이에요.
다른 도구 안내 옮기기
MCP 서버는 클로드 코드 전용이 아니라서, 서버 안내문이 다른 프로그램(Claude Desktop 등) 기준으로만 적혀 있을 때가 있어요. 문서는 안내문에서 셋 중 하나를 찾으라고 해요.
- https:// 주소가 있으면 원격 서버: claude mcp add --transport http 이름 주소
- npx, uvx 같은 켜는 명령이 있으면 로컬 서버: claude mcp add 이름
--그 명령 - “mcpServers” 로 시작하는 JSON 블록이 있으면 claude mcp add-json 이나 .mcp.json 에 옮기기
add-json 은 JSON 한 블록을 그대로 받아 서버를 등록하는 명령이에요. 문서 예시는 맥·리눅스 터미널 형식이라 JSON 을 작은따옴표로 감싸요. 그런데 윈도우에 기본으로 깔린 PowerShell 5.1 에서는 이렇게 넘긴 JSON 의 큰따옴표가 프로그램에 닿기 전에 빠져요. 이 PC 에서 node 로 프로그램이 받은 글자를 출력해 봤어요.
첫 번째는 문서 형식 그대로 넘긴 것이고, 받은 글자에서 큰따옴표가 다 사라졌어요. 이러면 JSON 으로 못 읽어요. 두 번째처럼 큰따옴표마다 앞에 \ 를 붙이면 그대로 넘어가요. 이 시험은 node 로 한 거예요. claude mcp add-json 도 같은 길로 글자를 받으니 같은 일이 생길 거라고 보지만, claude 로는 따로 돌려 보지 않았어요(미확인). PowerShell 7 은 이 PC 에 없어서 보지 못했어요.
그래서 윈도우 초보라면 add-json 보다 두 방법을 권해요. 주소나 켜는 명령을 찾아 claude mcp add 로 붙이거나, 메모장으로 .mcp.json 을 만들어 JSON 을 그대로 붙여 넣는 거예요. 파일에는 따옴표 문제가 없어요. 메모장은 저장할 때 파일 형식이 텍스트 문서(*.txt)로 설정돼 있어서 그대로 두면 .mcp.json.txt 가 돼요. 저장 창에서 파일 형식을 모든 파일로 바꾸고 이름을 .mcp.json 으로 적어요. 문서 예시 가운데 줄 끝에 \ 를 달고 다음 줄로 넘긴 긴 명령(맥·리눅스 형식)도 PowerShell 에서는 그대로 안 되니, 한 줄로 이어 붙여 쳐요.
Claude Desktop 에 붙여 둔 서버를 가져오는 claude mcp add-from-claude-desktop 은 도움말과 문서 모두 맥과 WSL(윈도우 안의 리눅스) 전용이라고 적었어요. 윈도우 PowerShell 에서는 안 돼요.
권한 규칙 mcp__
MCP 도구도 클로드 코드의 권한 설정을 따라요. 매번 묻는 게 번거로운 서버라면 규칙으로 미리 허락해 둘 수 있어요. 규칙에 쓰는 이름 형식은 이래요.
{
"permissions": {
"allow": ["mcp__claude-code-docs"]
}
}설정 파일(settings.json)에 이렇게 적으면 claude-code-docs 서버의 도구는 묻지 않고 쓰라는 뜻이에요. 나만 쓸 규칙이면 홈 폴더의 ~/.claude/settings.json(윈도우라면 사용자 폴더 안 .claude 폴더의 settings.json), 이 프로젝트에만 둘 규칙이면 프로젝트 안 .claude/settings.json 에 적어요. mcp__ 뒤에 내가 지은 서버 이름, 그 뒤에 __ 와 도구 이름을 붙이면 도구 하나만 가리켜요. 앞뒤 밑줄이 두 개씩이라 틀리기 쉬워요.
권한 문서에 몇 줄이 더 있어요. allow 규칙에 별표(*)를 쓰려면 mcp__서버이름__ 까지는 글자로 적어야 해요. “mcp__*” 처럼 서버까지 별표로 허락하는 규칙은 경고와 함께 무시돼요. 반대로 막는 deny 규칙의 “mcp__*” 는 모든 MCP 도구를 막아요. 규칙 형식 전체와 권한 모드는 클로드 코드 권한 설정 글에 있어요. claude.ai 커넥터의 도구는 mcp__claude_ai_서버__도구 형식 이름으로 나타나요.
@ 자료와 / 명령
서버에 따라 도구 말고 두 가지를 더 내주기도 해요.
- 자료(resource): 입력 칸에 @ 를 치면 파일과 함께 서버가 내준 자료도 목록에 떠요. @서버이름:주소 형식으로 가리키면 그 내용을 붙여서 보내요.
- 프롬프트(prompt): 서버가 미리 만들어 둔 요청 템플릿이에요. / 를 치면 /서버이름:프롬프트이름 (MCP) 형식으로 명령 목록에 섞여 나와요. /mcp__서버이름__프롬프트이름 으로 쳐도 되고, 뒤에 띄어쓰기로 값을 붙여요.
어떤 서버가 무엇을 내주는지는 서버마다 달라서, 붙인 뒤 /mcp 에서 그 서버를 골라 보면 도구 목록이 나와요.
더 깊이: 컨텍스트
여기부터는 서버를 여럿 붙여 쓰거나, 한도·컨텍스트를 아끼고 싶을 때 볼 부분이에요. 서버를 많이 붙이면 대화가 무거워지지 않을까 걱정되죠. 클로드 코드는 이걸 “도구 검색”으로 줄여요.
처음에는 도구 이름과 서버 안내문만 싣고, 도구를 자세히 설명하는 긴 글은 Claude 가 그 도구가 필요해질 때 찾아 읽어요. 기본으로 켜져 있어요. 서버마다 도구 개수 상한은 없고, 실제 한계는 컨텍스트 크기라고 적혀 있어요. 도구 설명과 서버 안내문은 하나당 2,048 자에서 잘린다고도 적혀 있어요.
손볼 수 있는 곳은 두 군데예요.
- ENABLE_TOOL_SEARCH 환경 변수: false 면 모든 도구를 처음부터 다 싣고, auto 면 도구 설명을 다 합쳐 컨텍스트의 10% 아래일 땐 처음부터 싣고 10% 에 이르면 미뤄요(auto:5 처럼 퍼센트를 바꿀 수 있음). 손대지 않으면 기본값(미루기)이에요.
- alwaysLoad: .mcp.json 의 서버 항목에 “alwaysLoad”: true 를 넣으면 그 서버 도구만 늘 처음부터 실어요. 매번 쓰는 도구 몇 개에만 쓰라고 문서가 권해요. 켜면 클로드 코드가 켜질 때 그 서버를 최대 5초까지 기다린다고 적혀 있어요.
도구가 돌려준 결과가 너무 길 때도 막아 주는 장치가 있어요.
토큰은 AI 가 글을 잘게 쪼개 세는 단위예요. 결과가 10,000 토큰을 넘으면 경고가 뜨고, 기본 상한은 25,000 토큰이에요. 상한을 넘거나 글자가 50,000 자를 넘는 결과는 대화에 통째로 넣지 않고 파일로 저장한 뒤 그 경로만 알려 줘서, Claude 가 필요할 때 파일을 읽어요. 상한을 올리려면 PowerShell 에서 이렇게 켜요.
$env:MAX_MCP_OUTPUT_TOKENS = "50000"; claude이 창에서만 MCP 출력 상한을 50,000 토큰으로 올리고 클로드 코드를 켜라는 줄이에요. 문서 예시(export, 맥·리눅스 형식)를 PowerShell 형식으로 옮겼어요. 상한을 올리면 그만큼 대화가 빨리 길어지니 꼭 필요할 때만 올려요. 컨텍스트가 한도와 어떻게 이어지는지는 프롬프트 캐시 글과 사용량 확인 글에 있어요. /usage 의 분석 칸은 MCP 서버별로 한도를 몇 % 썼는지도 보여 줘요.
서브에이전트(일을 나눠 맡는 작은 Claude)의 설정에만 MCP 서버를 적어 두면 메인 대화 창을 차지하지 않는다는 요령은 서브에이전트 글에 있어요.
환경 변수와 토큰
팀이 .mcp.json 을 나눠 쓸 때 토큰을 파일에 그대로 적으면 깃에 올라가 버려요. 그래서 .mcp.json 은 환경 변수를 끼워 넣는 형식을 받아요.
{
"mcpServers": {
"api-server": {
"type": "http",
"url": "${API_BASE_URL:-https://api.example.com}/mcp",
"headers": { "Authorization": "Bearer ${API_KEY}" }
}
}
}${API_KEY} 자리에 각자 컴퓨터의 API_KEY 환경 변수 값이 들어가요. ${이름:-기본값} 은 그 변수가 없으면 뒤의 값을 쓰라는 뜻이에요. command·args·env·url·headers 에서 쓸 수 있어요. 변수가 없고 기본값도 없으면 ${API_KEY} 글자가 그대로 들어가고, claude mcp list 에 빠진 변수 경고가 떠요.
일부러 막아 둔 이름도 있어요. ANTHROPIC_API_KEY 처럼 클로드 코드 자신의 키, 클라우드 회사의 키, NPM_TOKEN 같은 비밀 값은 원격 서버의 url·headers 에 넣어도 빈 값으로 읽혀요. 저장소에 든 설정이 내 클로드 키를 남의 서버로 보내는 일을 막으려는 거예요. 꼭 넘겨야 하면 내가 지은 다른 이름의 변수에 옮겨 담아 쓰라고 적혀 있어요.
토큰을 복사해 붙일 때 끝에 줄바꿈이나 띄어쓰기가 딸려 오는 일이 잦아요. 클로드 코드는 이걸 지우지 않고 그대로 쓰는 대신, claude mcp list 와 /mcp 에 “Leading or trailing whitespace in: headers.Authorization” 같은 경고를 띄워요. 로그인 실패가 이상하게 계속되면 이 경고부터 봐요.
믿을 만한 서버만
MCP 서버는 내 컴퓨터에서 프로그램을 켜거나, 내 계정으로 바깥 서비스를 만져요. 문서 맨 앞 경고도 “연결하기 전에 믿을 수 있는 서버인지 확인하라”예요. 특히 웹 페이지나 남이 쓴 글을 가져오는 서버는 프롬프트 주입에 노출될 수 있다고 적혀 있어요. 프롬프트 주입은 가져온 글 속에 “이전 지시는 무시하고 이렇게 해라” 같은 문장을 숨겨 AI 를 엉뚱하게 움직이려는 수법이에요.
지키면 좋은 것을 문서 내용에서 모으면 이래요.
- 서비스 회사가 직접 낸 서버, 또는 Anthropic 디렉터리(claude.ai/directory)에서 검토된 커넥터부터 고르기.
- 데이터베이스 서버는 읽기만 되는 계정으로 붙이기(문서의 PostgreSQL 예시가 그렇게 권함).
- 토큰은 필요한 저장소·권한만 준 것으로 만들기, 안 쓰는 서버는 지우기.
- 남이 만든 저장소의 .mcp.json 승인 창은 무엇을 켜는지 보고 승인하기.
거꾸로 클로드 코드 자체를 다른 프로그램의 MCP 서버로 쓸 수도 있어요. claude mcp serve 로 켜면 다른 MCP 프로그램이 클로드 코드의 도구(파일 읽기·고치기 등)를 호출해 쓸 수 있어요. 이때 도구마다 허락을 묻는 일은 호출하는 쪽 프로그램이 맡아야 한다고 적혀 있어요. 초보라면 쓸 일이 거의 없어서 이름만 알아 두면 돼요.
막힐 때
문제가 생기면 터미널에서는 claude mcp list, 클로드 코드 안에서는 /mcp 로 상태부터 봐요. /mcp 창에서는 나가지 않고 다시 연결(Reconnect)하거나 로그인할 수 있어요. 빠른 시작의 문제 해결 부분에서 자주 나오는 것을 옮겼어요.
| 보이는 것 | 흔한 이유 | 해 볼 것 |
|---|---|---|
| /mcp 에 No MCP servers configured | 다른 폴더에서 local 로 붙임, 엉뚱한 파일을 고침 | 지금 폴더에서 다시 붙이거나 --scope user |
| ✘ Failed to connect | 주소가 틀림, 서버가 안 켜짐, 토큰 거절 | claude mcp get 이름 의 Issue 줄, curl.exe -I 주소 |
| 켤 때 시간 초과 | npx 가 처음 받느라 30초 넘김 | $env:MCP_TIMEOUT 늘리기 |
| already exists | 같은 범위에 같은 이름 | remove 하거나 다른 이름 |
| 연결은 되는데 도구 0개 | 필요한 환경 변수(API 키)가 빠짐 | -e 이름=값 으로 넣기 |
| .mcp.json 고쳤는데 그대로 | 켤 때만 읽음, 예전에 거절함 | 다시 켜기, reset-project-choices |
출처: 클로드 코드 문서 mcp-quickstart 문제 해결. 10월 8일 확인.
원격 서버가 내 컴퓨터에서 닿기는 하는지는 curl.exe 로 봐요. PowerShell 에서는 curl 이 다른 명령(Invoke-WebRequest)의 별칭이라 꼭 curl.exe 로 쳐야 한다고 문서에 적혀 있어요. 이 PC 에서 문서 서버와 센트리 서버에 쳐 봤어요.
curl.exe -sI https://code.claude.com/docs/mcp이 주소에 헤더만 달라고 요청해서 대답이 오는지 보는 줄이에요(-s 는 진행 표시 숨기기, -I 는 헤더만). 문서가 대답 숫자를 이렇게 읽으라고 적었어요.
- 404·405: 서버는 살아 있어요. MCP 주소는 POST 라는 요청만 받는 곳이 많아서 이렇게 나와도 닿기는 한 거예요. 문서 서버가 405 였어요.
- 401·403: 서버는 살아 있고 로그인이 필요해요. 센트리가 401 이었고, 헤더에 OAuth 로그인 안내(WWW-Authenticate)가 붙어 왔어요.
- 아무 대답이 없으면: 주소나 인터넷 연결을 봐요.
로컬 서버가 안 켜지면 -- 뒤에 적은 명령을 터미널에 그대로 쳐 보라고 문서에 적혀 있어요. 켜져서 입력을 기다리면 서버는 멀쩡한 거고, 오류가 나면 그 문구가 빠진 것(Node.js, 브라우저 등)을 알려 줘요. 이 PC 에서는 서버 프로그램을 받아 켜는 것까지는 하지 않았어요.
켜질 때 기다리는 시간은 기본 30초예요. 늘리려면 이렇게 켜요.
$env:MCP_TIMEOUT = "60000"; claude이 창에서 MCP 서버를 켤 때 60,000 밀리초(60초)까지 기다리게 하고 클로드 코드를 켜라는 줄이에요. 문서에 실린 PowerShell 형식 그대로예요.
VS Code 확장에서도 대화 창에 /mcp 를 치면 같은 관리 창이 열리고, 2.1.261 부터는 거기서 서버를 더하고 지울 수도 있어요. VS Code 안의 터미널(Ctrl+`)에서 claude mcp add 를 쳐도 같은 설정에 저장된다고 적혀 있어요.
코덱스·안티그래비티는
다른 터미널 코딩 도구도 MCP 를 받아요. 붙이는 명령은 셋이 거의 같고, 설정 파일 이름과 원격 주소 필드 이름이 달라요.
| 무엇 | 클로드 코드 | 코덱스 CLI | 안티그래비티 CLI |
|---|---|---|---|
| 더하는 명령 | claude mcp add | codex mcp add | agy mcp add |
| 나만 쓰는 설정 | 홈의 .claude.json | 홈의 .codex\config.toml | 홈의 .gemini\config\mcp_config.json |
| 폴더 전용 설정 | .mcp.json(켤 때 승인) | .codex\config.toml(믿는 프로젝트만) | .agents\mcp_config.json |
| 원격 주소 필드 | type 과 url | url | serverUrl |
| 안에서 보기 | /mcp | /mcp | /mcp |
| 로그인 | /mcp, claude mcp login | codex mcp login | login 명령 없음, /mcp 창의 Authenticate(바뀐 점 기록) |
| 도구를 처음 쓸 때 | 권한 설정을 따름(문서 예시는 물어봄) | 서버·도구마다 고르는 설정, 기본값 미확인 | 규칙이 없으면 물어봄(Ask) |
출처: 클로드 코드 문서 mcp-quickstart·mcp·permissions, OpenAI 코덱스 문서 Model Context Protocol, 안티그래비티 문서 MCP. agy mcp add 는 안티그래비티 CLI 사용법 글에서 받은 프로그램 도움말로 확인한 것. 10월 8일 확인.
코덱스 문서의 CLI 예시는 로컬 서버(-- 뒤에 켜는 명령)만 보여 주고, 원격 서버는 config.toml 에 [mcp_servers.이름] 항목을 만들어 url 을 적는 길로 설명해요. 다만 프로그램 도움말(codex mcp add --help)에는 --url 로 주소 서버를 한 줄에 붙이는 길도 있어요(코덱스 CLI MCP 글). ChatGPT 데스크톱 앱과 코덱스 CLI·IDE 확장은 같은 설정을 같이 쓴다고 적혀 있어요. 도구마다 default_tools_approval_mode 로 auto·prompt·writes·approve 중 하나를 고를 수 있는데, 아무것도 안 적었을 때 어느 쪽인지는 이번에 읽은 문서에서 찾지 못했어요.
안티그래비티는 제미나이 CLI 에서 옮겨 왔다면 원격 서버 필드 이름을 url·httpUrl 에서 serverUrl 로 바꿔야 해요. 문서의 OAuth 부분은 서버가 자동 등록(DCR)을 받으면 따로 설정할 게 없다고 하고, 로그인 순서는 설정 화면(Agent settings)의 Authenticate 버튼으로 설명해요. CLI 화면에서 같은 순서인지는 문서에서 찾지 못했어요. 권한 규칙은 mcp(서버/도구) 형식이에요.
제 생각에는 세 도구를 같이 쓰는 분이라면, 붙이는 명령보다 “설정이 어느 파일에 들어갔나”를 기억하는 게 나아요. 명령은 셋이 비슷해서 금방 손에 익지만, 파일 이름과 주소 필드 이름이 달라서 한쪽 설정을 다른 쪽에 그대로 복사하면 안 돌아가요. 코덱스 쪽 쓰는 법은 코덱스 CLI 사용법 글에 있어요.
한국에서 되나
| 질문 | 답 |
|---|---|
| 한국에서 되나 | 됨(Anthropic 지원 국가 목록에 South Korea) |
| 무슨 요금제 | 클로드 코드를 쓰는 요금제(Pro·Max·Team·Enterprise·Console). MCP 만 따로 막는 요금제 안내는 문서에 없음 |
| 한국어 문서 | 있음(code.claude.com/docs/ko/mcp-quickstart) |
| claude.ai 커넥터 | claude.ai 구독 로그인일 때만 따라옴. Team·Enterprise 는 관리자만 추가 |
| VS Code /mcp 창에서 더하기·지우기 | 2.1.261 부터 |
출처: 클로드 코드 문서 mcp·mcp-quickstart·vs-code, anthropic.com 지원 국가 목록. 10월 8일 확인.
MCP 서버 쪽 서비스(노션·센트리 등)가 한국에서 되는지, 그 서비스의 요금제가 무엇인지는 서비스마다 따로 봐야 해요. 클로드 코드는 연결만 해 줄 뿐이에요.
다음에 볼 글
MCP 도구를 묻지 않고 쓰게 하려면 권한 설정 글, 붙인 서버가 한도를 얼마나 먹는지 보려면 사용량 확인 글이에요. 클로드 코드를 아직 깔지 않았다면 윈도우 설치 글, 처음 쓰는 법은 클로드 코드 사용법 글부터 보면 돼요. 나머지 요령은 사용량 아끼는 법 모음에 차례로 있어요.
이 글의 내용은 2026년 10월 8일, 클로드 코드 2.1.292 기준이에요. MCP 쪽은 버전마다 상태 글자와 경고 문구가 조금씩 바뀌고 있어요. 글과 다르게 보이면 공식 문서의 지금 내용을 먼저 보세요.
같이 보면 좋은 글: 클로드 코드 권한 설정 allow·ask·deny: 규칙 적는 형식과 덜 묻게 하는 방법
같이 보면 좋은 글: 클로드 코드 사용량 아끼는 법: 대화·캐시·서브에이전트부터 스킬·훅·권한 설정까지
같이 보면 좋은 글: AI 비교 2026: 클로드·챗GPT·제미나이 요금제·한도·기능 표
같이 보면 좋은 글: 클로드 코드 플러그인 설치하는 법: /plugin 으로 깔고 끄고 지우기, 직접 만들기까지
같이 보면 좋은 글: 클로드 코드 /context 사용법: 대화 창 얼마나 찼나 보기부터 줄이는 순서·창 크기까지
참고한 자료
2026년 10월 8일에 확인했어요. 클로드 코드 문서는 영어 문서와 한국어 문서(/docs/ko/)를 같이 봤어요.
- Connect to MCP servers (클로드 코드 공식 문서, 첫 서버 붙이기·상태 표·범위와 파일·.mcp.json·문제 해결)
- Connect Claude Code to tools via MCP (클로드 코드 공식 문서, 서버 종류·
--구분·범위 우선순위·환경 변수·로그인·claude.ai 커넥터·도구 검색·출력 한도·자료·프롬프트) - Configure permissions (클로드 코드 공식 문서, mcp__ 규칙)
- VS Code (클로드 코드 공식 문서, /mcp 창에서 서버 더하기)
- Changelog (클로드 코드 공식 문서)
- Supported countries (Anthropic, South Korea)
- Model Context Protocol (OpenAI 코덱스 공식 문서, codex mcp add·config.toml·승인 설정)
- Model Context Protocol (안티그래비티 공식 문서, mcp_config.json·serverUrl·OAuth·권한)
광고 · 쿠팡 추천 상품
이 포스팅은 쿠팡 파트너스 활동의 일환으로, 이에 따른 일정액의 수수료를 제공받습니다.
