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

Claude Code 공식 문서는 사용자가 Notion 같은 다른 도구의 자료를 복사해 대화에 붙여 넣고 있다면 MCP 서버를 연결하라고 안내합니다. 연결하면 Claude가 붙여 넣은 내용 대신 그 도구의 시스템을 직접 읽고 일합니다. 이 글은 claude-code-docs 서버로 /mcp가 하는 일을 찾아 달라는 요청을 서버 등록 전과 뒤에 Claude Code에 보낸 실제 화면을 비교하고, 등록 명령과 설정 파일, 승인 창, 권한, 오류를 실제 화면으로 설명합니다.

클로드 코드의 MCP 서버 연결은 claude mcp add 명령이나 .mcp.json 파일로 MCP 서버를 등록해 Claude가 그 서버의 도구를 쓰게 하는 설정입니다. 이 글은 2026년 10월 25일 기준 Claude Code 공식 문서(MCP, MCP quickstart, Debug your configuration)와 이날 macOS 터미널의 Claude Code v2.1.310에서 본 화면을 근거로 씁니다.

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

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

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

MCP 연결에는 세 가지 역할이 있습니다.

Claude가 서버의 도구를 쓰기로 하면 Claude Code가 그 요청을 해당 MCP 서버로 보내고, 서버가 실행한 결과를 다시 Claude에게 돌려줍니다. MCP는 이 주고받는 방식만 정하므로, Notion 같은 서비스에서 실제로 무엇을 읽고 바꿀 수 있는지는 각 서버가 내놓는 도구와 연결한 계정의 권한이 정합니다.

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

claude mcp add로 서버를 등록하는 명령

claude mcp add처럼 claude로 시작하는 명령은 운영체제의 터미널이나 PowerShell에 입력하고, /mcp는 실행 중인 Claude Code 입력창에 입력합니다. 공식 문서에 따르면 claude mcp add는 PowerShell과 명령 프롬프트(CMD)에서도 같게 동작합니다.

원격 서버는 인터넷 주소로 접속하는 서버이며, 이름과 주소를 적습니다. 공식 quickstart가 첫 서버로 권하는 Claude Code 문서 검색 서버는 로그인 없이 연결됩니다.

--transport http는 주소로 접속하는 원격 서버라는 표시이고, claude-code-docs는 사용자가 정하는 서버 이름입니다. 이 이름은 Claude의 도구 호출 줄과 claude mcp remove 같은 명령에서 서버를 가리킬 때 씁니다. 예전 원격 연결 방식인 SSE(Server-Sent Events)는 공식 문서에서 사용 중단 예정으로 표시되어 있고, v2.1.265 이상에서는 SSE만 받는 서버도 --transport http로 등록하면 Claude Code가 SSE로 바꿔 연결합니다.

로컬 서버는 내 컴퓨터에서 프로그램을 실행해 연결하는 서버이며, stdio(표준 입출력) 방식을 씁니다. 형식은 다음과 같고, 서버이름, 실행프로그램, 서버파일경로는 설명용 자리표시자입니다.

-- 앞은 Claude Code의 옵션이고 뒤는 서버를 실행하는 명령입니다. --를 빼면 Claude Code가 서버 프로그램의 옵션까지 자기 옵션으로 읽습니다. 다른 글의 npx -y ...를 복사하면 패키지를 내려받아 실행하므로, 제공자와 패키지 이름을 먼저 확인합니다.

다른 프로그램용 안내에 mcpServers로 시작하는 JSON만 있다면 claude mcp add-json을 씁니다. 이때는 mcpServers 묶음 전체가 아니라 그 안의 서버 객체 하나를 넘깁니다.

관리 명령은 claude mcp list(목록과 연결 상태), claude mcp get 이름(범위, 상태, 오류 상세), claude mcp remove 이름(등록 지우기)이고, 세션 안에서는 /mcp를 씁니다. 원격 서버를 지우면 Claude Code가 그 서버용으로 저장해 둔 로그인 정보(OAuth 토큰)도 함께 지웁니다.

범위와 저장 위치: .mcp.json과 ~/.claude.json

