<span class="lang-ko">MCP 서버 연결 - Claude Code 101</span><span class="lang-en">MCP Server Connection

MCP, 일상에서 이해하기

MCP in Everyday Terms

기술 용어 없이, 일상 비유로 MCP를 이해해봅시다.

Let's understand MCP through everyday analogies, no jargon needed.

📱 스마트폰 앱 비유

여러분의 스마트폰을 생각해보세요.

스마트폰 자체는 똑똑하지만, 앱을 설치하기 전에는 할 수 있는 게 한정되어 있습니다. 카카오톡을 설치하면 메시지를 보낼 수 있고, 카메라 앱이 있으면 사진을 찍을 수 있고, 은행 앱이 있으면 계좌를 확인할 수 있죠.

MCP 서버 = Claude에게 설치하는 앱입니다.

  📱 스마트폰 = Claude (기본적으로 똑똑함)
  📦 카카오톡 앱 = Slack MCP (메시지 보내기)
  📦 깃허브 앱 = GitHub MCP (코드 관리)
  📦 엑셀 앱 = PostgreSQL MCP (데이터 조회)
  📦 파일 탐색기 = Filesystem MCP (파일 접근)

앱을 설치하듯이 MCP 서버를 추가하면, Claude가 할 수 있는 일이 확 늘어납니다.

📱 Smartphone App Analogy

Think of your smartphone.

The phone itself is smart, but before installing apps, what it can do is limited. Install KakaoTalk to send messages, a camera app to take photos, a banking app to check accounts.

MCP servers = apps you install for Claude.

  📱 Phone = Claude (smart by default)
  📦 Messaging app = Slack MCP (send messages)
  📦 GitHub app = GitHub MCP (manage code)
  📦 Spreadsheet app = PostgreSQL MCP (query data)
  📦 File manager = Filesystem MCP (access files)

Just like installing apps, adding MCP servers dramatically expands what Claude can do.

MCP 연결 전 vs 후

Before vs After MCP

❌ MCP 없이Without MCP

· "DB에서 매출 확인해줘" → "저는 DB에 접근할 수 없습니다" · "Slack에 결과 보내줘" → "저는 Slack에 메시지를 보낼 수 없습니다" · "GitHub 이슈 확인해줘" → "저는 GitHub API에 접근할 수 없습니다" · 매번 수동으로 복사-붙여넣기 해야 함

· "Check sales in DB" → "I can't access the database" · "Send results to Slack" → "I can't send Slack messages" · "Check GitHub issue" → "I can't access the GitHub API" · Manual copy-paste every time

✅ MCP 연결 후With MCP

· "DB에서 이번 달 매출 확인해줘" → 즉시 쿼리 실행 & 결과 분석 · "결과를 #sales 채널에 보내줘" → 자동으로 Slack 전송 · "이슈 #42 수정하고 PR 올려줘" → 이슈 확인→코드 수정→PR 생성 · 모든 것이 하나의 대화에서 연결됨

· "Check this month's sales in DB" → Instant query & analysis · "Send results to #sales channel" → Auto Slack delivery · "Fix issue #42 and create PR" → Read issue→Fix code→Create PR · Everything connected in one conversation

🎯

핵심: MCP는 어려운 기술이 아닙니다. "Claude에게 새 능력을 추가하는 것"이 전부입니다. 터미널에서 명령어 한 줄이면 됩니다.

Key point: MCP isn't complex technology. It's simply "adding new abilities to Claude." One terminal command is all it takes.

MCP가 뭐야?

What is MCP?

한 줄 요약: Claude에게 외부 세계와 소통하는 능력을 달아주는 표준 규격이다.

One-line summary: A standard protocol that gives Claude the ability to communicate with the outside world.

USB 포트 비유 — 왜 "표준"이 중요한가

옛날에는 핸드폰마다 충전 단자가 달랐습니다. 삼성 따로, LG 따로, 애플 따로...
그런데 USB-C가 나오면서? 하나의 규격으로 모든 기기를 연결할 수 있게 됐죠.

MCP도 마찬가지입니다. 예전에는 Claude가 GitHub을 쓰려면 GitHub용 코드를, Slack을 쓰려면 Slack용 코드를 따로 만들어야 했습니다.

