커뮤니티 입장하기

클로드 코드 MCP 서버 연결하기 (설정 파일, 권한, 오류)

클로드 코드의 MCP 서버 연결은 claude mcp add 명령이나 .mcp.json 파일로 외부 도구 서버를 등록해 클로드가 그 도구를 쓰게 하는 설정입니다. 등록 범위는 local, project, user 세 가지이고, 연결 상태와 인증은 /mcp에서 확인합니다.

같은 말:클로드 코드 MCP 설정claude mcp add.mcp.jsonMCP 연결 오류MCP scope

게시 코스 6 / 10번째 개념
새로 올라온 개념이에요. 먼저 읽어 보고 퀴즈도 풀어 보세요
#AI#자동화#API
Share
목차
  1. 🤔 MCP 서버를 추가했는데 도구가 보이지 않을 때
  2. 🔑 MCP 서버 연결의 정의
  3. ⌨️ 서버를 추가하는 명령 형식
  4. 📂 범위와 저장 위치
  5. 🔑 토큰과 인증 넣는 법
  6. ✅ 프로젝트 서버 승인과 도구 권한
  7. 🧯 연결이 안 될 때 확인 순서
  8. ⚠️ 자주 하는 실수
  9. ❓ 자주 묻는 질문
  10. 📋 3줄 요약
  11. 📚 참고 자료

이 글은 앤트로픽이 운영하는 code.claude.com/docs의 MCP 문서와 설정 문제 해결 문서를 한국어 사용자가 실무에 바로 옮길 수 있도록 정리한 글입니다. 명령과 설정 키는 2026년 9월 28일 공식 문서 기준이고, 원문 링크는 글 끝 참고 자료에 모았습니다.

🤔 MCP 서버를 추가했는데 도구가 보이지 않을 때

노션이나 깃허브 MCP 서버를 연결하라는 글을 따라 명령을 입력하면 "Added"라는 성공 메시지가 나옵니다. 그런데 막상 클로드에게 노션 페이지를 찾아 달라고 하면 그런 도구가 없다고 합니다. 설정 파일을 열어 보면 어떤 글은 .mcp.json, 어떤 글은 settings.json, 어떤 글은 ~/.claude.json에 적으라고 해서 어디가 맞는지부터 헷갈립니다.

MCP가 무엇인지는 입문 코스의 MCP 알아보기에 있습니다. 지금부터는 실제로 서버를 추가하는 명령 형식, 범위별 저장 위치, 토큰과 인증을 넣는 방법, 도구 권한 이름, 연결이 안 될 때 확인하는 순서를 정리합니다.

🔑 MCP 서버 연결의 정의

클로드 코드의 MCP 서버 연결은 claude mcp add 명령이나 .mcp.json 파일로 외부 도구 서버를 등록해 클로드가 그 도구를 쓰게 하는 설정입니다.

MCP 서버는 연결 방식에 따라 두 가지로 나뉩니다. 인터넷 주소로 접속하는 원격 서버는 HTTP 방식을 쓰고, 내 컴퓨터에서 프로그램을 실행해 연결하는 로컬 서버는 stdio(표준 입출력) 방식을 씁니다. 예전의 SSE 방식은 공식 문서에서 사용 중단 예정으로 표시되어 있고, HTTP를 쓰라고 안내합니다.

⌨️ 서버를 추가하는 명령 형식

원격 서버는 이름과 주소를 적습니다.

claude mcp add --transport http notion https://mcp.notion.com/mcp

토큰을 헤더로 넘기는 서버라면 --header를 붙입니다.

claude mcp add --transport http secure-api https://api.example.com/mcp --header "Authorization: Bearer your-token"

로컬 서버는 -- 뒤에 실행 명령을 적습니다.

claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable -- npx -y airtable-mcp-server

여기서 --는 클로드 코드의 옵션과 서버 실행 명령을 나누는 구분자입니다. 빠뜨리면 서버에 넘길 --port 같은 옵션을 클로드 코드가 자기 옵션으로 읽습니다. --env 바로 뒤에 서버 이름을 두면 이름까지 환경 변수로 읽어 거부하므로, 공식 예시처럼 --transport stdio를 사이에 둡니다.

