이 페이지의 목차
확인 2026-09-16근거 자료 20건갱신 2026-10-26언급 35곳
이 페이지의 목차
확인 날짜 안내

확인 날짜가 섞인 페이지다. 기본은 원본 날짜 미상인 공식 문서의 수집일(2026-10-18) 기준이고, Antigravity CLI 절은 그 도구의 이전 문서(원본 날짜 미상, 수집 2026-10-18), Cowork·채팅 통합 발표 글 문단은 발행일(2026-09-16) 기준이다. 발표 글은 "커넥터"라고만 하고 MCP라는 말은 쓰지 않는다. 컨텍스트 엔지니어링 글(2025-09-29) 문단은 원칙(비대한 도구 세트를 피하라)이고 에이전트 설계 글(2024년 글) 문단은 설계 원칙이라 날짜 계산에서 뺀다. 페이지 확인 날짜는 남은 가장 오래된 날짜인 2026-09-16이다. 서버 추가·인증·스코프 설정 세부는 공식 MCP 문서를 수집한 뒤 채운다.

정의#

Claude를 외부 서비스와 도구에 연결하는 프로토콜이다. Claude Code에서는 MCP 서버(용어 사전)를 연결해 도구와 데이터 접근을 얻는다. 연결과 인증은 서버가 맡는다. Claude Code 확장 기능 개요

원본 예: DB 조회, Slack에 글 올리기, 브라우저 제어. Claude Code 확장 기능 개요

Claude Cowork에서도 앱 연결은 MCP 커넥터로 한다. 첫 세팅에서 자주 쓰는 커넥터(Slack, Gmail, Drive, Asana, GitHub 등)를 인증하고, 작업 내용상 커넥터가 필요해 보이면 Cowork가 먼저 제안한다. Claude Cowork 시작하기 → Claude Cowork 시작 세팅

2026-09-16 발표로 Cowork와 채팅이 하나의 Claude로 합쳐지면서, 이미 가진 커넥터를 맥락·스킬과 함께 어느 대화에서나 쓸 수 있고 기존 Cowork 사용자의 커넥터는 그대로 남는다고 발표 글은 말한다(2026-09-16 기준). 발표 글 사례의 한 사용자는 법률 판례 데이터베이스를 불러오게 할 수 있었고, 그러면 판례를 가져와 읽고 추가로 필요할 판례를 내려받아 폴더에 저장할 것이라고 말한다(가능 표현 "could"·"would"이며 실제 결과 보고는 아니다). 그 데이터베이스가 어떤 방식으로 연결됐는지는 원본에 없다. Claude Cowork와 채팅 통합 공지 같은 날 수정된 Help Center 문서는 연결한 앱(Google Drive, Gmail, Microsoft 365, Slack 등)이 작업 중에 쓰여 Claude가 필요한 것을 가져온다고 말하고, 연결 자리를 Customize > Connectors로 적는다(2026-09-16 기준). 이 문서는 커넥터를 MCP라고 부르지 않는다. Claude Cowork와 채팅 통합 도움말

언제 쓰는가#

(2024년 글) Anthropic의 에이전트 설계 글은 에이전트형 시스템의 기본 블록을 검색·도구·메모리로 증강한 LLM으로 보고, 이 증강을 구현하는 방법 중 하나로 당시 막 공개한 MCP를 든다. 간단한 클라이언트 구현으로 늘어나는 서드파티 도구 생태계와 연결할 수 있다는 설명이다. 효과적인 에이전트 만들기 → 워크플로와 에이전트

MCP와 스킬은 함께 쓴다#

MCP는 외부 시스템용 전용 도구를 주고, 스킬은 그 도구를 잘 쓰는 법과 /<name> 워크플로를 준다. 원본 예: 팀의 DB 스키마와 쿼리 패턴을 담은 스킬, 팀 메시지 형식 규칙을 담은 /post-to-slack 워크플로. Claude Code 확장 기능 개요

다른 조합: 훅이 MCP를 통해 외부 동작을 일으킨다(중요 파일 수정 시 Slack 알림). Claude Code 확장 기능 개요

