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

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

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

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

먼저 MCP가 무엇인지 짧게 정리하고, 이어서 실제로 서버를 추가하는 명령 형식, 범위별 저장 위치, 토큰과 인증을 넣는 방법, 도구 권한 이름, 연결이 안 될 때 확인하는 순서를 정리합니다.

🧭 MCP 뜻: AI 앱과 외부 도구를 잇는 표준 규격

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 AI 앱이 외부 시스템과 연결되는 방식을 정한 오픈소스 표준 규격입니다. 여기서 외부 시스템은 내 컴퓨터의 파일이나 데이터베이스 같은 자료, 검색 엔진이나 계산기 같은 도구, 미리 만들어 둔 프롬프트 같은 작업 흐름을 말합니다. MCP 공식 소개는 MCP를 "AI 앱을 위한 USB-C 포트"에 비유합니다. USB-C 단자 하나로 여러 전자 기기를 연결하듯, AI 앱도 MCP라는 공통 방식으로 여러 서비스와 연결된다는 뜻입니다.

MCP는 앤트로픽이 2024년 11월 25일 오픈소스로 공개했고, 2025년 12월 9일 리눅스 재단 산하의 Agentic AI Foundation(AAIF)에 기부했습니다. 그래서 지금은 앤트로픽 전용 규격이 아닙니다. MCP 공식 소개에 따르면 Claude와 ChatGPT 같은 AI 어시스턴트, Visual Studio Code와 Cursor 같은 개발 도구가 MCP를 지원합니다.

MCP 연결은 세 가지 역할로 나뉩니다.

클로드가 Notion 페이지 검색 도구를 쓰기로 하면 클로드 코드가 그 요청을 Notion MCP 서버로 보내고, 서버가 실행한 결과를 다시 클로드에게 돌려줍니다. MCP는 이 주고받는 방식만 정하므로, Notion이나 깃허브에서 실제로 무엇을 읽고 바꿀 수 있는지는 각 서버가 제공하는 도구와 연결한 계정의 권한이 정합니다.

MCP 서버는 스킬과도 하는 일이 다릅니다. MCP 서버는 클로드가 외부 서비스에 접근하는 연결이고, 스킬은 그 연결을 어떤 순서로 쓸지 적어 둔 작업 절차입니다. 스킬만으로는 외부 서비스에 접근할 수 없습니다. 규격 원문과 공식 소개는 MCP 공식 사이트에 있습니다.

🔑 MCP 서버 연결의 정의

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

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

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

먼저 claude ... 명령은 운영체제의 터미널에, /mcp는 실행 중인 Claude Code 입력창에 적는다는 점을 구분합니다. 아래 Notion 예제는 등록 형식을 보여 줍니다. 기존에 같은 연결이 있다면 중복 추가하지 않고 뒤의 실습에서 상태부터 확인합니다.

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

토큰을 직접 --header나 --env 인자에 쓰면 명령 기록이나 설정에 남을 수 있습니다. Notion처럼 OAuth를 지원하면 /mcp의 로그인 절차를 먼저 사용합니다. OAuth는 서비스 로그인 화면에서 연결 앱의 접근을 허용하는 방식입니다. 헤더가 필요한 다른 서버는 아래 환경 변수 예제를 읽고 제공자의 인증 안내를 따릅니다.

로컬 서버의 명령 형식은 다음과 같습니다. 서버이름, 실행프로그램, 서버파일경로는 설명용 자리표시자이며 그대로 실행하지 않습니다.

-- 앞은 Claude Code 옵션이고 뒤는 서버 프로그램의 명령입니다. 다른 글의 npx -y ...를 복사하면 패키지를 내려받아 실행할 수 있으므로 제공자와 패키지 이름, 버전을 먼저 확인합니다. 서버에 넘길 옵션도 -- 뒤에 둡니다.

다른 도구용 안내에 JSON 설정만 있다면 claude mcp add-json에는 서버 이름과 서버 객체 하나를 넘깁니다. 전체 mcpServers 묶음을 그대로 넣는 것과 구분하고 제공자의 Claude Code 예제를 우선 확인합니다. 관리 명령은 claude mcp list(목록과 상태), claude mcp get 이름(상세), claude mcp remove 이름(삭제)이고, 세션 안에서는 /mcp를 씁니다.