다른 도구용 안내에 JSON 설정만 있다면 claude mcp add-json 이름 '{"command":"npx","args":["-y","@example/mcp-server"]}'처럼 안쪽 객체만 넘깁니다. 관리 명령은 claude mcp list(목록과 상태), claude mcp get 이름(상세), claude mcp remove 이름(삭제)이고, 세션 안에서는 /mcp를 씁니다.

📂 범위와 저장 위치

--scope(짧게 -s)로 누가 쓸 서버인지 정합니다. 이 부분이 가장 많이 헷갈립니다.

범위저장 위치쓰는 사람
local (기본값)~/.claude.json의 현재 프로젝트 항목이 프로젝트에서 나만
project프로젝트 루트의 .mcp.json저장소를 받은 팀 전체
user~/.claude.json내 모든 프로젝트

알아 둘 함정이 세 가지 있습니다.

  • MCP의 local은 홈 폴더에 저장됩니다: 이름이 같아도 일반 설정의 .claude/settings.local.json과 다른 파일입니다
  • settings.json은 MCP 서버를 읽지 않습니다: settings.json에 mcpServers를 적거나, .mcp.json을 .claude/ 폴더 안에 두면 로드되지 않습니다
  • 같은 서버가 여러 범위에 있으면: local, project, user, 플러그인, claude.ai 커넥터 순서로 앞선 것 하나를 통째로 씁니다. 항목을 섞어 쓰지 않습니다

~/.claude.json은 앱 상태와 MCP 설정이 들어가는 파일이고, 권한과 훅은 ~/.claude/settings.json에 둡니다. 두 파일 이름이 비슷해서 서로 바꿔 적는 실수가 잦습니다.

🔑 토큰과 인증 넣는 법

.mcp.json을 팀과 공유할 때는 토큰을 파일에 직접 적지 않고 환경 변수로 넘깁니다. .mcp.json은 ${VAR}와 기본값을 주는 ${VAR:-default} 문법을 command, args, env, url, headers에서 받습니다.

{ "mcpServers": { "api-server": { "type": "http", "url": "${API_BASE_URL:-https://api.example.com}/mcp", "headers": { "Authorization": "Bearer ${API_KEY}" } } } }

변수가 비어 있고 기본값도 없으면 ${API_KEY}라는 글자가 그대로 전송되고 claude mcp list에 경고가 뜹니다. 주소만 있고 "type"이 빠진 항목은 로컬 서버로 해석되어 실패하므로 "type": "http"를 꼭 넣습니다.

OAuth로 로그인하는 원격 서버는 세션 안에서 /mcp를 열고 서버를 골라 브라우저 로그인을 따라갑니다. 터미널에서 바로 하려면 claude mcp login 이름을 쓰고, SSH 원격 환경이라 브라우저가 없으면 --no-browser로 로그인 주소만 받습니다. claude -p 같은 비대화형 실행에서는 로그인 창을 띄울 수 없으므로 대화형 세션에서 먼저 로그인해 둡니다.

✅ 프로젝트 서버 승인과 도구 권한

저장소에 들어 있는 .mcp.json의 서버는 보안상 처음 쓰기 전에 승인을 묻습니다. 승인 창을 그냥 닫았다면 /mcp에서 승인하기 전까지 꺼진 상태로 남고, 지난 선택을 초기화하려면 claude mcp reset-project-choices를 씁니다. v2.1.196 이상에서는 남의 저장소가 설정 파일에 "모든 MCP 서버 자동 승인"을 넣어 두어도 신뢰하지 않은 폴더에서는 그 설정을 무시합니다.

MCP 도구에도 권한 규칙을 걸 수 있습니다. 이름 형식은 mcp__서버이름__도구이름입니다.

규칙적용 대상
mcp__github 또는 mcp__github__*github 서버의 모든 도구
mcp__github__create_issue그 도구 하나
mcp__claude_ai_서버__도구claude.ai에서 연결한 커넥터 도구

읽기 도구는 allow에, 쓰기나 삭제 도구는 ask에 넣어 두면 승인 창이 줄면서도 되돌리기 어려운 작업은 한 번 더 확인하게 됩니다.

🧯 연결이 안 될 때 확인 순서