MCP라는 "USB-C 같은 표준"이 생기면서:
  ✅ GitHub MCP 서버 꽂으면 → GitHub 사용 가능
  ✅ Slack MCP 서버 꽂으면 → Slack 사용 가능
  ✅ DB MCP 서버 꽂으면 → DB 조회 가능

규격이 통일되어 있으니, 누구든 MCP 서버를 만들면 Claude에 바로 연결됩니다.

USB Port Analogy — Why "Standard" Matters

Remember when every phone had a different charger? Samsung, LG, Apple — all different...
Then USB-C came along and one standard connects all devices.

MCP is the same idea. Before, connecting Claude to GitHub needed GitHub-specific code, Slack needed Slack-specific code, etc.

Now with MCP as a "USB-C-like standard":
  ✅ Plug in GitHub MCP server → GitHub ready
  ✅ Plug in Slack MCP server → Slack ready
  ✅ Plug in DB MCP server → DB queries ready

Since the standard is unified, anyone can build an MCP server and it connects to Claude instantly.

🔌

Model Context Protocol

MCP는 Model Context Protocol의 약자입니다. AI 모델이 외부 도구와 데이터에 접근하기 위한 개방형 표준 프로토콜이죠.

MCP stands for Model Context Protocol. It is an open standard protocol for AI models to access external tools and data.

🔗

표준화된 연결 방식

Standardized Connection

USB처럼 하나의 규격으로 다양한 도구를 연결합니다. 각 도구마다 따로 연동 코드를 짤 필요 없이, MCP 서버만 있으면 바로 연결됩니다.

Like USB, a single standard connects diverse tools. No need to write separate integration code for each tool — just have an MCP server and you're connected.

♾️

무한 확장 가능

Infinitely Extensible

GitHub, Slack, DB, 웹 검색, 파일 시스템 등 MCP 서버는 계속 늘어나고 있습니다. 직접 만들 수도 있어서 확장에 한계가 없습니다.

GitHub, Slack, DB, web search, filesystem — MCP servers keep growing. You can even build your own, so there's no limit to expansion.

작동 원리

How It Works

MCP가 어떻게 Claude와 외부 도구를 연결하는지 흐름을 살펴봅니다.

Let's walk through how MCP connects Claude with external tools.

MCP 아키텍처 다이어그램

Claude Code          MCP Client          MCP Server         External Tool
    |                     |                     |                    |
    |  "GitHub 이슈 확인해" |                     |                    |
    | ————————→ |                     |                    |
    |                     | JSON-RPC 요청       |                    |
    |                     | ———————→ |                    |
    |                     |                     | API 호출           |
    |                     |                     | ——————→ |
    |                     |                     |                    |
    |                     |                     | 응답 데이터        |
    |                     |                     | ←—————— |
    |                     | 구조화된 결과      |                    |
    |                     | ←—————— |                    |
    |  결과를 자연어로    |                     |                    |
    | ←——————— |                     |                    |
    |                     |                     |                    |
      

💬

쉽게 말하면: 여러분이 Claude에게 말하면 → Claude가 MCP 서버에 "대신 해줘" 하고 → MCP 서버가 실제 서비스(GitHub, DB 등)에서 결과를 가져와서 → Claude가 여러분에게 알려줍니다. 여러분은 자연어로 말하기만 하면 됩니다.

In simple terms: You tell Claude → Claude asks the MCP server "handle this for me" → MCP server fetches results from the actual service (GitHub, DB, etc.) → Claude tells you the result. You just speak in natural language.

사용자가 요청

User Makes a Request

"GitHub 이슈 #42 확인하고 수정해줘"처럼 자연어로 요청합니다. Claude가 어떤 MCP 서버를 호출할지 자동으로 판단합니다.

You make a natural language request like "Check GitHub issue #42 and fix it." Claude automatically determines which MCP server to call.

MCP Client가 요청 전달

MCP Client Forwards Request

Claude Code에 내장된 MCP Client가 JSON-RPC 2.0 형식으로 요청을 MCP Server에 전달합니다. 이 과정은 자동으로 이루어집니다.

The MCP Client built into Claude Code forwards the request to the MCP Server in JSON-RPC 2.0 format. This process happens automatically.

MCP Server가 외부 도구 호출

MCP Server Calls External Tool