--scope(짧게 -s)로 서버 설정을 어느 범위에 저장할지 정합니다. 적지 않으면 local 범위입니다. local 범위는 설정을 어느 프로젝트에 적용할지만 정하며, 서버가 읽는 자료를 현재 폴더로 제한하지는 않습니다.

Windows에서 ~/.claude.json은 %USERPROFILE%\.claude.json(보통 C:\Users\이름\.claude.json)입니다. 범위는 등록할 때 정해지므로, 바꾸려면 claude mcp remove 이름 --scope local처럼 지운 뒤 새 범위로 다시 등록합니다.

설정 파일에서 자주 틀리는 점은 세 가지입니다.

• MCP의 local은 홈 폴더에 저장됩니다: 이름이 같아도 권한 규칙을 적는 .claude/settings.local.json과 다른 파일입니다.
• settings.json의 mcpServers는 읽지 않습니다: settings.json에 mcpServers를 적거나 .mcp.json을 .claude/ 폴더 안에 두면 서버가 불러와지지 않습니다. ~/.claude/mcp.json, ~/.claude/.mcp.json도 Claude Code가 읽지 않는 경로입니다.
• 같은 이름이 여러 범위에 있으면: local, project, user 순서로 앞선 범위의 설정 하나를 통째로 씁니다. 플러그인과 claude.ai 커넥터는 주소로 중복을 판단하며 순서가 그 뒤입니다. 조직이 관리 설정으로 배포한 서버는 이들보다 앞섭니다.

.mcp.json 직접 쓰기와 환경 변수

.mcp.json은 손으로 써도 됩니다. 원격 서버는 type과 url을, 로컬 서버는 command와 args를 적습니다.

Claude Code는 세션을 시작할 때 .mcp.json을 읽으므로, 파일을 고친 뒤에는 세션을 끝내고 다시 엽니다. 주소만 있고 "type"이 빠진 항목은 로컬 서버로 해석되어 건너뜁니다. v2.1.310에서 type을 뺀 .mcp.json으로 claude mcp list를 실행하면 아래 경고가 나왔습니다.

팀과 공유하는 .mcp.json에는 토큰(서비스가 발급한 접속 비밀번호)을 직접 적지 않고 환경 변수로 넘깁니다. .mcp.json은 ${VAR}와 기본값을 주는 ${VAR:-기본값} 문법을 command, args, env, url, headers에서 받습니다. 아래 api.example.com은 설명용 주소입니다.

변수가 설정되지 않았고 기본값도 없으면 ${API_KEY}라는 글자가 그대로 쓰이고 claude mcp list에 경고가 뜹니다. ANTHROPIC_API_KEY 같은 Claude Code와 클라우드 인증 변수는 원격 서버의 주소와 헤더에서 빈 값으로 처리되므로, 연결하려는 서비스가 발급한 자격 증명을 다른 이름의 변수로 넘깁니다. 토큰을 복사할 때 딸려 온 앞뒤 공백은 Claude Code가 지우지 않고 경고만 띄웁니다.

프로젝트 서버 승인과 폴더 신뢰

.mcp.json의 서버는 처음 쓰기 전에 승인을 묻습니다. 승인하기 전 claude mcp list는 그 서버를 ⏸ Pending approval (run `claude` to approve)로 보여 주고, claude를 실행하면 폴더 신뢰 창 다음에 승인 창이 뜹니다.

거절하거나 창을 닫은 선택을 처음으로 되돌리려면 claude mcp reset-project-choices를 실행합니다. 남의 저장소가 .claude/settings.json에 enableAllProjectMcpServers를 넣어 두어도, 신뢰한다고 고르지 않은 폴더에서는 그 설정이 무시되고 서버는 승인 대기로 남습니다. 반대로 claude -p(질문 하나를 실행하고 바로 끝내는 비대화형 실행)는 승인 창을 띄울 수 없어 .mcp.json의 서버를 묻지 않고 불러오므로, 받아 온 저장소에서 비대화형으로 실행하기 전에는 .mcp.json을 먼저 읽습니다.

로그인이 필요한 서버 인증: Notion 연결

Notion, Sentry 같은 서비스의 원격 MCP 서버는 OAuth로 로그인합니다. OAuth는 서비스의 로그인 화면에서 연결할 앱에 접근을 허락하는 방식입니다. Notion 공식 안내에 따르면 Claude Code에서는 터미널에 아래 명령을 입력한 뒤 Claude Code 세션의 /mcp에서 로그인합니다.

