MCP 서버를 붙이면 사용량(토큰)을 더 먹나요?

네. 연결된 서버의 도구 정의가 컨텍스트에 올라가기 때문에 붙이는 만큼 소모가 늘어납니다. Claude Code의 /usage 명령으로 MCP 서버별 소모량을 퍼센트로 확인할 수 있으니, 안 쓰는 서버는 /mcp 패널에서 토글로 껐다가 필요할 때 켜는 게 좋습니다.

Claude Desktop에 이미 붙인 서버를 Claude Code에서 다시 설정해야 하나요?

아니요. macOS와 WSL에서는 claude mcp add-from-claude-desktop 명령으로 데스크톱 설정을 가져올 수 있습니다.

MCP 서버가 갑자기 끊기면 자동으로 다시 붙나요?

HTTP·SSE 서버는 자동 재연결을 시도합니다. 1초에서 시작해 두 배씩 늘리며 최대 5회까지 재시도하고, 그 후에는 실패로 표시되어 /mcp에서 수동 재시도해야 합니다. stdio 서버는 로컬 프로세스라서 자동 재연결 대상이 아닙니다.

회사 레포에 .mcp.json을 커밋했는데 팀원 쪽에서 연결이 안 됩니다.

프로젝트 스코프 서버는 보안상 승인 절차를 거칩니다. 클론한 레포는 자기 자신의 서버를 승인할 수 없어서, 팀원이 해당 폴더에서 claude를 실행해 워크스페이스 신뢰 대화상자를 수락하기 전까지 '승인 대기(Pending approval)' 상태로 남습니다.

클로드 MCP 연결하기: Claude Code·Desktop 실제 설정법과 함정 (2026)

MCP 관련 글은 “이런 게 나왔다”는 소개는 많은데, 막상 붙이려고 하면 어디에 붙이는 건지부터 헷갈린다. Claude Code에 붙이는 것, 데스크톱 앱에 붙이는 것, claude.ai 웹에서 켜는 것이 전부 “MCP”라는 이름으로 불리지만 설정 방법과 가능한 일이 다르다. 공식 문서를 근거로 세 경로를 갈라서 정리했다.

아래 명령어·정책은 code.claude.com/docs/en/mcp, modelcontextprotocol.io, Anthropic 공식 지원 문서를 2026-07-28에 확인한 값이다. MCP는 스펙과 CLI가 빠르게 바뀌는 영역이라, 설정 직전에 공식 문서를 다시 확인하는 편이 안전하다.

MCP가 뭔지 30초

Model Context Protocol은 AI 애플리케이션을 외부 시스템에 연결하는 오픈소스 표준이다. 공식 문서는 “AI 애플리케이션의 USB-C 포트”라는 비유를 쓴다 — 도구마다 전용 연동을 만들지 말고, 한 번 만들어 여러 클라이언트에 붙이자는 발상이다.

중요한 오해 하나: MCP는 Anthropic 전용 규격이 아니다. ChatGPT, VS Code, Cursor도 MCP를 지원한다. 현재 스펙 버전은 2025-11-25이고 JSON-RPC 2.0 메시지를 쓴다.

서버가 클라이언트에 제공하는 것은 세 종류다:

종류	내용
Tools	모델이 실행하는 함수 (검색, 쿼리, 파일 쓰기 등)
Resources	모델·사용자가 읽는 컨텍스트와 데이터
Prompts	사용자를 위한 템플릿 메시지·워크플로

“MCP = 도구 붙이기”로만 알려져 있지만 실제로는 Resources와 Prompts도 스펙의 일부다.

어디에 붙이나 — 경로 3개

이 표가 이 글의 핵심이다. 목적에 따라 경로가 정해진다.

경로	붙일 수 있는 서버	쓸 수 있는 곳	설정 방법
Claude Code CLI	로컬 + 원격 전부	Claude Code	`claude mcp add`
데스크톱 확장	로컬(내 컴퓨터)	Claude Desktop, Claude Code	설정 > Extensions
웹 커넥터	원격(클라우드 SaaS)	웹·모바일·Cowork·Desktop·Claude Code	커넥터 디렉터리에서 연결

판단 기준은 단순하다. 붙이려는 대상이 로그인해서 쓰는 클라우드 서비스(Slack, Notion, Linear, GitHub)면 웹 커넥터가 맞다. 한 번 연결하면 모든 기기에서 쓸 수 있다. 반대로 내 컴퓨터에서 도는 것(로컬 파일, localhost 데이터베이스, 데스크톱 앱)이면 로컬 서버여야 하고, 이건 Claude Desktop과 Claude Code에서만 된다.

참고로 원격 MCP 커넥터는 무료 플랜에도 포함돼 있다. 유료 결제 없이도 클라우드 서비스는 붙일 수 있다는 뜻이다 — 무료에 뭐가 들어있고 뭐가 없는지는 무료로 어디까지 되나에서 갈라놨다. 다만 Claude Code 자체는 Pro부터라서, 아래 CLI 방식은 유료 플랜이 전제다.

Claude Code에 붙이기

transport 3종

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