MCP Server가 실제 외부 API(GitHub API, DB 커넥션 등)를 호출하여 데이터를 가져옵니다.

The MCP Server calls the actual external API (GitHub API, DB connection, etc.) to fetch data.

결과를 Claude에게 전달

Results Delivered to Claude

외부 도구의 응답이 구조화된 형태로 Claude에게 돌아옵니다. Claude는 이 데이터를 분석하여 사용자에게 자연어로 답변합니다.

The external tool's response is returned to Claude in a structured format. Claude analyzes this data and answers the user in natural language.

📡

기술 포인트: MCP는 JSON-RPC 2.0 프로토콜을 기반으로 합니다. 각 MCP 서버는 로컬에서 실행되는 독립 프로세스이며, Claude Code가 stdin/stdout 또는 HTTP를 통해 통신합니다.

Technical point: MCP is based on the JSON-RPC 2.0 protocol. Each MCP server is an independent process running locally, and Claude Code communicates via stdin/stdout or HTTP.

Popular MCP Server Catalog

가장 많이 사용되는 MCP 서버들입니다. 필요에 따라 골라서 연결하세요.

The most commonly used MCP servers. Pick and connect based on your needs.

서버명Server	npm 패키지npm Package	주요 기능Key Features
Filesystem	@modelcontextprotocol/server-filesystem	프로젝트 외부 파일 접근, 읽기/쓰기, 디렉토리 탐색Access files outside project, read/write, directory navigation
GitHub	@modelcontextprotocol/server-github	이슈/PR 조회·생성, 코드 검색, 리포지토리 관리View/create issues & PRs, code search, repository management
Slack	@modelcontextprotocol/server-slack	메시지 읽기/보내기, 채널 관리, 스레드 검색Read/send messages, channel management, thread search
PostgreSQL	@modelcontextprotocol/server-postgres	데이터베이스 쿼리 실행, 스키마 조회, 테이블 분석Execute database queries, schema inspection, table analysis
Brave Search	@modelcontextprotocol/server-brave-search	웹 검색, 최신 정보 조회, 뉴스 검색Web search, latest information lookup, news search
Memory	@modelcontextprotocol/server-memory	대화 간 정보 저장, 장기 기억 관리, 지식 그래프Store info across conversations, long-term memory, knowledge graph

📦

더 많은 서버: MCP 서버 목록은 계속 늘어나고 있습니다. github.com/modelcontextprotocol/servers에서 공식 서버 목록을, Anthropic MCP Registry에서 검증된 상업용 서버 목록을 확인할 수 있습니다.

More servers: The MCP server list keeps growing. Find the official server list at github.com/modelcontextprotocol/servers, and verified commercial servers at Anthropic MCP Registry.

설정 방법

Setup

MCP 서버를 Claude Code에 연결하는 두 가지 방법을 알아봅니다.

Learn two ways to connect an MCP server to Claude Code.

방법 A: CLI로 추가하기

Method A: Add via CLI

가장 간단한 방법입니다. 터미널에서 한 줄 명령어로 MCP 서버를 추가합니다.

The simplest method. Add an MCP server with a single command in the terminal.

Terminal

# Filesystem MCP 서버 추가 (특정 디렉토리만 접근 허용)
claude mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /path

# GitHub MCP 서버 추가 (환경변수 포함)
claude mcp add github --env GITHUB_TOKEN=your-token \
  -- npx -y @modelcontextprotocol/server-github

# Slack MCP 서버 추가
claude mcp add slack --env SLACK_BOT_TOKEN=xoxb-... \
  -- npx -y @modelcontextprotocol/server-slack

# 연결된 MCP 서버 목록 확인
claude mcp list

# 서버 제거
claude mcp remove filesystem
            

방법 B: JSON 직접 편집하기

Method B: Edit JSON Directly

설정 파일을 직접 수정하여 더 세밀한 제어가 가능합니다. 설정은 .claude/settings.json(프로젝트) 또는 ~/.claude/settings.json(전체)에 저장됩니다.

Edit the configuration file directly for finer control. Settings are stored in .claude/settings.json (project) or ~/.claude/settings.json (global).

.claude/settings.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    },
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-..."
      }
    }
  }
}
            

세션 내 확인하기

Check Within Session

Claude Code 대화 중에 /mcp 명령어로 연결 상태와 컨텍스트 비용을 바로 확인할 수 있습니다.