등록 직후 claude mcp list에는 ! Needs authentication이 나옵니다. 세션에서 /mcp를 열고 notion 서버를 골라 Enter를 누른 뒤 Authenticate를 고르면 브라우저에 Notion 로그인 화면이 열립니다. 연결되는 계정과 작업 공간, 접근 범위를 읽고 맞을 때 허용합니다.

터미널에서 바로 로그인하려면 claude mcp login notion을, 로그인 정보를 지우려면 claude mcp logout notion을 씁니다. SSH로 접속한 원격 컴퓨터처럼 브라우저가 없는 곳에서는 claude mcp login이 로그인 주소만 출력하고, --no-browser로 그 동작을 강제할 수 있습니다. claude -p 같은 비대화형 실행에는 /mcp 화면이 없어 로그인 창을 띄울 수 없으므로, 대화형 세션에서 먼저 로그인해 둡니다. 토큰을 헤더로 받는 서버는 --header "Authorization: Bearer 토큰"으로 등록합니다.

MCP 도구 권한 규칙: mcp__서버__도구

MCP 도구에도 권한 규칙을 걸 수 있습니다. 규칙 이름은 /mcp에서 서버와 도구를 고르면 나오는 Full name과 같고, 형식은 mcp__서버이름__도구이름입니다.

서버 이름의 점이나 공백은 _로 바뀝니다. allow 규칙의 별표는 mcp__서버__ 뒤에만 쓸 수 있고, 모든 MCP 도구를 여는 "mcp__*" allow 규칙은 무시됩니다. 처음에는 실제 도구 이름과 입력 내용을 보고 읽기 도구만 allow에 두고, 쓰기와 삭제 도구는 ask에 둡니다. 읽기 도구도 외부 서비스로 검색어나 자료를 보내므로 서버 전체를 한 번에 허용하지 않습니다. 공식 문서는 외부 내용을 가져오는 서버가 프롬프트 인젝션 위험을 키울 수 있으니 믿을 수 있는 서버만 연결하라고 경고합니다.

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

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

같은 MCP 서버라도 할 수 있는 일은 서버마다 다릅니다. 예를 들어 v2.1.310의 /mcp에서 claude-code-docs 서버의 도구 목록을 열면 Search documentation과 Query documentation filesystem에는 read-only(읽기만 함), Submit documentation feedback에는 open-world(서버 밖으로 내용을 보냄) 표시가 붙어 있습니다. 연결하기 전에 서버가 내놓는 도구 목록에서 읽기 도구와 바깥으로 보내거나 바꾸는 도구를 나눠 봅니다.

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

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

직접 해 보기: 공식 문서 검색 서버 연결하기

Claude Code 설치와 로그인이 끝났다면 진행합니다. 아직이라면 설치 기초를 먼저 따라 합니다. 이 실습의 서버는 로그인이 필요 없는 Claude Code 문서 검색 서버이고, 요청을 보내면 계정의 사용량이 듭니다.

1. Finder나 파일 탐색기에서 빈 폴더 mcp-연습을 만듭니다.
2. 터미널이나 PowerShell에서 cd 뒤에 mcp-연습 폴더를 끌어다 놓고 Enter를 누른 뒤, claude mcp add --transport http claude-code-docs https://code.claude.com/docs/mcp를 입력합니다. Added HTTP MCP server claude-code-docs ... to local config 줄이 나오면 설정이 저장된 것입니다.
3. 같은 터미널에 claude mcp list를 입력하고 claude-code-docs 줄 끝이 ✔ Connected인지 봅니다.
4. claude --permission-mode default로 Claude Code를 시작합니다. 이 옵션은 파일 편집이나 도구 사용처럼 동작마다 허락을 묻는 Manual 모드로 시작하게 합니다. 폴더 신뢰 창이 나오면 Yes, I trust this folder를 고릅니다.
5. 입력창에 "claude-code-docs 서버로 /mcp 명령이 하는 일을 찾아 줘"를 보냅니다. 요청에 서버 이름을 적으면 Claude가 웹 검색 같은 다른 도구 대신 claude-code-docs 서버를 씁니다. 도구 승인 창이 뜰 때마다 1번 Yes를 고릅니다.
6. 답 위에 Called claude-code-docs 줄이 있는지 봅니다. 이 줄이 있으면 Claude가 학습한 지식이 아니라 MCP 서버의 검색 결과로 답했다는 뜻입니다.
7. /mcp를 입력하고 claude-code-docs를 골라 View tools에서 도구 세 개(Search documentation, Query documentation filesystem, Submit documentation feedback)를 봅니다. Esc로 닫습니다.

