서론

본 기사에서는 **Claude Code (CLI 에이전트)**를 위해, 2026년 6월 시점의 최신 공식 문서를 바탕으로 MCP 도입 방법을 정리합니다.

※ Claude.ai (브라우저 버전)에 대해서도 약간 언급합니다.

아키텍처 개요

MCP는 3자 구성으로 동작합니다.

MCP 서버로의 접속 방식은 크게 두 가지가 있습니다. stdio (로컬 PC에서 프로세스를 실행하여 접속)와 Streamable HTTP (클라우드 상의 URL에 접속)입니다. 어느 것을 사용할지는 "무엇에 접속하고 싶은가"에 따라 결정됩니다. 자세한 내용은 기사 말미의 보충 섹션에서 해설합니다.

Claude Code에서의 MCP 설정

전제 조건

stdio 계열의 MCP 서버는 npx를 통해 동작하므로 Node.js가 필요합니다. 필요한 버전은 서버에 따라 다르지만, 18 이상 (권장 버전은 22)을 설치해 두면 거의 문제없을 것이라고 생각합니다.

설정 패턴 요약표

아래에서 상세한 설정 방법을 살펴보겠습니다.

옵션 1: 리모트 서버 추가 (Streamable HTTP)

URL과 토큰만으로 접속할 수 있으며, 로컬 설치가 필요 없습니다.

# 기본 구문
claude mcp add --transport http <name> <url>
# GitHub MCP (PAT 인증)
...

OAuth가 필요한 서비스 (Sentry, Slack, Notion 등)는 추가 후에 다음을 실행합니다:

/mcp # Claude Code 세션 내에서 실행 → 브라우저가 열리며 OAuth 인증 수행

주요 리모트 MCP 서비스 목록

옵션 2: 로컬 프로세스 추가 (stdio)

PC 로컬에서 동작하는 MCP 서버입니다. 파일 시스템이나 DB, 자체 제작 도구에 대한 액세스에 사용합니다.

# 기본 구문
claude mcp add [options] <name> -- <command> [args...]
# ⚠️ 옵션（--transport, --env, --scope, --header）은 반드시 서버 이름의 "앞"에 작성할 것
...

npx 버전 고정의 중요성

# ❌ 운영/팀 환경에서는 피해야 함 (매번 최신 버전을 가져옴)
-- npx -y @modelcontextprotocol/server-github
# ✅ 버전 고정 (.mcp.json에 직접 작성하는 것을 권장)
...

옵션 3: JSON 설정 파일로 관리 (.mcp.json을 프로젝트 루트에 두고 Git으로 관리하는 것이 가장 심플함)

