Claude Code MCP 서버 연동 완전정리: AI에 외부 도구를 연결하는 법

Claude Code MCP 서버 연동 완전정리: AI에 외부 도구를 연결하는 법

GitHub에서 이슈를 읽고, Slack에 메시지를 보내고, 데이터베이스를 조회하는 걸 Claude Code 안에서 대화 한 마디로 할 수 있다면? MCP(Model Context Protocol)가 바로 그 기술입니다. 이 글에서는 MCP의 개념부터 설정, 인기 서버, 커스텀 서버 만들기까지 완전 정리합니다.

MCP 서버 연동 완전정리

---

1. MCP란? — AI에 도구를 연결하는 표준 프로토콜

Model Context Protocol

MCP는 AI 모델과 외부 도구/데이터를 연결하는 개방형 표준 프로토콜입니다. USB-C가 다양한 기기를 하나의 규격으로 연결하듯, MCP는 AI를 다양한 서비스에 연결합니다.

개념	설명
MCP 클라이언트	Claude Code (도구를 사용하는 쪽)
MCP 서버	외부 서비스를 제공하는 쪽 (GitHub, Slack 등)
프로토콜	클라이언트와 서버가 소통하는 표준 규격

MCP가 하는 일

Claude Code (클라이언트) ←→ MCP 프로토콜 ←→ MCP 서버 ←→ 외부 서비스
                                                         (GitHub, DB, Slack...)

MCP 없이 vs MCP 있을 때

상황	MCP 없이	MCP 있을 때
GitHub 이슈 확인	브라우저 열어서 직접 확인	"이슈 #42 보여줘"
DB 조회	SQL 클라이언트에서 직접 실행	"users 테이블 스키마 보여줘"
Slack 전송	Slack 앱 열어서 직접 작성	"개발채널에 배포 완료 알려줘"
파일 검색	탐색기에서 직접 찾기	"로그 디렉토리에서 에러 찾아줘"

200개 이상의 MCP 서버가 이미 존재하며, 계속 늘어나고 있습니다.

MCP란?

---

2. MCP 서버 추가 방법

CLI로 추가하기

# HTTP 서버 (원격 서비스 — 권장)
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# SSE 서버 (레거시, 가능하면 HTTP 사용)
claude mcp add --transport sse asana https://mcp.asana.com/sse

# Stdio 서버 (로컬 프로세스)
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "postgresql://localhost/mydb"

# 환경 변수 포함
claude mcp add --transport stdio myserver \
  --env API_KEY=your-key \
  -- node server.js

전송 방식 3가지

전송 방식	설명	사용 시점
HTTP	양방향 HTTP 스트리밍 (권장)	원격 클라우드 서비스
SSE	Server-Sent Events (레거시)	HTTP 불가능한 경우만
Stdio	로컬 자식 프로세스	로컬 도구, 커스텀 스크립트

관리 명령어

# 서버 목록 보기
claude mcp list

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

# 서버 제거
claude mcp remove github

# Claude Desktop에서 가져오기
claude mcp add-from-claude-desktop

# JSON으로 직접 추가
claude mcp add-json myserver '{"type":"http","url":"https://api.example.com/mcp"}'

Claude Code 안에서 관리

# /mcp 커맨드로 대화형 관리
> /mcp

# 인증, 서버 상태 확인, 자격 증명 관리 등

 

MCP 서버 추가 방법

---

3. 인기 MCP 서버 TOP 10

바로 연결할 수 있는 서버들

서버	종류	기능	추가 명령
GitHub	HTTP	PR, 이슈, 코드 검색	claude mcp add --transport http github https://api.githubcopilot.com/mcp/
Sentry	HTTP	에러 모니터링, 디버깅	claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
Notion	HTTP	페이지, 데이터베이스	claude mcp add --transport http notion https://mcp.notion.com/mcp
PostgreSQL	Stdio	DB 조회, 스키마 탐색	claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "..."
Slack	HTTP	채널 검색, 메시지 전송	커뮤니티 서버
Puppeteer	Stdio	브라우저 자동화	npx -y @modelcontextprotocol/server-puppeteer
Brave Search	HTTP	웹 검색	공식 서버
Airtable	Stdio	스프레드시트 DB	claude mcp add --env AIRTABLE_API_KEY=... airtable -- npx -y airtable-mcp-server
Asana	SSE	프로젝트 관리	claude mcp add --transport sse asana https://mcp.asana.com/sse
PayPal	HTTP	결제 관리	claude mcp add --transport http paypal https://mcp.paypal.com/mcp

더 많은 서버 찾기