권한: 승인을 강제하는 MCP 도구 (2026-10-18 기준)#

  • requiresUserInteraction(_meta["anthropic/requiresUserInteraction"])으로 표시된 MCP 도구와 조직이 ask로 정한 커넥터 도구(그 설정이 Claude Code에 닿는 세션에서)는 어떤 권한 모드에서도 자동 승인되지 않는다. allow 규칙이 있어도 사용자에게 직접 묻고 자동 모드 분류기로 가지 않는다. 묻지 않는 dontAsk 모드에서는 거부된다. Claude Code 권한 모드 → 권한 모드

  • 관리자 관점의 정리: Claude Code 관리자 권한 통제

  • (2026-10-21 기준) MCP 도구의 권한 규칙 이름: 서버 전체는 mcp__<server>__*(또는 mcp__puppeteer처럼 서버 이름만), 도구 하나는 mcp__<server>__<tool>. 서버 이름의 .·공백은 _가 되고(my.server → mcp__my_server__*), 플러그인 서버는 mcp__plugin_my-plugin_database-tools__*처럼 범위가 붙으며, 이름에 __가 있거나 _로 끝나면 와일드카드 형태(mcp__reports__v2__*)로 쓴다. allow 규칙의 도구 이름 glob은 mcp__<server>__ 뒤에서만 받고, deny "mcp__*"는 모든 MCP 도구를 컨텍스트에서 뺀다. 설정 파일의 괄호 붙은 mcp__ 규칙(파라미터 규칙)은 건너뛰므로 MCP 도구 파라미터 deny는 --disallowedTools로 넘긴다. Claude Code가 직접 가져오는 claude.ai 커넥터 도구는 mcp__claude_ai_<server>__<tool>로 보인다. Claude Code 권한 설정 → Claude Code 권한 규칙 문법

  • (2026-10-21 기준) 작업 공간 신뢰: 상위 폴더만 신뢰한 대화형 세션은 .mcp.json 서버를 연결하기 전에 묻고(저장소 자신의 승인은 치지 않음), claude -p·SDK는 승인 여부와 상관없이 묻지 않고 연결한다. disabledMcpjsonServers로 이름을 넣으면 모든 세션 종류에서 거부한다. Claude Code 권한 설정 → 작업 공간 신뢰

  • 훅의 "allow"로도 이 두 종류의 확인 창은 없앨 수 없다(공식 훅 가이드, 2026-10-18 기준). Claude Code 훅 가이드

  • (2026-10-21 기준) 로컬 MCP 서버는 Bash 샌드박스 밖에서 사용자의 전체 권한으로 돈다. 샌드박스의 파일·네트워크 제한은 MCP 서버에 적용되지 않고, MCP 도구는 권한 규칙을 따른다. 샌드박스는 .mcp.json을 보호 경로로 두어 샌드박스 명령이 서버를 더하지 못하게 한다. 이 보호는 작업 디렉터리와 그 위 디렉터리 기준이고, 파일 격리를 끄는 filesystem.disabled를 켜면 꺼지며, excludedCommands나 샌드박스 밖 재시도처럼 샌드박스 밖에서 도는 명령에는 적용되지 않는다. Claude Code 샌드박스 → 샌드박스

훅에서 MCP 다루기 (2026-10-18 기준)#

  • 훅 matcher에서 MCP 도구는 mcp__<server>__<tool> 이름으로 맞춘다(예: mcp__github__search_repositories). 플러그인에 묶인 서버는 mcp__plugin_my-plugin_db__query처럼 범위가 붙은 서버 이름을 쓴다. 한 서버의 모든 도구는 mcp__github__.*, 여러 서버에 걸친 쓰기 도구는 mcp__.*__write.* 같은 정규식으로 맞춘다. Claude Code 훅 가이드
  • 훅 종류 중 mcp_tool은 설정된 MCP 서버의 도구를 호출한다. Elicitation 이벤트는 MCP 서버가 도구 호출 중 사용자 입력을 요청할 때, ElicitationResult는 사용자가 답한 뒤 응답을 서버로 보내기 전에 실행되고, 둘 다 matcher는 MCP 서버 이름이다. Notification에는 MCP elicitation 관련 알림 종류가 있다. Claude Code 훅 가이드 → Claude Code 훅 설정 레시피
  • (2026-10-18 기준) 공식 훅 레퍼런스가 더하는 것: Claude Code 훅 레퍼런스
    • 서버 전체를 맞출 때 .*는 필수다. mcp__memory처럼 쓰면 정확 문자열로 비교돼 아무 도구에도 맞지 않는다. 플러그인 서버의 도구에는 서버 키만으로 쓴 matcher가 돌지 않는다.
    • mcp_tool 훅 필드는 server(플러그인 서버는 plugin:<plugin-name>:<server-name>), tool, input("${tool_input.file_path}" 같은 치환). 도구의 텍스트 결과를 command 훅 stdout처럼 읽고, isError: true면 막지 않는 오류다. 훅은 OAuth를 시작하지 않으니 /mcp에서 먼저 인증한다. 시작 시 SessionStart와 Setup에서는 서버를 쓸 수 없어 mcp_tool 훅을 건너뛴다.
    • PreToolUse 등 도구 이벤트 입력의 mcp_server 객체(name, 정의 출처 source, v2.1.274 이상). 원본은 신뢰 판단을 서버 이름이나 접두어가 아니라 source로 하라고 한다.
    • Elicitation 훅은 hookSpecificOutput.action(accept+content, decline, cancel)으로 대화상자 없이 서버에 답한다. 원본 예: issue-tracker 서버가 묻는 프로젝트 키를 DOCS로 자동 입력. ElicitationResult 훅은 사용자의 답을 서버로 보내기 전에 바꾸거나 막는데, 사용자가 거절·취소했을 때도 돌아 훅의 action이 사용자의 것을 대체하므로 입력 action이 accept인지 먼저 확인하라고 원본이 경고한다. → 훅 이벤트 레퍼런스