📂 범위와 저장 위치

--scope(짧게 -s)로 어느 프로젝트와 사용자에게 설정을 적용할지 정합니다. local 범위는 설정을 어느 프로젝트에 적용할지만 정하며, 서버의 자료 접근을 현재 폴더로 제한하지는 않습니다.

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

• MCP의 local은 홈 폴더에 저장됩니다: 이름이 같아도 일반 설정의 .claude/settings.local.json과 다른 파일입니다
• 일반 settings.json의 mcpServers는 등록 위치가 아닙니다: settings.json에 mcpServers를 적거나, .mcp.json을 .claude/ 폴더 안에 두면 로드되지 않습니다
• 같은 서버가 여러 범위에 있으면: 일반 CLI 설정은 local, project, user 순서로 앞선 항목을 통째로 씁니다. 플러그인과 claude.ai 커넥터는 연결 주소 등으로 중복을 판단하며 우선순위가 뒤입니다. 조직이 관리 설정으로 제공한 서버는 이들보다 우선할 수 있습니다

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

🔑 토큰과 인증 넣는 법

아래 api.example.com은 설명용 주소라 실제 연결 실습 대상이 아닙니다. .mcp.json을 팀과 공유할 때는 토큰을 파일에 직접 적지 않고 환경 변수로 넘깁니다. .mcp.json은 ${VAR}와 기본값을 주는 ${VAR:-default} 문법을 command, args, env, url, headers에서 받습니다.

일반 변수가 설정되지 않았고 기본값도 없으면 ${API_KEY}라는 글자가 그대로 전송되고 claude mcp list에 경고가 뜹니다. 다만 ANTHROPIC_API_KEY 같은 보호 대상 인증 변수는 원격 서버의 URL과 헤더에서 빈 값으로 처리될 수 있습니다. Claude용 키를 다른 서버 인증에 재사용하지 말고, 연결하려는 서비스가 발급한 자격 증명을 씁니다. 주소만 있고 "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__서버이름__도구이름입니다.

처음에는 실제 도구 이름과 입력 내용을 보고 읽기 작업부터 확인합니다. 필요하면 확인한 읽기 도구만 allow에, 쓰기와 삭제 도구는 ask에 지정합니다. 읽기 도구도 외부 서비스로 검색어나 자료를 보내므로 무조건 전체 서버를 허용하지 않습니다. 조직 정책과 권한 모드도 실제 승인 동작에 영향을 줍니다.

🗂️ 업무 서비스에 MCP를 붙이는 방법과 연동이 없는 서비스

업무 서비스에 클로드를 연결하려면 먼저 그 서비스가 MCP를 어떤 형태로 제공하는지 봅니다. 제공 형태에 따라 등록 방법과 확인할 내용이 달라집니다.

같은 MCP 서버라도 할 수 있는 일은 서버마다 다릅니다. 예를 들어 Google Ads MCP 서버의 현재 공식 버전은 광고 계정 데이터를 읽기만 하는 읽기 전용입니다. 내 컴퓨터에서 실행하거나 구글의 서버 실행 서비스인 Cloud Run에 직접 올려 쓰며, 최신 버전은 OAuth 2.0 로그인이나 서비스 계정으로 인증합니다. Google Ads API를 쓸 때 발급받던 접근 키인 개발자 토큰은 2026년 9월 9일 종료되었고, 계정이 쓸 수 있는 API 범위는 이제 Google Cloud 프로젝트에 연결된 접근 등급으로 정해집니다. 그래서 Google Ads MCP 서버로는 성과 조회와 분석을 맡길 수 있지만 예산이나 입찰을 바꿀 수는 없습니다.