• 공식 저장소: github.com/modelcontextprotocol/servers
• 커뮤니티: 200개 이상의 MCP 서버 생태계

인기 MCP 서버

---

4. 설정 파일 구조

.mcp.json — 프로젝트 공유 설정

프로젝트 루트에 .mcp.json을 만들면 팀원과 MCP 설정을 공유할 수 있습니다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_URL}"],
      "env": {
        "DB_URL": "${DB_URL:-postgresql://localhost/mydb}"
      }
    }
  }
}

3가지 스코프

스코프	저장 위치	공유	활용
Project	.mcp.json (프로젝트 루트)	Git 커밋 가능	팀 공통 서버
Local	~/.claude.json (프로젝트별)	본인만	개인 API 키
User	~/.claude.json (전역)	본인만, 모든 프로젝트	범용 도구

# 스코프 지정
claude mcp add --scope project --transport http github https://...
claude mcp add --scope local --transport http myapi https://...
claude mcp add --scope user --transport http search https://...

환경 변수 확장

{
  "env": {
    "API_KEY": "${API_KEY}",
    "DB_URL": "${DB_URL:-https://default.db.com}"
  }
}

• ${VAR}: 환경 변수 직접 참조
• ${VAR:-기본값}: 변수 없으면 기본값 사용

설정 파일 구조

---

5. MCP의 3가지 기능: 도구, 리소스, 프롬프트

도구 (Tools) — Claude가 실행하는 함수

MCP 서버가 제공하는 함수로, Claude가 필요할 때 호출합니다.

# Claude가 자동으로 MCP 도구를 인식하고 사용
"GitHub에 이슈 만들어줘"
# → mcp__github__create_issue 도구 호출

"users 테이블에서 최근 가입자 10명 보여줘"
# → mcp__db__query 도구 호출

리소스 (Resources) — 읽기 전용 데이터

@멘션으로 참조하는 데이터 소스입니다.

# @서버이름:프로토콜://경로
"@github:issue://123 분석하고 수정안 제시해줘"
"@docs:file://api/authentication 리뷰해줘"
"@postgres:schema://users 구조 설명해줘"

프롬프트 (Prompts) — 재사용 가능한 템플릿

MCP 서버가 제공하는 명령 템플릿입니다.

# /mcp__서버이름__프롬프트이름
/mcp__github__pr_review 456
/mcp__jira__create_issue "로그인 버그" high

기능	방향	사용법	예시
도구	Claude → 서버	자동 호출	"이슈 만들어줘"
리소스	서버 → Claude	@멘션	@github:issue://123
프롬프트	사용자 → Claude	/명령어	/mcp__github__pr_review

MCP의 3가지 기능

---

6. 인증 방법

OAuth 2.0 — 원격 서버 표준

대부분의 HTTP MCP 서버는 OAuth 2.0 인증을 사용합니다.

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

# 2. Claude Code 안에서 인증
> /mcp
# → 브라우저가 열리며 로그인 진행
# → 토큰 자동 저장 (macOS Keychain / Windows 자격 증명)

Bearer 토큰

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

커스텀 헤더

claude mcp add --transport http api https://api.company.com/mcp \
  --header "X-API-Key: your-key" \
  --header "X-Custom-Header: value"

환경 변수로 보안 관리