During a Claude Code session, use /mcp to instantly check connection status and context cost.

Claude Code 세션 내

# 세션 내에서 MCP 상태 확인
/mcp

# 출력 예시:
Connected MCP Servers:
  filesystem   ✔ connected   ~320 tokens
  github       ✔ connected   ~580 tokens
  slack        ✔ connected   ~410 tokens

# 터미널에서 목록 확인
claude mcp list
            

📊

컨텍스트 비용 주의: 각 MCP 서버는 연결 시 도구 정의를 매 요청마다 컨텍스트에 포함합니다. /mcp로 서버별 토큰 소비량을 확인하고, 자주 쓰지 않는 서버는 제거하는 것이 좋습니다.

Watch context cost: Each MCP server includes its tool definitions in context with every request. Check token usage per server with /mcp and remove servers you rarely use.

⌨️ CLI 추가CLI Add

· 한 줄 명령어로 빠르게 추가 · 실수 가능성이 낮음 · 간단한 설정에 적합 · 서버 하나씩 추가할 때 편리

· Quick add with one command · Low risk of mistakes · Ideal for simple setups · Convenient for adding servers one by one

📝 JSON 편집JSON Edit

· 여러 서버를 한번에 설정 · 복잡한 환경변수 관리 가능 · 팀과 설정 파일 공유 용이 · 버전 관리(Git)에 적합

· Configure multiple servers at once · Manage complex environment variables · Easy to share config files with team · Great for version control (Git)

범위(Scope) 설정

Scope Configuration

MCP 서버를 어디에 저장할지 결정합니다. 프로젝트 범위, 사용자 범위, 로컬 범위 세 가지가 있습니다.

Determines where to store the MCP server settings. There are three scopes: project, user, and local.

📁

프로젝트 범위

Project Scope

프로젝트 루트의 .claude/settings.json에 저장됩니다. Git에 커밋하여 팀 전체가 동일한 MCP 서버를 공유할 수 있습니다.

Stored in .claude/settings.json at the project root. Commit to Git so the whole team shares the same MCP servers.

팀 공유Team Shared 버전 관리Version Control

👤

사용자 범위

User Scope

~/.claude/settings.json에 저장됩니다. 내 컴퓨터의 모든 프로젝트에서 사용 가능하지만 나만 사용합니다.

Stored in ~/.claude/settings.json. Available across all projects on your machine, but only for you.

전체 프로젝트All Projects 개인용Personal

🔒

로컬 범위

Local Scope

현재 프로젝트에서만, 나만 사용하는 설정입니다. 민감한 자격 증명이나 실험적인 서버 설정에 적합합니다.

Settings for the current project only, personal use only. Ideal for sensitive credentials or experimental server configurations.

현재 프로젝트Current Project 개인용Personal

범위 지정 방법

# 프로젝트 범위로 추가 (팀 공유, .claude/settings.json)
claude mcp add --scope project github npx -y @modelcontextprotocol/server-github

# 사용자 범위로 추가 (모든 프로젝트, ~/.claude/settings.json)
claude mcp add --scope user filesystem npx -y @modelcontextprotocol/server-filesystem /path

# 로컬 범위로 추가 (현재 프로젝트만, 기본값)
claude mcp add github npx -y @modelcontextprotocol/server-github
      

서브에이전트에 특정 MCP 서버 할당하기

서브에이전트(Subagent)를 사용할 때, 특정 에이전트에게만 특정 MCP 서버를 제공할 수 있습니다. 예를 들어, DB 분석 전담 에이전트에게만 PostgreSQL MCP를 부여하는 식입니다.

Assigning specific MCP servers to subagents

When using subagents, you can provide specific MCP servers to specific agents only. For example, giving only the DB analysis agent access to the PostgreSQL MCP.

서브에이전트 MCP 할당 예시 (YAML)

---
name: db-analyst
mcpServers:
  - postgres
---
# 이 에이전트는 postgres MCP 서버만 사용할 수 있습니다
        

🧭

어떤 범위를 선택할까요?
· 프로젝트 범위: 팀 전체가 공유해야 하는 서버 (Sentry, Jira 등 프로젝트 도구)
· 사용자 범위: 여러 프로젝트에서 자주 쓰는 개인 서버 (GitHub, Brave Search 등)
· 로컬 범위: 민감한 자격 증명이 포함되어 공유하면 안 되는 서버