MCP 서버가 없는 서비스라면 먼저 필요한 자료를 CSV나 엑셀 파일로 내보낼 수 있는지 봅니다. 내보낸 파일을 작업 폴더에 두면 클로드 코드가 별도 연결 없이 그 파일을 읽습니다. 화면에서만 볼 수 있는 설정이라면 허용된 브라우저 조작 도구가 화면을 읽고 버튼을 누르게 하는 방법도 있습니다. 예를 들어 관리 화면의 여러 탭에 흩어진 설정을 확인해야 할 때, 브라우저 조작 도구가 탭을 하나씩 열어 설정값을 읽고 탭끼리 다른 조건을 표로 정리하게 할 수 있습니다. 다만 브라우저 조작은 로그인 절차와 서비스 약관, 회사 정책에 따라 막힐 수 있고 화면 구성이 바뀌면 다른 버튼을 누를 수 있으므로, 결과를 원래 화면과 대조합니다. 구성 방법은 연동 없는 서비스에 AI로 일 시키는 방법에 정리했습니다.

다루려는 대상이 워드, 엑셀, 파워포인트 파일이라면 명령줄 도구를 MCP 서버로 등록하는 방법도 있습니다. OfficeCLI는 AI 에이전트가 오피스 파일을 명령줄에서 읽고 고치고 만들도록 만든 오픈소스 도구이고, officecli mcp claude 명령 한 줄로 클로드 코드에 MCP 서버로 등록됩니다. 자세한 내용은 OfficeCLI 정리에 있습니다.

🧯 연결이 안 될 때 확인 순서

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에 cached라고 나오면 이전에 확인한 도구 목록을 재사용하고 첫 호출 때 연결하는 상태일 수 있습니다. 연결 실패와 구분하고 작은 읽기 작업으로 확인합니다. 오류 로그를 공유할 때는 토큰과 개인 자료를 제거합니다.

서버가 느리게 켜진다면 MCP_TIMEOUT 환경 변수(밀리초, 기본 30초)로 시작 대기 시간을 늘립니다. 도구 결과는 기본 10,000토큰에서 경고하고 기본 제한은 25,000토큰입니다. 도구가 자체 제한을 지정한 경우는 다를 수 있습니다. 먼저 검색 범위나 반환 건수를 줄이고, 필요한 경우에만 MAX_MCP_OUTPUT_TOKENS 설정을 검토합니다. 다른 설치 문제와 함께 보는 확인 순서는 클로드 코드 자주 나는 문제와 해결에 있습니다.

본문의 MCP 연결 점검 흐름입니다. 서버 정보를 등록한 것만으로 연결과 인증 검증이 끝난다는 뜻은 아닙니다.

⚠️ 자주 하는 실수

• "Added"를 연결 성공으로 믿습니다: 설정 저장 성공일 뿐입니다
• 토큰을 .mcp.json에 그대로 적고 저장소에 올립니다: 이미 공개된 키는 폐기하고 재발급하며, 이후에는 ${VAR} 참조와 별도 자격 증명 보관 방식을 씁니다
• 토큰을 복사할 때 앞뒤 공백이 딸려 옵니다: 클로드 코드는 공백을 자동으로 지우지 않고 경고만 띄웁니다
• 같은 이름으로 다시 추가합니다: 같은 범위에 같은 이름이 있으면 "already exists"로 실패합니다. 기존 주소와 범위를 먼저 확인하고, 바꿔야 한다면 그 항목만 백업 후 변경합니다

❓ 자주 묻는 질문

MCP와 API는 무엇이 다른가요?

API는 서비스가 다른 프로그램에게 열어 둔 연결 통로이고, MCP는 AI 앱이 여러 서비스의 도구를 같은 방식으로 쓰도록 맞춘 규격입니다. API를 쓰려면 서비스마다 다른 요청 형식에 맞춰 연동 코드를 따로 만들어야 합니다. MCP 서버는 그 서비스의 기능을 MCP 형식의 도구로 감싸서 제공하므로, 클로드 코드는 서버를 등록하는 것만으로 도구 목록을 받아 씁니다. MCP 서버가 늘 API를 거치는 것은 아니며, 파일이나 계산 도구를 직접 제공하는 서버도 있습니다. API 자체의 뜻은 API란에서 설명합니다.

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