조직이 MCP 서버를 통제하는 법 (2026-10-18 기준)#

공식 managed settings 배포 문서가 드는 키다. 키 하나의 전체 동작은 원본이 링크한 Managed MCP configuration 문서에 있다. Claude Code managed settings 배포 → managed settings

  • 서버 제공: 관리 파일 디렉터리의 managed-mcp.json이나 managedMcpServers 키(v2.1.259 이상)로 모든 사용자에게 원격 MCP 서버를 사용자 서버와 함께 준다. 원본은 이것이 무언가를 잠그는 것이 아니라 서버를 제공하는 것이라고 말한다.
  • 허용 목록 잠금: allowManagedMcpServersOnly: true면 managed settings의 allowedMcpServers만 존중한다. 차단 목록 deniedMcpServers는 모든 출처에서 합쳐진다. 어느 관리자 출처든 true를 두면 잠금이 켜지고(v2.1.273 이상), 잠금이 켜졌는데 어떤 관리자 출처도 목록을 두지 않으면 차단 목록을 통과한 모든 서버가 로드된다(호스트가 넘긴 목록이 없을 때).
  • claude.ai 커넥터: managed-mcp.json을 배포하면 Claude Code가 스스로 가져오는 claude.ai 커넥터가 억제되고, allowAllClaudeAiMcps로 함께 로드하게 할 수 있다. disableClaudeAiConnectors는 어느 관리자 출처에서든 true면 적용된다(v2.1.273 이상).
  • 잘못 쓴 allowedMcpServers는 빈 허용 목록으로 강제돼 사용자가 추가한 서버가 들어오지 못한다. 조직이 managedMcpServers로 준 서버는 계속 로드된다. 잘못된 항목 하나만이면 그 항목만 빼고 나머지를 강제한다.
  • 사이드로드 차단: disableSideloadFlags는 시작 때 --mcp-config 등의 플래그를 거부한다(v2.1.193 이상).
  • strictPluginOnlyCustomization은 user·project 출처의 MCP 서버를 막을 수 있다(true는 스킬·에이전트·훅·MCP 넷 다, 배열은 지정한 것만).
  • (2026-10-21 기준) settings reference가 키 항목에 적는 조건: allowedMcpServers 항목은 serverName·serverCommand·serverUrl 중 하나만 갖고, 목록에 serverCommand가 하나라도 있으면 stdio 서버는 serverCommand로, serverUrl이 하나라도 있으면 원격 서버는 serverUrl로 맞아야 한다(serverName 일치만으로는 안 됨). 허용 목록 예외: 내장 서버(Claude in Chrome, IDE의 ide 서버), Claude Tag 세션의 Slack 도구(v2.1.268 이상), 조직이 준 서버(managedMcpServers 전부와 ${VAR}를 쓰지 않는 managed-mcp.json 항목, v2.1.259 전에는 managed-mcp.json 서버도 목록에 맞아야 했다). 이 예외들에도 deniedMcpServers는 적용되고, 프로세스 안 type: "sdk" 서버만 두 목록 모두 예외다. disableClaudeAiConnectors는 어느 파일의 true든 적용돼 저장소 파일이 끌 수는 있어도 user·managed의 true를 풀지 못한다. 프로젝트 .mcp.json 서버 일괄 승인(enableAllProjectMcpServers)은 신뢰하지 않은 폴더에서 공유 project 파일 값을 무시한다. Claude Code 설정 키 전체 레퍼런스 → Claude Code 설정 키 레퍼런스