Which scope to choose?
· Project scope: Servers the whole team should share (Sentry, Jira, etc.)
· User scope: Personal servers used frequently across projects (GitHub, Brave Search, etc.)
· Local scope: Servers with sensitive credentials that should not be shared

실전 활용 시나리오

Real-world Scenarios

MCP 서버를 연결하면 어떤 일이 가능해지는지, 3가지 실전 시나리오로 보여드립니다.

3 real-world scenarios showing what becomes possible when you connect MCP servers.

🚀 시나리오 1: GitHub 이슈 → 코드 수정 → PR 자동화 Scenario 1: GitHub Issue → Code Fix → PR Automation

GitHub MCP 서버를 연결하면, 이슈 확인부터 PR 생성까지 한 번의 요청으로 자동화할 수 있습니다.

With the GitHub MCP server connected, you can automate everything from checking an issue to creating a PR in a single request.

이슈 확인

Check Issue

Claude가 GitHub MCP를 통해 이슈 내용을 읽어옵니다.

Claude reads the issue content via GitHub MCP.

코드 분석 & 수정

Code Analysis & Fix

이슈와 관련된 코드를 찾아 수정합니다.

Finds and fixes the code related to the issue.

PR 생성

Create PR

브랜치 생성, 커밋, PR 올리기까지 자동으로 처리합니다.

Automatically handles branch creation, commit, and PR creation.

Claude Code 대화

You: GitHub 이슈 #42를 확인하고 수정해서 PR 올려줘

Claude: 이슈 #42를 확인했습니다. "로그인 페이지에서 이메일 유효성 검사 누락" 이슈네요.

// Claude가 자동으로 수행하는 작업:
1. GitHub MCP → 이슈 #42 상세 내용 조회
2. 코드 분석 → src/auth/login.ts 파일 확인
3. 코드 수정 → 이메일 유효성 검사 로직 추가
4. GitHub MCP → 브랜치 생성, 커밋, PR 생성

Claude: PR #58을 생성했습니다.
  · 브랜치: fix/issue-42-email-validation
  · 변경 파일: src/auth/login.ts, src/utils/validators.ts
  · 테스트 추가: tests/auth/login.test.ts
        

🗄️ 시나리오 2: DB 스키마 분석 → 마이그레이션 작성 Scenario 2: DB Schema Analysis → Migration Writing

PostgreSQL MCP 서버를 연결하면, DB 구조를 파악하고 마이그레이션 파일을 자동 생성할 수 있습니다.

With the PostgreSQL MCP server connected, you can understand the DB structure and auto-generate migration files.

스키마 조회

Schema Lookup

PostgreSQL MCP를 통해 현재 DB 스키마를 읽어옵니다.

Reads the current DB schema via PostgreSQL MCP.

변경사항 분석

Impact Analysis

요청한 변경이 기존 데이터에 미치는 영향을 분석합니다.

Analyzes the impact of the requested change on existing data.

마이그레이션 생성

Generate Migration

안전한 마이그레이션 SQL과 롤백 스크립트를 작성합니다.

Writes safe migration SQL and rollback scripts.

Claude Code 대화

You: users 테이블에 phone_number 컬럼 추가하는 마이그레이션 만들어줘

Claude: 현재 users 테이블 스키마를 확인했습니다.

// PostgreSQL MCP를 통해 자동 수행:
1. 현재 users 테이블 스키마 조회
2. 기존 데이터 건수 확인 (100만 건)
3. 안전한 마이그레이션 전략 수립

Claude: 마이그레이션 파일을 생성했습니다.
  migrations/20240315_add_phone_number.sql
  · NULL 허용으로 추가 (기존 데이터 안전)
  · 인덱스 CONCURRENTLY 생성 (무중단)
  · 롤백 스크립트 포함
        

💬 시나리오 3: Slack 메시지 분석 → 요약 레포트 Scenario 3: Slack Message Analysis → Summary Report

Slack MCP 서버를 연결하면, 채널의 메시지를 분석하여 요약 레포트를 자동 생성할 수 있습니다.

With the Slack MCP server connected, you can analyze channel messages and auto-generate summary reports.

메시지 수집

Collect Messages