/mcp 화면에서 서버를 끄면 설정은 남고 연결만 끊깁니다. 이 선택은 프로젝트마다 따로 기록되고, 다시 켤 때도 /mcp에서 켭니다. 연결을 끄거나 등록을 지우는 것과 서비스 쪽 OAuth 권한을 철회하는 것은 별개입니다. 서비스 쪽 권한을 철회하면 같은 인증을 쓰던 다른 작업에도 영향을 줄 수 있습니다.

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

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

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

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

Notion 가상 페이지 하나로 읽기 확인하기

Claude Code와 Notion 계정이 있고 연결을 허용한 연습 환경에서 진행합니다. Notion을 쓰지 않는다면 등록 범위와 오류 확인 순서까지만 읽고 새 계정이나 유료 결제를 만들지 않습니다.

1. Notion에서 직접 MCP 연결 연습 페이지를 만들고 날짜: 2026년 11월 12일, 장소: 2번 회의실을 적습니다. 실제 고객 자료는 넣지 않습니다.
2. CLAUDE.md 실습의 폴더와 터미널 안내를 따라 새 빈 폴더 mcp-practice에서 터미널을 열고 claude mcp list로 기존 연결을 확인합니다. 이미 Notion이 연결되어 있다면 그대로 사용합니다. 없다면 위의 공식 Notion 등록 명령을 이 폴더에서 실행합니다. 기본 local 범위로 저장됩니다.
3. claude를 실행하고 /mcp에서 Notion을 선택해 인증을 진행합니다. 연결되는 계정과 작업 공간 및 접근 권한을 읽고 허용 범위가 맞을 때 승인합니다. 연습 페이지를 만들었다고 접근 권한이 그 페이지로만 제한되는 것은 아닙니다.
4. Notion에서 연습 페이지의 링크를 복사해 “이 페이지를 읽고 날짜와 장소 두 줄로만 답해 주세요. 페이지 수정, 생성, 삭제는 하지 마세요”라고 요청합니다. 필요한 읽기 호출만 확인합니다. 호출 기록에서 어떤 서버의 도구를 썼는지도 확인하며 다른 검색 결과로 대신한 답변은 이 실습의 성공으로 보지 않습니다.
5. 답변과 Notion 원문의 날짜, 장소를 대조합니다. 찾지 못했다면 내용을 추측시키지 말고 링크, 로그인한 작업 공간과 접근 권한을 확인합니다. Connected 표시만 보고 읽기 성공으로 기록하지 않습니다.
6. Notion에서 직접 장소를 3번 회의실로 바꾸고 “같은 페이지를 새로 읽어 주세요”라고 요청합니다. 실제 읽기 호출과 새 값을 확인하고 날짜가 그대로인지도 비교합니다.

끝나면 /exit로 나온 뒤 이번에 추가한 연결만 제거하려면 연습 폴더의 터미널에서 claude mcp remove notion --scope local을 실행합니다. 기존에 쓰던 연결은 지우지 않습니다. 서비스 접근 권한도 없애려면 Notion의 연결 관리에서 Claude Code에 준 승인을 별도로 해제합니다. 설정, 연결과 실제 읽기 중 어디까지 확인했는지 남기면 첫 연습을 마친 것입니다.

📋 3줄 요약

1. MCP 등록 명령은 설정을 저장하며 인증과 연결 및 실제 도구 실행은 각각 확인해야 합니다.

2. local과 user는 홈 폴더의 ~/.claude.json에 저장되고 project는 프로젝트 루트 .mcp.json에 저장됩니다.

3. 첫 연결은 필요한 범위만 승인하고 가상 자료 하나를 읽어 원문과 비교한 뒤 사용을 넓힙니다.

📚 참고 자료

• MCP 문서: https://code.claude.com/docs/en/mcp
• 설정 문제 해결 문서: https://code.claude.com/docs/en/debug-your-config
• 권한 규칙 문서: https://code.claude.com/docs/en/permissions
• MCP 공식 소개: https://modelcontextprotocol.io/docs/getting-started/intro
• Google Ads MCP 서버 안내: https://developers.google.com/google-ads/api/docs/developer-toolkit/mcp-server
• CLI 참고 문서: https://code.claude.com/docs/en/cli-reference
• Notion의 Claude Code 연결 안내