Claude Code의 MCP (Model Context Protocol) 는 GitHub, Sentry, 데이터베이스, Notion과 같은 외부 도구를 Claude에 연결하는 메커니즘입니다. 연결해 두면 "다른 도구의 화면을 복사해서 붙여넣는" 작업이 사라지고, Claude가 해당 시스템을 직접 읽고 조작할 수 있게 됩니다. 서버 추가, 스코프 (Scope), 인증, 호출 방법까지 실제로 사용하는 부분을 한 차례 정리합니다.

MCP란

MCP는 "AI와 외부 도구를 연결하기 위한 공통 규격"입니다. USB처럼 대응하는 서버 (Server) (GitHub나 Sentry 등의 제공 측)를 Claude Code에 꽂으면, 해당 도구의 기능을 Claude에서 사용할 수 있게 됩니다. 오픈 규격이므로 대응 서버는 공식 디렉토리만 해도 수백 개가 있습니다.

연결 시의 기준은 명확합니다. **"다른 도구에서 Claude로 데이터를 복사해서 붙여넣고 있는 자신을 발견했을 때"**입니다. Issue 본문, 모니터링 대시보드의 에러, DB의 쿼리 결과―― 이런 것들을 붙여넣는 대신, Claude가 직접 읽으러 갈 수 있게 됩니다.

서버의 3가지 연결 방식 (트랜스포트, Transport)

서버는 통신 방식 (트랜스포트)에 따라 3종류가 있습니다. 기본적으로 claude mcp add로 추가합니다.

원격 (HTTP)

가장 많이 사용합니다. 클라우드 서비스에 연결하려면 이것을 사용합니다.

# Notion에 연결
claude mcp add --transport http notion https://mcp.notion.com/mcp
# Bearer 토큰을 전달하는 경우
...

로컬 (stdio)

로컬에서 스크립트나 CLI를 서버로 동작시키는 방식입니다. -- (더블 대시)가 핵심이며, 이것 이후는 서버 실행 커맨드로 그대로 전달됩니다 (Claude 측의 옵션과 섞이지 않도록 구분합니다).

# Airtable의 로컬 서버를 추가 (환경 변수 포함)
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
-- npx -y airtable-mcp-server

--를 잊어버리면, 서버에 전달하고 싶은 --port와 같은 플래그를 Claude 자신의 옵션으로 해석하려고 시도하여 실패합니다. 이 부분만 주의하세요.

스코프 (Scope) — 설정을 어디에 저장할 것인가

동일한 서버라도 어느 범위에서 유효하게 할지를 --scope (-s)로 선택합니다. 이것이 MCP에서 가장 혼동하기 쉬운 부분입니다.

# 본인만 · 이 프로젝트만 (기본값)
claude mcp add --transport http stripe https://mcp.stripe.com
# 팀과 공유 (.mcp.json에 작성되며, 커밋 가능)
...

사용 구분은, 팀에게 배포하고 싶다면 project (.mcp.json을 커밋) / 본인 전용의 편리한 서버는 user / 인증 정보가 포함된 실험은 local입니다. 동일한 이름이 여러 스코프에 있으면 local > project > user 순으로 하나만 채택됩니다 (필드는 병합되지 않습니다).

참고로 project 스코프의 .mcp.json

는 타인의 리포지토리(Repository)에서 멋대로 실행되지 않도록, 사용 전 승인 프롬프트가 나타납니다 (안전 중심의 설계).

.mcp.json

의 형태와 환경 변수 확장

--scope project

로 추가하면, 리포지토리 직하에 이 형태로 작성됩니다. 직접 작성해도 좋습니다.