Slack MCP를 통해 특정 채널의 최근 메시지를 가져옵니다.

Fetches recent messages from a specific channel via Slack MCP.

내용 분석

Content Analysis

논의된 주제, 결정 사항, 액션 아이템을 자동으로 분류합니다.

Automatically categorizes discussion topics, decisions, and action items.

레포트 생성

Generate Report

정리된 요약 레포트를 마크다운으로 생성합니다.

Generates a clean summary report in Markdown.

Claude Code 대화

You: #dev-backend 채널의 이번 주 논의를 요약해줘

Claude: Slack MCP를 통해 이번 주 메시지 147건을 분석했습니다.

## 주간 요약 레포트 (#dev-backend)

### 주요 논의 사항
1. API v2 마이그레이션 일정 확정 (3/20)
2. Redis 캐시 TTL 정책 변경 논의
3. 신규 모니터링 도구 도입 검토

### 결정된 사항
· API v2는 점진적 마이그레이션으로 진행
· Redis TTL은 1시간으로 통일

### 액션 아이템
· @김개발: API v2 마이그레이션 가이드 작성
· @박서버: 모니터링 도구 PoC 진행
        

📋 시나리오 4: Notion + GitHub 조합 — 기획자도 개발 현황 파악 Scenario 4: Notion + GitHub Combo — Even PMs Can Track Dev Progress

여러 MCP 서버를 동시에 연결하면, 서로 다른 서비스의 정보를 한 번에 조합할 수 있습니다. 기획자가 "이번 스프린트 진행 상황 정리해줘"라고 하면 끝!

Connect multiple MCP servers simultaneously to combine information across services. A PM just says "summarize this sprint's progress" and it's done!

Claude Code 대화 (GitHub + Notion MCP 연결)Claude Code Chat (GitHub + Notion MCP connected)

You: 이번 스프린트 진행 상황을 Notion 페이지로 정리해줘

Claude: GitHub MCP로 이번 스프린트의 PR과 이슈를 분석하고,
Notion MCP로 정리 페이지를 만들겠습니다.

// Claude가 자동으로 수행하는 작업:
1. GitHub MCP → 최근 2주간의 PR 18건, 이슈 12건 조회
2. PR 상태 분류: 머지 완료 14건, 리뷰 중 3건, 충돌 1건
3. Notion MCP → "Sprint #7 Progress" 페이지 생성
4. 표, 진행률 차트, 담당자별 현황을 Notion에 자동 작성

Claude: Notion에 스프린트 현황 페이지를 만들었습니다.
  · 전체 진행률: 78% (14/18 PR 머지 완료)
  · 블로커: PR #234 충돌 — @김개발님 확인 필요
  · Notion 링크: Sprint #7 Progress 페이지
        

💡

포인트: 이렇게 여러 MCP를 조합하면 서비스 간의 다리 역할을 Claude가 해줍니다. 개발자가 아니어도 개발 현황을 쉽게 파악하고 공유할 수 있어요.

Key point: Combining multiple MCPs lets Claude act as a bridge between services. Even non-developers can easily understand and share development status.

주의사항 & 트러블슈팅

Caution & Troubleshooting

MCP 서버를 사용할 때 반드시 알아야 할 사항들과 흔한 문제 해결법입니다.

Must-know information when using MCP servers, and solutions to common problems.

🔑

환경변수 설정 필수: 대부분의 MCP 서버는 API 토큰이 필요합니다. GitHub MCP는 GITHUB_TOKEN, Slack MCP는 SLACK_BOT_TOKEN을 반드시 설정해야 합니다. 토큰 없이 연결하면 인증 에러가 발생합니다.

Environment variables required: Most MCP servers require API tokens. GitHub MCP requires GITHUB_TOKEN, Slack MCP requires SLACK_BOT_TOKEN. Connecting without a token will cause authentication errors.

🛡️

보안 주의: MCP 서버는 로컬에서 실행됩니다. 이는 장점이자 주의점입니다. DB 서버에 접근하는 MCP를 설정하면 Claude가 실제로 쿼리를 실행할 수 있으므로, 프로덕션 DB에는 읽기 전용 계정을 사용하세요. 민감한 데이터가 있는 환경에서는 접근 범위를 최소화하는 것이 좋습니다.