claude mcp add는 설정을 적기만 하고 연결이나 자격 증명을 검증하지 않습니다. 자리표시자 토큰을 넣어도 "Added"가 뜨고, 나중에 연결할 때 실패합니다. 그래서 추가한 뒤에는 반드시 상태를 봅니다.

  1. claude mcp list로 상태 확인: ✔ Connected면 정상, ! Needs authentication이면 /mcp에서 로그인, ✘ Failed to connect면 다음 단계로 넘어갑니다
  2. claude mcp get 이름의 Issue: 줄: HTTP 상태 코드나 오류 코드가 나옵니다. 401이면 토큰, 연결 거부면 주소나 실행 명령을 봅니다
  3. ⏸ Pending approval: 프로젝트 서버를 아직 승인하지 않은 상태입니다. claude를 실행해 승인합니다
  4. 연결됐는데 도구가 0개: /mcp에서 Reconnect를 누르고, 그래도 없으면 claude --debug=mcp로 실행해 ~/.claude/debug/ 아래 로그에서 서버 오류를 읽습니다
  5. 로컬 서버가 파일을 못 찾음: command와 args의 상대 경로는 .mcp.json 위치가 아니라 클로드 코드를 실행한 폴더 기준으로 풀립니다. 절대 경로로 바꿉니다

서버가 느리게 켜진다면 MCP_TIMEOUT 환경 변수(밀리초, 기본 30초)로 시작 대기 시간을 늘립니다. 도구 결과가 너무 길면 10,000토큰에서 경고가 뜨고 기본 25,000토큰에서 잘리므로, 한도는 MAX_MCP_OUTPUT_TOKENS로 조정합니다. 다른 설치 문제와 함께 보는 확인 순서는 클로드 코드 자주 나는 문제와 해결에 있습니다.

⚠️ 자주 하는 실수

  • "Added"를 연결 성공으로 믿습니다: 설정 저장 성공일 뿐입니다
  • 토큰을 .mcp.json에 그대로 적고 저장소에 올립니다: ${VAR}로 바꾸고 실제 값은 각자의 환경 변수에 둡니다
  • 토큰을 복사할 때 앞뒤 공백이 딸려 옵니다: 클로드 코드는 공백을 자동으로 지우지 않고 경고만 띄웁니다
  • 같은 이름으로 다시 추가합니다: 같은 범위에 같은 이름이 있으면 "already exists"로 실패합니다. 지우고 다시 추가합니다

❓ 자주 묻는 질문

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

/mcp 화면에서 서버를 끄면 설정은 남고 연결만 끊깁니다. 이 선택은 프로젝트마다 따로 기록되고, 다시 켤 때도 /mcp에서 켭니다.

클로드 데스크톱에 등록한 서버를 가져올 수 있나요?

claude mcp add-from-claude-desktop으로 가져올 수 있습니다. 공식 문서 기준으로 맥과 WSL에서만 동작합니다.

MCP 서버가 많으면 컨텍스트를 많이 쓰나요?

도구 검색 기능이 기본으로 켜져 있어서 세션 시작 때는 도구 이름과 서버 안내만 싣고, 필요한 도구의 상세는 쓸 때 불러옵니다. 그래도 쓰지 않는 서버는 /mcp에서 꺼 두는 편이 깔끔합니다.

📋 3줄 요약

  1. 클로드 코드는 claude mcp add로 MCP 서버를 등록하며 원격 서버는 --transport http와 주소로, 로컬 서버는 -- 뒤에 실행 명령을 적어 stdio로 추가합니다.

  2. 기본 범위 local과 user는 홈 폴더의 ~/.claude.json에, 팀과 공유하는 project 범위는 프로젝트 루트의 .mcp.json에 저장되고 settings.json은 MCP 서버를 읽지 않습니다.

  3. claude mcp add의 Added 출력은 설정을 적었다는 뜻일 뿐이라 연결 여부는 claude mcp list나 /mcp의 Connected 표시로 확인합니다.

📚 참고 자료

Share

제대로 이해했는지 한 문제로 확인해 볼까요?

답을 고르면 바로 풀이가 나와요.

claude mcp add 명령에 --scope project를 주어 추가한 MCP 서버 설정은 어디에 저장될까요?

7개념 / 클래스클로드 코드 Git 작업 흐름 (브랜치, 커밋, 워크트리)

이어서 배우면 좋은 개념

관련 글