{
  "mcpServers": {
    "api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}

비밀 키를 .mcp.json에 직접 넣지 마세요! 환경 변수 ${API_TOKEN}을 사용하세요.

인증 방법

---

7. 커스텀 MCP 서버 만들기

TypeScript로 만들기

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new McpServer({
  name: "my-server",
  version: "1.0.0",
});

// 도구 정의
server.tool("get_weather", { city: "string" }, async ({ city }) => {
  const data = await fetchWeather(city);
  return { content: [{ type: "text", text: JSON.stringify(data) }] };
});

// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

Python으로 만들기 (FastMCP)

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("my-server")

@mcp.tool()
def get_weather(city: str) -> str:
    """도시의 현재 날씨를 조회합니다."""
    data = fetch_weather(city)
    return json.dumps(data)

@mcp.resource("weather://{city}")
def weather_resource(city: str) -> str:
    """날씨 리소스를 제공합니다."""
    return fetch_weather(city)

mcp.run()

등록하기

# 로컬 서버 등록
claude mcp add --transport stdio my-weather -- node dist/server.js

# 또는 Python
claude mcp add --transport stdio my-weather -- python server.py

SDK	언어	특징
TypeScript SDK	JS/TS	공식 SDK, 타입 안전
Python SDK	Python	FastMCP 인터페이스, 데코레이터 방식

커스텀 MCP 서버 만들기

---

8. 도구 검색 (Tool Search)

MCP 서버가 많아지면?

MCP 서버를 여러 개 연결하면 도구가 수십~수백 개가 됩니다. 모든 도구를 한번에 로드하면 컨텍스트 윈도우를 낭비하게 됩니다. 도구 검색(Tool Search) 이 이를 해결합니다.

동작 방식

항목	설명
활성화 조건	MCP 도구가 컨텍스트의 10% 초과 시 자동
동작	필요한 도구만 동적으로 로드
지원 모델	Sonnet 4, Opus 4 이상 (Haiku 미지원)

설정 옵션

# 환경 변수로 제어
ENABLE_TOOL_SEARCH=auto claude        # 기본값 (10% 초과 시 자동)
ENABLE_TOOL_SEARCH=auto:5 claude      # 5% 초과 시 자동
ENABLE_TOOL_SEARCH=true claude        # 항상 활성화
ENABLE_TOOL_SEARCH=false claude       # 비활성화 (모두 로드)

MCP 출력 토큰 제한

# 기본: 10,000 토큰에서 경고, 25,000에서 잘림
MAX_MCP_OUTPUT_TOKENS=50000 claude    # 최대 출력 토큰 확장

# 서버 시작 타임아웃
MCP_TIMEOUT=10000 claude              # 10초로 설정

도구 검색 (Tool Search)

---

9. 보안 주의사항

MCP 서버 보안 체크리스트

항목	설명
소스 검증	신뢰할 수 있는 출처의 서버만 사용
비밀 키 보호	.mcp.json에 직접 키 넣지 않기
환경 변수	${API_KEY} 형식으로 비밀 관리
최소 권한	필요한 권한만 부여
정기 점검	토큰 90일마다 교체 권장

Stdio 서버 주의점

Stdio 서버는 로컬 머신에서 직접 실행됩니다. 시스템 전체에 접근할 수 있으므로 신뢰할 수 있는 서버만 사용하세요.

# ⚠️ 이런 설정은 위험할 수 있습니다
claude mcp add --transport stdio unknown -- npx untrusted-package

# ✅ 검증된 공식 서버 사용
claude mcp add --transport stdio db -- npx -y @bytebase/dbhub --dsn "..."

엔터프라이즈 관리

조직에서 MCP 서버를 중앙 관리할 수 있습니다.

// managed-mcp.json (관리자가 배포)
// macOS: /Library/Application Support/ClaudeCode/
// Linux: /etc/claude-code/
// Windows: C:\Program Files\ClaudeCode\
{
  "allowedMcpServers": [
    { "serverName": "github" },
    { "serverUrl": "https://mcp.company.com/*" }
  ],
  "deniedMcpServers": [
    { "serverName": "untrusted-server" }
  ]
}

보안 주의사항

---

10. 자주 묻는 질문 (FAQ)

Q: MCP 서버를 여러 개 동시에 사용할 수 있나요?
A: 네! 원하는 만큼 추가할 수 있습니다. 도구가 많아지면 Tool Search가 자동으로 활성화되어 효율적으로 관리합니다.

Q: Claude Desktop에서 쓰던 MCP 설정을 가져올 수 있나요?
A: claude mcp add-from-claude-desktop 명령으로 Claude Desktop의 설정을 그대로 가져올 수 있습니다.

Q: Windows에서 Stdio 서버가 안 되는데요?
A: Windows에서는 npx 등의 명령에 cmd /c 래퍼가 필요합니다. claude mcp add --transport stdio my-server -- cmd /c npx -y @some/package

Q: MCP 서버가 응답하지 않으면?
A: MCP_TIMEOUT 환경 변수로 타임아웃을 조정하세요. 기본 10초이며, 느린 서버는 더 길게 설정할 수 있습니다.

Q: Hook과 MCP 서버의 차이가 뭔가요?
A: Hook은 이벤트 발생 시 자동 실행되는 확정적 자동화입니다. MCP 서버는 Claude가 필요할 때 호출하는 외부 도구입니다. Hook은 차단 가능하지만, MCP 도구는 차단할 수 없습니다.

Q: 커스텀 MCP 서버를 팀에 배포하려면?
A: 서버를 npm 패키지나 Docker 이미지로 배포하고, .mcp.json을 Git에 커밋하면 팀원들이 동일한 설정을 사용할 수 있습니다. 비밀 키는 환경 변수로 분리하세요.

---

면책 조항: 이 글은 정보 제공 목적으로 작성되었습니다. Claude Code의 기능과 요금은 Anthropic의 정책에 따라 변경될 수 있으며, 최신 정보는 공식 문서를 확인해 주세요.