Security caution: MCP servers run locally. This is both an advantage and a concern. If you set up an MCP that accesses a DB server, Claude can actually execute queries — so use a read-only account for production DBs. In environments with sensitive data, minimize the access scope.

⚠️

흔한 에러: "MCP server not responding"

이 에러가 발생하면 다음을 순서대로 확인하세요:
· npm/npx가 설치되어 있는지 — MCP 서버 대부분은 Node.js 기반입니다
· 패키지명이 정확한지 — @modelcontextprotocol/server-* 형식이 올바른지 확인
· 환경변수가 올바른지 — 토큰이 만료되지 않았는지 확인
· 네트워크 연결 — 외부 API에 접근 가능한지 확인

Common error: "MCP server not responding"

When this error occurs, check the following in order:
· Is npm/npx installed? — Most MCP servers are Node.js-based
· Is the package name correct? — Verify the @modelcontextprotocol/server-* format
· Are environment variables correct? — Check that tokens haven't expired
· Network connection — Verify access to external APIs

💻

/mcp 커맨드: Claude Code 대화 중에 /mcp를 입력하면 현재 연결된 MCP 서버의 상태와 서버별 컨텍스트 토큰 소비량을 즉시 확인할 수 있습니다. 각 MCP 서버는 도구 정의를 매 요청에 포함시키기 때문에, 서버가 많을수록 컨텍스트 비용이 증가합니다. 문제가 의심될 때 가장 먼저 실행해보세요.

/mcp command: During a Claude Code session, type /mcp to instantly check the status of connected MCP servers and token consumption per server. Since each MCP server includes tool definitions in every request, more servers means higher context cost. Run this first when you suspect an issue.

트러블슈팅 명령어

# MCP 서버 상태 확인 (터미널)
claude mcp list

# 특정 서버 상세 정보 확인
claude mcp get github

# 특정 서버 제거 후 재추가
claude mcp remove github
claude mcp add github --env GITHUB_TOKEN=your-token \
  -- npx -y @modelcontextprotocol/server-github

# Claude Code 세션 내에서 상태 + 컨텍스트 비용 확인
/mcp

# 설정 파일 직접 확인
cat ~/.claude/settings.json
      

자주 묻는 질문

FAQ

MCP에 대해 가장 많이 궁금해하는 것들

The most common questions about MCP

네, 가능합니다! MCP는 오픈 프로토콜이기 때문에 누구나 서버를 만들 수 있습니다. TypeScript/Python SDK가 제공되어 있어서, 회사 내부 API나 특정 SaaS 도구를 MCP 서버로 감싸면 Claude가 직접 사용할 수 있게 됩니다. 예를 들어, 회사 내부 HR 시스템을 MCP 서버로 만들면 "이번 달 휴가 현황 알려줘"를 Claude가 처리할 수 있습니다.

Yes! MCP is an open protocol so anyone can build a server. TypeScript/Python SDKs are provided, so you can wrap an internal company API or specific SaaS tool as an MCP server for Claude to use directly. For example, build your HR system as an MCP server, and Claude can handle "show me this month's leave status."

각 MCP 서버는 도구 정의를 Claude에게 매 요청마다 전달합니다. 즉, 서버가 많을수록 컨텍스트를 더 많이 소비하고 비용도 늘어납니다. 공식 문서에 따르면 MCP 도구 설명이 컨텍스트의 10%를 넘으면 Claude Code가 자동으로 Tool Search 모드를 활성화하여 필요한 도구만 동적으로 로드합니다. Claude Code 세션 내에서 /mcp를 입력하면 서버별 토큰 소비량을 확인할 수 있습니다. 실제 사용에서는 꼭 필요한 서버만 유지하는 것이 좋습니다.

Each MCP server sends its tool definitions to Claude with every request. So more servers means more context consumed and higher cost. According to official docs, if MCP tool descriptions exceed 10% of context, Claude Code automatically activates Tool Search mode to dynamically load only needed tools. Type /mcp in a Claude Code session to check token usage per server. In practice, keep only the servers you actually need.