HTTP가 원격 서버의 권장 방식이다. 인증 헤더가 필요하면:

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

로컬 프로세스로 도는 서버는 stdio를 쓴다. 여기서 -- 위치가 중요하다:

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

-- 앞은 Claude의 옵션(--transport, --env, --scope), 뒤는 서버를 실행할 명령어다. 뒤쪽은 그대로 전달된다.

SSE는 쓰지 말자. 공식 문서가 “The SSE (Server-Sent Events) transport is deprecated”라고 경고하고 HTTP를 쓰라고 안내한다. 기존에 SSE로 붙여둔 게 있으면 HTTP 지원 여부를 확인해 옮기는 게 맞다.

.mcp.json에 직접 쓸 때 알아둘 점: type 필드에 streamable-http를 써도 http로 인식된다. MCP 스펙이 이 transport를 streamable-http라고 부르기 때문에, 서버 문서에서 복사한 설정이 그대로 동작하도록 만든 배려다. 반대로 url은 있는데 type이 없으면 설정 오류다 — Claude Code는 type 없는 항목을 stdio로 읽기 때문에 해당 서버를 건너뛴다.

스코프 — 여기서 제일 많이 막힌다

붙였는데 다른 프로젝트에서 안 보인다는 문제는 대부분 스코프 때문이다. 기본값이 local이라 추가한 프로젝트에서만 로드된다.

스코프	로드되는 범위	팀 공유	저장 위치
`local` (기본)	현재 프로젝트만	아니오	`~/.claude.json`
`project`	현재 프로젝트만	예 (버전 관리)	프로젝트 루트의 `.mcp.json`
`user`	내 모든 프로젝트	아니오	`~/.claude.json`

# 모든 프로젝트에서 쓰고 싶다
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

# 팀과 공유하고 싶다 (.mcp.json 생성 → 커밋)
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

`.mcp.json` 실물

--scope project로 추가하면 프로젝트 루트에 이 파일이 생긴다. 직접 써도 되고, 팀 레포에 커밋하는 대상이 이것이다.

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "sentry": {
      "type": "http",
      "url": "https://mcp.sentry.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${SENTRY_TOKEN}"
      }
    },
    "local-db": {
      "command": "npx",
      "args": ["-y", "@my/db-mcp-server", "--root", "${CLAUDE_PROJECT_DIR:-.}"],
      "env": {
        "DB_URL": "${DB_URL}"
      }
    }
  }
}

여기서 놓치기 쉬운 게 세 개 있다.

① ${VAR} 환경변수 확장이 된다. 그래서 토큰을 파일에 박지 않고도 팀과 공유할 수 있다. .mcp.json은 버전 관리에 올라가는 파일이니 시크릿을 직접 쓰면 안 된다 — 위 예시처럼 ${SENTRY_TOKEN} 형태로 두고 실제 값은 각자 환경에 둔다.

② ${CLAUDE_PROJECT_DIR}에는 기본값을 붙여야 한다. Claude Code는 이 변수를 서버 프로세스의 환경에 넣지, Claude Code 자신의 환경에 넣지 않는다. 그래서 .mcp.json의 command·args에서 참조하려면 ${CLAUDE_PROJECT_DIR:-.}처럼 기본값이 필요하다. (플러그인이 제공하는 설정은 예외라 기본값 없이 동작한다.)

③ url이 있는데 type이 없으면 조용히 건너뛴다. Claude Code는 type 없는 항목을 stdio 서버로 읽기 때문에 URL 항목이 깨진다. 설정 파일을 손으로 쓸 때 제일 흔한 실수다:

// .mcp.json 자가 점검 — 붙이기 전에 돌려보면 실수를 잡는다
const j = JSON.parse(require("fs").readFileSync(".mcp.json", "utf8"));
for (const [name, cfg] of Object.entries(j.mcpServers)) {
  if (cfg.url && !cfg.type) console.error(`${name}: url은 있는데 type이 없음`);
  if (!cfg.url && !cfg.command) console.error(`${name}: url도 command도 없음`);
}

같은 이름의 서버가 여러 곳에 정의돼 있으면 우선순위가 높은 쪽 하나만 쓴다. 필드가 병합되지 않는다는 점이 중요하다 — 스코프별로 일부 설정만 덮어쓰는 식은 통하지 않는다.

local
project
user
플러그인이 제공하는 서버
claude.ai 커넥터

스코프 세 개는 이름으로 중복을 판정하고, 플러그인과 커넥터는 엔드포인트(URL·명령어)로 판정한다.

인증과 관리

OAuth 2.0이 필요한 원격 서버는 /mcp 명령으로 인증한다. 같은 패널에서 서버별 도구 개수를 확인할 수 있고, 설정을 지우지 않고 토글로 껐다 켤 수 있다. 안 쓰는 서버를 꺼두는 건 그냥 정리 문제가 아니다 — 연결된 서버의 도구 정의가 컨텍스트를 차지하므로 사용량과 직결된다. Claude의 사용량 한도가 어떻게 계산되는지는 Pro와 Max 요금제를 정리한 글에서 다뤘다.

알아두면 시간을 아끼는 것들:

예약된 이름이 있다: workspace, claude-in-chrome, computer-use, Claude Preview, Claude Browser. 이 이름으로 추가하면 claude mcp add가 거부한다.
데스크톱 설정 가져오기: macOS·WSL에서 claude mcp add-from-claude-desktop.
재연결 정책: HTTP·SSE는 1초부터 두 배씩 늘리며 최대 5회 자동 재시도. stdio는 로컬 프로세스라 자동 재연결 대상이 아니다.
프로젝트 스코프 승인 초기화: claude mcp reset-project-choices.

Claude Desktop에 붙이기

데스크톱은 claude_desktop_config.json을 손으로 편집하는 방식에서 확장(Extensions) 방식으로 옮겨왔다. 공식 안내는 JSON을 직접 다루지 않는 경로를 기본으로 제시한다.

설정 > Extensions
Browse extensions로 디렉터리 열기
원하는 확장 Install
API 키 등 필요한 값 입력

직접 만든 확장을 넣으려면 설정 > Extensions > Advanced settings > Extension Developer > Install Extension에서 .mcpb 파일을 고른다.

두 가지가 실용적으로 유용하다. 첫째, 데스크톱 앱에 Node.js 런타임이 내장돼 있어서 Node를 따로 설치하지 않아도 Node 기반 서버가 돈다. 둘째, API 키 같은 민감한 설정값은 OS 수준 암호화(macOS Keychain, Windows Credential Manager)로 보관된다.

보안 — 이건 꼭 알고 붙이자

MCP 서버는 임의 코드 실행 경로다. 공식 스펙 문서도 이 점을 명시한다: 도구는 임의 코드 실행을 의미하므로 주의해서 다뤄야 하고, 신뢰할 수 있는 서버에서 온 게 아니라면 도구 설명(annotation)조차 신뢰할 수 없는 것으로 취급해야 한다는 것이다.

그리고 대부분의 MCP 소개 글이 빠뜨리는 문구가 Claude Code 보안 문서에 있다:

Anthropic은 디렉터리에 추가하기 전 등재 기준에 따라 커넥터를 심사하지만, 어떤 MCP 서버도 보안 감사하거나 관리하지 않는다.

즉 Anthropic 디렉터리에 올라와 있다는 게 “보안 검증됐다”는 뜻이 아니다. 공식 권고는 직접 만든 서버를 쓰거나, 신뢰하는 제공자의 서버를 쓰라는 것이다.

특히 조심할 유형은 외부 콘텐츠를 가져오는 서버다. 웹페이지·이슈·이메일 같은 외부 텍스트를 컨텍스트로 끌어오는 서버는 프롬프트 인젝션 경로가 된다 — 가져온 문서 안에 “이 파일을 지워라” 같은 지시가 심어져 있을 때 모델이 그걸 사용자 지시로 착각할 수 있다. Claude Code는 새 MCP 서버에 대해 신뢰 확인 절차를 요구하고, 웹 fetch를 별도 컨텍스트 창에서 처리하는 방식으로 이를 완화한다. 다만 -p 플래그로 비대화식 실행할 때는 신뢰 확인이 비활성화된다는 점을 기억해야 한다. 자동화 스크립트에 MCP를 엮을 때 특히 중요하다.

실무적으로는 이 정도가 현실적인 선이다:

서드파티 서버는 필요한 순간에만 켜기(/mcp 토글)
자격증명이 붙은 서버는 --scope project로 커밋하지 않기 — .mcp.json은 버전 관리에 올라간다
외부 콘텐츠를 읽는 서버와 쓰기 권한이 있는 서버를 같은 세션에 함께 켜두지 않기

정리

하려는 일	답
클라우드 SaaS 붙이기	웹 커넥터 (모든 기기에서 공유)
로컬 파일·DB 붙이기	데스크톱 확장 또는 Claude Code stdio
모든 프로젝트에서 쓰기	`claude mcp add --scope user`
팀과 공유	`claude mcp add --scope project` → `.mcp.json` 커밋
새로 붙일 때 transport	`http` (SSE는 deprecated)
사용량 줄이기	`/mcp`에서 안 쓰는 서버 토글 오프

MCP를 실제 사이드 프로젝트 자동화에 엮어서 쓴 기록은 Claude Code로 사이드 프로젝트 자동화하기에 정리해뒀다.

MCP가 “어떤 도구를 쓸 수 있게 할지”라면, 그 도구를 어떤 순서로 쓸지 가르치는 건 스킬 쪽이다 — 클로드 스킬 정리에서 다뤘다. 그리고 붙인 서버가 요금에 얼마나 영향을 주는지(도구 정의가 입력 토큰에 포함된다)는 API 요금 정리에서 단가와 함께 계산했다.

한 가지 더. 사내 문서나 DB를 MCP로 붙이는 이유 중 하나는 답변을 실제 자료에 묶어두기 위해서인데, 붙였다고 해서 인용까지 정확해지는 건 아니다. 근거를 댔는지와 그 근거가 진짜인지는 별개 문제라 — 인용문을 원문과 기계적으로 대조하는 방법은 할루시네이션 검증 파이프라인에 정리했다.