{
"mcpServers": {
"api-server": {
...

${API_KEY}

・${VAR:-default}

의 **환경 변수 확장 (Environment Variable Expansion)**이 적용됩니다 (command, args, env, url, headers에서 사용 가능). 덕분에, API 키 자체는 커밋하지 않고, 각자의 환경 변수로부터 주입하면서 설정 파일만 팀과 공유할 수 있습니다.

원격 서버 인증 (OAuth)

많은 클라우드 서버는 인증이 필요합니다. Claude Code는 OAuth 2.0을 지원하며, 추가 → /mcp를 통한 브라우저 로그인의 2단계로 이루어집니다.

# 1. 서버 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

# 2. Claude Code 내에서 /mcp 실행 → 브라우저가 열리며 로그인
/mcp

토큰은 안전하게 저장되며 자동으로 갱신(Refresh)됩니다. 세션을 열지 않고 셸(Shell)에서 인증하고 싶다면 claude mcp login sentry를 사용하세요 (해제는 claude mcp logout sentry).

GitHub와 같이 PAT (Personal Access Token, 개인 액세스 토큰)를 헤더로 전달하는 타입도 있습니다.

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer YOUR_GITHUB_PAT"

서버 관리

claude mcp list # 목록
claude mcp get github # 상세 (연결 상태, 인증 설정)
claude mcp remove github # 삭제

Claude Code 내에서 /mcp를 입력하면 연결 상태, 도구(Tool) 수, 인증 필요 여부를 패널로 확인할 수 있습니다. 연결되어 있으면 connected, 인증 만료나 자격 증명 오류가 있으면 failed라고 표시되므로, 제대로 작동하지 않을 때는 먼저 이곳을 확인하세요. 설정을 삭제하지 않고 일시적으로 끄는 것도 /mcp 패널의 토글을 통해 가능합니다.

실무 사용 예시

연결한 후에는 자연어로 요청하기만 하면 됩니다. 도구 이름을 의식할 필요는 없습니다.

Sentry를 통한 에러 조사

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

최근 24시간 동안 가장 많이 발생한 에러는? 이 에러 ID의 스택 트레이스(Stack Trace)를 보여줘. 어떤 배포(Deploy)가 이것을 포함했어?

GitHub 리뷰 및 Issue

PR #456을 리뷰하고 개선점을 제안해줘. 지금 발견한 버그의 Issue를 생성해줘.

PostgreSQL 질의

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
--dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

이번 달 매출 합계는? orders 테이블의 스키마(Schema)를 보여줘.

리소스 참조 (@) 및 프롬프트 (/)

서버가 공개하는 **리소스 (Resource)**는 파일과 마찬가지로 @를 통해 참조할 수 있습니다. @를 입력하면 연결된 서버의 리소스가 자동 완성 목록에 나타납니다.

@github:issue://123 를 분석해서 수정안을 내줘
@postgres:schema://users 와 @docs:file://database/user-model 을 비교해줘

형식은 @서버명:protocol://경로입니다. 서버가 공개하는 **프롬프트 (Prompt)**는 / 메뉴에 명령어로 나열됩니다.

/mcp__github__pr_review 456
/mcp__jira__create_issue "Bug in login flow" high

/mcp__서버명__프롬프트명 [인자]

형태입니다. 자주 사용하는 정형화된 작업을 서버 측에서 준비해 두었다면, 이 방식으로 한 번에 호출할 수 있습니다.

서버를 늘려도 컨텍스트가 무거워지지 않음 (tool search)

"서버를 많이 연결하면 툴 정의 (tool definition) 때문에 컨텍스트가 팽창하지 않을까?"라는 걱정은 현재로서는 기본적으로 필요하지 않습니다. Claude Code는 기본적으로 tool search를 활성화하고 있으며, MCP 툴 정의는 시작 시점에 모두 읽어들이는 것이 아니라, 필요할 때만 Claude가 검색하여 가져옵니다. 따라서 서버를 늘려도 컨텍스트 소비는 거의 늘어나지 않습니다 (사용감은 이전과 동일합니다).

• 컨텍스트 관리 방식에 대한 생각은 '사용량·잔량 확인 방법'에 자세히 기술했습니다.
• 반드시 항상 보여주고 싶은 소수의 서버만 .mcp.json의 해당 엔트리에 "alwaysLoad": true를 추가하면 시작 시 로드할 수 있습니다.

보안 주의사항

• 신뢰할 수 있는 서버만 연결하세요. 외부 콘텐츠를 가져오는 서버는 프롬프트 인젝션 (prompt injection)의 경로가 될 수 있습니다.
• project 스코프의 .mcp.json은 사용 전에 승인 프롬프트가 나타납니다. 모르는 리포지토리의 .mcp.json을 쉽게 승인하지 마세요.
• OAuth를 경유한다면 oauth.scopes를 통해 요구하는 권한을 필요 최소한으로 제한할 수도 있습니다.

요약

• MCP = 외부 툴을 Claude에 연결하는 공통 규격. "복사 붙여넣기를 하고 있는 자신"을 발견했다면 연결할 때입니다.
• 추가는 claude mcp add를 사용합니다. 원격은 --transport http, 로컬은 -- <명령어>를 사용합니다 (-- 구분자가 핵심입니다).
• 스코프는 **local (자신) / project (팀 공유용, .mcp.json 사용) / user (모든 프로젝트)**의 3가지가 있습니다. .mcp.json은 환경 변수 확장을 통해 키를 숨길 수 있습니다.
• 인증은 추가 후 /mcp를 통해 OAuth 로그인을 진행합니다. 관리는 claude mcp list/get/remove와 /mcp 패널을 사용합니다.
• 리소스는 @, 프롬프트는 /mcp__...를 사용합니다. tool search 덕분에 서버를 늘려도 가볍습니다.
• 자세한 내용은 공식 문서를 참조하세요.

관련 기사

이 기사는 Claude Code를 최대한 활용하여 개인적으로 Web 툴을 양산하는 과정에서 쌓인 메모입니다. 제작한 툴 모음과 양산 기록은 Novare Orbis에서 공개하고 있습니다. 괜찮으시다면 한 번 둘러봐 주세요.

Discussion