네! --scope project 플래그를 사용하거나 프로젝트 루트의 .claude/settings.json에 직접 작성하면, 해당 프로젝트를 사용하는 모든 팀원이 동일한 MCP 서버 설정을 공유할 수 있습니다. 다만 API 토큰 같은 민감한 정보는 환경변수로 분리하고, 각 팀원이 자신의 토큰을 로컬에 설정하는 것이 좋습니다. 설정 파일은 Git에 커밋하되, 토큰은 .env에 넣어 .gitignore로 관리하세요. 개인 전용 설정은 --scope user로 ~/.claude/settings.json에 저장하면 팀과 분리됩니다.

Yes! Use the --scope project flag or write directly to .claude/settings.json at the project root, and all teammates working on that project will share the same MCP server settings. Separate sensitive info like API tokens into environment variables, with each teammate setting their own token locally. Commit the config file to Git, but put tokens in .env and manage with .gitignore. Personal settings can be separated from the team using --scope user to save in ~/.claude/settings.json.

물론입니다! MCP는 Claude Code의 기능을 확장하는 선택적 기능입니다. MCP 없이도 Claude Code는 파일 읽기/쓰기, 코드 생성, 터미널 명령어 실행 등 핵심 기능을 모두 사용할 수 있습니다. MCP는 "외부 서비스와의 연결"이 필요할 때 추가하는 것이라고 생각하면 됩니다. GitHub에 직접 PR을 올리거나, DB에 쿼리를 날리거나, Slack에 메시지를 보내는 등의 작업이 필요할 때 MCP를 도입하세요.

Of course! MCP is an optional feature that extends Claude Code's capabilities. Without MCP, Claude Code still has all core features: file read/write, code generation, terminal command execution, and more. Think of MCP as something you add when you need "connections to external services." Adopt MCP when you need to create PRs directly on GitHub, execute queries on a DB, send Slack messages, etc.

5분 만에 첫 MCP 연결하기

Your First MCP in 5 Minutes

백문이 불여일견! 지금 바로 따라해보세요. 가장 간단한 Filesystem MCP부터 시작합니다.

Seeing is believing! Follow along right now. We'll start with the simplest one: Filesystem MCP.

✅

사전 준비: Claude Code가 설치되어 있고, Node.js(npx)가 동작하면 됩니다. 별도의 API 키가 필요 없는 MCP라서 초보자가 시작하기 좋습니다.

Prerequisites: You just need Claude Code installed and Node.js (npx) working. This MCP doesn't require any API keys, making it perfect for beginners.

1 MCP 서버 추가하기 Add the MCP Server

터미널을 열고 아래 명령어를 입력하세요. /path/to/allowed/dir 부분을 실제 폴더 경로로 바꿔주세요.

Open your terminal and type the command below. Replace /path/to/allowed/dir with your actual folder path.

Terminal

# Filesystem MCP 서버 추가 (예: Documents 폴더)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents
        

2 연결 확인하기 Verify Connection

서버가 잘 추가됐는지 확인합니다.

Check that the server was added successfully.

Terminal

claude mcp list

# 출력 예시:
  - filesystem: connected
    Tools: read_file, write_file, list_directory, ...
        

3 실제로 사용해보기 Try It Out

Claude Code를 실행하고 자연어로 요청해보세요!

Launch Claude Code and make requests in natural language!

Claude Code 대화Claude Code Chat

You: Documents 폴더에 있는 파일들 중에서 가장 최근에 수정된 파일 5개 알려줘

Claude: Filesystem MCP를 통해 Documents 폴더를 조회했습니다.

  최근 수정된 파일 Top 5:
  1. report-2024Q1.xlsx (2분 전)
  2. meeting-notes.md (1시간 전)
  3. budget-plan.csv (3시간 전)
  4. project-timeline.pdf (어제)
  5. team-roster.json (2일 전)

You: meeting-notes.md 내용 요약해줘

Claude: 파일을 읽어서 요약합니다...
  📝 3월 14일 팀 미팅 노트
  - 주요 안건: Q2 로드맵 확정
  - 결정사항: 모바일 앱 우선 개발
  - 다음 단계: 김개발님이 3/18까지 기술 검토서 작성
        

🚀

다음 단계: Filesystem MCP가 잘 동작하면, GitHub MCP나 Slack MCP도 도전해보세요! 위의 설정 방법 섹션에서 자세한 안내를 확인할 수 있습니다.

Next step: Once Filesystem MCP works, try GitHub MCP or Slack MCP! Check the Setup section above for detailed instructions.