{
"mcpServers": {
"github": {
...

환경 변수 확장 (Variable Expansion) 구문

.mcp.json 내부에서는 다음과 같은 변수 확장을 사용할 수 있습니다:

JSON에서 직접 추가하는 커맨드

# add-json 커맨드로 JSON 문자열로부터 추가
claude mcp add-json weather-api \
'{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer TOKEN"}}'
...

스코프 (저장 위치) 3가지 종류

MCP 서버를 추가할 때, --scope 옵션으로 설정을 어디에 저장할지 지정할 수 있습니다.

선택 기준

팀에서 동일한 서버를 사용 → project (.mcp.json을 Git 관리)
개인 실험 · API 키가 필요한 설정 → local (기본값)
어떤 프로젝트에서도 사용하는 개인 설정 → user

스코프 우선순위 (동일한 이름의 서버가 충돌할 경우)

1. local
2. project
3. user
...

동일한 이름이 여러 개 있을 경우, 가장 우선순위가 높은 스코프의 설정이 통째로 사용됩니다 (필드 머지(Merge)는 수행되지 않습니다).

서버 관리 커맨드

# 목록 표시 (연결 상태도 확인 가능)
claude mcp list
# 특정 서버의 상세 확인
...

.mcp.json의 프로젝트 스코프 서버는 보안을 위해 최초 실행 시 승인이 필요합니다. claude mcp list에서 ⏸ Pending approval이라고 표시되어 있다면, 인터랙티브 모드로 claude를 실행하여 승인해 주세요.

실전 사용 예시

Sentry로 에러 조사하기

# 추가
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
# 인증
...

# 사용 예시 (자연어로 지시하기만 하면 됨)
"지난 24시간 동안 가장 많이 발생한 에러를 알려줘"
"에러 ID abc123의 스택 트레이스(Stack Trace)를 보여줘"
...

GitHub에서 PR 리뷰하기

GitHub PAT 취득: https://github.com/settings/personal-access-tokens

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
--header "Authorization: Bearer ${GITHUB_PAT}"

"PR #456을 리뷰하고 개선점을 제안해줘"
"나에게 할당된 모든 오픈 PR(Open PR)을 보여줘"
"버그를 발견했으니 새로운 이슈(Issue)를 생성해줘"

PostgreSQL을 자연어로 쿼리하기

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

"이번 달 총 매출을 알려줘"
"orders 테이블의 스키마(Schema)를 확인해줘"
"지난 90일 동안 구매하지 않은 사용자를 검색해줘"

Claude.ai (브라우저 버전)에서의 Remote MCP

플랜별 대응 현황

추가 방법

claude.ai/customize/connectors 에 접속 → URL 입력 → OAuth 플로우를 통해 인증. 토큰 리프레시(Token Refresh)는 자동으로 이루어집니다.

claude.ai의 설정을 Claude Code에서 공유하기

Claude.ai 계정으로 로그인되어 있는 Claude Code는 claude.ai에서 추가한 커넥터(Connector)를 자동으로 참조합니다. 동일한 서버를 두 곳에서 각각 설정할 필요가 없습니다.

# Claude.ai 커넥터 목록 확인
/mcp
# → claude.ai 유래 서버는 "from claude.ai" 인디케이터와 함께 표시됨
...

보안상 주의사항

MCP는 AI 에이전트에게 "손과 발"을 부여하는 것이므로, 보안 리스크에 대한 이해가 중요합니다.

주요 리스크

1. 툴 포이즈닝 (Tool Poisoning)

MCP 서버의 툴 정의(설명문)에 악의적인 지시를 심는 공격입니다. 사용자에게는 무해해 보일지라도, AI가 실행 시점에 기밀 파일을 외부로 전송하는 등의 동작을 수행하게 만들 가능성이 있습니다. 2025년 4월에 구체적인 공격 기법이 공개되었으며, 이는 실제 존재하는 리스크입니다.

대책:

• 공식 또는 유명 OSS(Open Source Software) 서버만 사용한다
• 프로덕션 환경에서는 npx -y를 통한 버전 고정 없는 실행을 피한다
• 툴 호출 로그를 정기적으로 확인한다

2. 프롬프트 인젝션 (Prompt Injection)

MCP 툴이 외부 콘텐츠(이메일, 웹 페이지 등)를 읽을 때, 그 안에 포함된 지시 사항을 AI가 실행해 버리는 리스크입니다.

대책:

• 외부 콘텐츠를 처리하는 세션에서는 승인 정책을 untrusted 수준으로 설정한다
• 중요한 작업(DB 업데이트, 운영 환경 작업)에는 반드시 인간의 확인 단계를 둔다

3. 시크릿 유출 (Secret Leakage)

.mcp.json이나 설정 파일에 API 키를 하드코딩(Hardcode)하는 리스크입니다.

# ❌ 나쁜 예
"headers": { "Authorization": "Bearer ghp_actual_token_here" }
# ✅ 좋은 예
...

대책:

• .mcp.json은 Git으로 관리하므로, 시크릿(Secret)은 반드시 환경 변수를 참조하도록 한다
• OAuth 토큰은 최소 권한 범위(Scope)로 발급한다
• 팀 단위로 사용할 경우 시크릿 매니저(Secret Manager)를 이용한다

인시던트: Asana MCP 서버 데이터 유출 (2025년 6월)

악의적인 공격이 아니라, MCP 구현 상의 버그가 정보 유출로 직결된 실제 사례입니다.

테넌트(Tenant) 간의 액세스 제어가 불완전했던 버그로 인해, 특정 사용자가 다른 조직의 태스크, 프로젝트 메타데이터, 코멘트, 파일 등에 접근할 수 있는 상태가 약 1개월간 지속되었다고 합니다.

참고: Asana, MCP AI 기능이 고객 데이터를 다른 조직에 노출했다고 경고 (BleepingComputer)

자주 발생하는 문제점

OAuth 인증 루프 (Slack・Notion・Sentry)

일정 기간이 지나면 재인증 (Re-authorization)이 필요합니다.

/mcp → 대상 서버 선택 → 재인증

도구가 컨텍스트를 압박하는 경우

연결된 서버가 늘어나면 도구 정의 (Tool definition)가 컨텍스트 (Context)를 압박할 수 있습니다. 2026년 1월에 도입된 Tool Search 덕분에, Claude Code 최신 버전에서는 필요할 때만 도구를 온디맨드 (On-demand)로 로드하는 방식을 사용합니다. 먼저 Claude Code를 최신 버전으로 업데이트해 보세요.

특정 서버를 항상 로드하고 싶다면 .mcp.json에서 alwaysLoad: true를 설정합니다:

{
"mcpServers": {
"core-tools": {
...

MCP 추가 요약

• SaaS 및 외부 서비스에는 --transport http로 URL을 지정하기만 하면 됩니다.
• 로컬 DB 및 파일에는 --transport stdio로 npx 명령어를 지정합니다.
• 팀 단위로 공유하려면 --scope project를 사용하여 .mcp.json을 Git으로 관리합니다.
• claude.ai와 Claude Code는 설정을 공유할 수 있으므로 중복 설정은 필요하지 않습니다.

처음 하나를 시도해 본다면, GitHub MCP (--transport http)가 설정이 가장 간편하여 추천합니다.

보충: 연결 방식 (stdio 및 Streamable HTTP)에 대하여

본문에서 등장한 두 가지 연결 방식에 대해 보충 설명을 덧붙입니다.

stdio (standard input/output의 약자)는 로컬 PC에서 MCP 서버 프로세스를 실행하고, 표준 입출력을 통해 Claude Code와 통신하는 방식입니다. 레이턴시 (Latency)가 낮고 인터넷 연결이 필요 없다는 장점이 있는 반면, 각자의 PC에 개별적인 셋업이 필요합니다.

Streamable HTTP는 클라우드 상의 HTTPS 엔드포인트 (Endpoint)로 요청을 보내는 방식입니다. URL만 알면 연결할 수 있기 때문에 팀 단위 전개나 모바일 이용에 적합합니다. 이전에 사용되던 SSE (Server-Sent Events) 방식의 후속이며, 현재 SSE는 권장되지 않습니다 (Deprecated).

참고 링크

Discussion