컨텍스트 비용#

  • 세션 시작 때 연결된 서버의 도구 이름과 서버 지시만 로드된다. 전체 JSON 스키마는 Claude가 특정 도구를 필요로 할 때까지 미뤄진다. Claude Code 확장 기능 개요 공식 작동 방식 문서(2026-10-18 기준)도 MCP 도구 정의가 기본으로 미뤄져 tool search로 필요할 때 로드되고, 그 전까지는 도구 이름과 서버 지시만 컨텍스트를 쓴다고 적는다. Claude Code 작동 방식
  • Tool search가 기본으로 켜져 있어, 쓰지 않는 MCP 도구는 컨텍스트를 아주 조금만 쓴다(2026-10-18 확인). Claude Code 확장 기능 개요
  • 이 동작은 환경 변수로 바꾼다(2026-10-18 기준). ENABLE_TOOL_SEARCH=auto면 스키마가 컨텍스트 창의 10% 안에 들어갈 때 미리 싣고, ENABLE_TOOL_SEARCH=false면 모든 스키마를 싣는다. 기본은 이름만 싣고 작업에 필요한 스키마를 tool search로 불러오는 것이다. Claude Code 컨텍스트 창
  • 서브에이전트도 같은 MCP 서버를 쓸 수 있고, 그 도구 목록은 서브에이전트 자기 컨텍스트에 든다(2026-10-18 기준). Claude Code 컨텍스트 창
  • (2026-10-18 기준) 서브에이전트 frontmatter의 mcpServers로 메인 대화에 없는 서버를 그 서브에이전트에만 줄 수 있다. 인라인 정의는 .mcp.json과 같은 스키마(stdio·http·sse·ws)로 서브에이전트가 시작할 때 연결되고 끝나면 끊기며, 이름 참조는 부모 세션 연결을 공유한다. 원본은 서버 도구 설명이 메인 컨텍스트를 쓰지 않게 하려면 .mcp.json 대신 여기 인라인으로 두라고 한다. 조건: 프로젝트 .claude/agents/의 인라인 서버는 그 폴더를 신뢰한 뒤에만 로드되고(v2.1.238 이상), --strict-mcp-config·--bare·managed MCP 정책도 적용된다(--strict-mcp-config는 --agents·SDK로 넘긴 인라인 서버는 거르지 않음). 플러그인 서브에이전트는 이 필드를 무시한다. Claude Code 서브에이전트 → 서브에이전트 정의 파일 레퍼런스
  • 확인 명령: /mcp는 서버별 연결 상태, /context all은 로드된 MCP 도구별 토큰 수를 보여 준다. 원격 서버가 끊기면 자동으로 다시 연결하며, 당장 쓰지 않는 서버는 연결을 끊을 수 있다. Claude Code 확장 기능 개요

→ 컨텍스트 비용

(2025-09-29 기준) Anthropic 엔지니어링 글은 MCP를 시스템 지시, 도구, 외부 데이터, 메시지 기록과 함께 관리해야 할 컨텍스트 상태의 하나로 꼽는다. 같은 글은 가장 흔한 실패로 기능을 너무 많이 덮거나 어떤 도구를 쓸지 모호하게 만드는 비대한 도구 세트를 들고, 겹치지 않는 최소 도구 세트를 권한다. 효과적인 컨텍스트 엔지니어링 → 컨텍스트 엔지니어링, 시스템 프롬프트·도구·예시 설계

레벨이 겹칠 때#

같은 이름의 MCP 서버는 우선순위로 덮어쓴다: local > project > user. Claude Code 확장 기능 개요

다른 도구의 MCP 설정 위치: Antigravity CLI (2026-10-18 기준)#

Antigravity CLI 공식 이전 문서는 MCP 서버를 주 설정 파일 안에 넣지 않고 전용 경량 JSON 프로필(mcp_config.json)로 분리했다고 말한다. Gemini CLI에서 Antigravity CLI로 이전

위치
예전 Gemini CLI~/.gemini/settings.json 안에 인라인
Antigravity CLI 전역 서버~/.gemini/config/mcp_config.json
Antigravity CLI 워크스페이스 서버.agents/mcp_config.json