연습이 끝나면 /exit로 세션을 끝내고, 터미널에서 claude mcp remove claude-code-docs를 입력합니다. Removed MCP server "claude-code-docs" from local config 줄이 나오면 등록이 지워진 것입니다. 팀 공유를 연습하려면 다른 빈 폴더에서 --scope project로 등록한 뒤 .mcp.json을 열어 보고, claude를 실행해 승인 창을 확인합니다.

막혔을 때

연결이 안 되면 먼저 claude mcp list와 claude mcp get 이름을 실행합니다. v2.1.219 이상에서는 상태 줄 끝과 Issue: 줄에 HTTP 상태 번호와 서버가 보낸 오류 문구가 나옵니다.

공식 문서에 따르면 MCP 도구 결과가 10,000토큰을 넘으면 경고가 뜨고, 기본 최대치는 25,000토큰입니다. 최대치를 넘는 결과와, 도구가 따로 한도를 정하지 않았을 때 50,000자를 넘는 텍스트 결과는 파일로 저장되고, Claude가 필요할 때 그 파일을 읽습니다. 먼저 검색 범위나 반환 건수를 줄이고, 필요할 때만 MAX_MCP_OUTPUT_TOKENS 환경 변수로 최대치를 바꿉니다. 오류 로그를 다른 사람에게 보낼 때는 토큰과 개인 자료를 지웁니다. 다른 설치 문제와 함께 보는 순서는 클로드 코드 자주 나는 문제와 해결에 있습니다.

자주 묻는 질문

클로드 코드에서 MCP 서버를 삭제하려면 어떻게 하나요?

터미널에서 claude mcp remove 서버이름을 실행하면 등록이 지워지고 Removed MCP server "서버이름" from local config처럼 지운 범위가 나옵니다. 같은 이름이 여러 범위에 있으면 claude mcp remove 서버이름 --scope project처럼 범위를 적습니다. 공식 문서에 따르면 원격 서버를 지우면 Claude Code가 그 서버용으로 저장한 로그인 정보도 함께 지워집니다.

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

세션에서 /mcp를 열고 서버를 골라 Disable을 고르면 설정은 남고 연결만 끊깁니다. 이 선택은 프로젝트마다 ~/.claude.json에 기록되고, claude mcp list에는 ⊘ Disabled for this project (re-enable via /mcp)로 나옵니다. 다시 켤 때도 /mcp에서 켭니다.

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

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

Claude 데스크톱 앱에 등록한 서버를 가져올 수 있나요?

claude mcp add-from-claude-desktop으로 가져올 수 있습니다. 공식 문서 기준으로 macOS와 WSL(Windows에서 리눅스를 실행하는 기능)에서만 동작하고, 실행하면 가져올 서버를 고르는 창이 뜹니다.

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

도구 검색 기능이 기본으로 켜져 있어서 세션 시작 때는 도구 이름과 서버 안내만 싣고, 도구의 자세한 설명은 쓸 때 불러옵니다. 그래도 연결한 서버마다 도구 이름과 서버 안내가 모든 세션의 컨텍스트를 차지하므로, 쓰지 않는 서버는 지우거나 /mcp에서 꺼 둡니다.

참고 자료

• Claude Code 공식 문서: Connect Claude Code to tools via MCP(등록 명령, 범위, 인증, 출력 한도)
• Claude Code 공식 문서: Connect to MCP servers(첫 서버 연결, 상태 표, 문제 해결)
• Claude Code 공식 문서: Debug your configuration(서버가 안 보일 때)
• Claude Code 공식 문서: Configure permissions(mcp__ 규칙 이름)
• MCP 공식 소개(USB-C 비유, 지원 앱)
• Notion 공식 안내: Get started with MCP(Claude Code 연결 명령)