MCP & 외부 연결

이 챕터의 예시는 일반적인 업무 흐름을 기반으로 한 참고용입니다. 실제 업무 방식과 다를 수 있으니, 프롬프트의 구조를 참고하고 본인의 현업에 맞게 수정해서 사용하세요.

MCP란?

**MCP(Model Context Protocol)**는 AI 도구와 외부 서비스를 연결하는 표준 프로토콜입니다. 쉽게 말해, "Claude Code에 플러그인을 꽂는 것"입니다. MCP 서버 하나를 연결하면 Claude Code에 새로운 **도구(tool)**가 추가됩니다.

Claude Code (AI) ←→ MCP 프로토콜 ←→ MCP 서버 ←→ 외부 서비스
                                        |
                                   GitHub, Slack,
                                   파일시스템, 검색 등

기존에는 AI가 외부 서비스를 쓰려면 서비스마다 별도 통합이 필요했습니다. MCP는 이를 하나의 표준 방식으로 통일합니다. USB 포트처럼 규격만 맞으면 어떤 서비스든 꽂을 수 있습니다.

MCP가 추가하는 것

MCP 서버 찾기

공식 MCP 서버 목록은 아래 저장소에서 확인할 수 있습니다:

https://github.com/modelcontextprotocol/servers

자주 쓰는 MCP 서버

이 외에도 Notion, Linear, Sentry, PostgreSQL 등 수백 개의 커뮤니티 MCP 서버가 있습니다.

설정 방법

프로젝트 루트에 .mcp.json 파일을 만듭니다.

.mcp.json 파일 구조

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    },
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-slack"],
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

각 필드 설명

환경변수 관리

토큰은 .mcp.json에 직접 넣지 않고, .env 파일을 통해 관리합니다:

# .env (프로젝트 루트)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxxxxxxxxx

.mcp.json에서는 ${변수명} 형식으로 참조합니다:

"env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }

.env 파일은 반드시 .gitignore에 추가하세요. .mcp.json은 Git에 올라갈 수 있으므로 토큰을 직접 입력하면 안 됩니다.

설정 확인

/mcp    # Claude Code 내에서 연결된 MCP 서버 상태 확인

이 명령으로 각 서버의 연결 상태, 사용 가능한 도구 목록을 확인할 수 있습니다.

Step-by-step: GitHub MCP 연결하기

1단계: GitHub Personal Access Token 발급

1. https://github.com/settings/tokens 접속
2. "Generate new token (classic)" 클릭
3. 필요한 권한 선택: repo, read:org, read:user
4. 토큰 생성 후 복사 (한 번만 보여줌)

2단계: .env 파일에 토큰 저장

# .env
GITHUB_TOKEN=ghp_여기에_토큰_붙여넣기

3단계: .mcp.json 작성

{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

4단계: Claude Code 재시작

설정 변경 후 Claude Code를 재시작하거나, /mcp 명령으로 서버를 다시 로드합니다.

5단계: 동작 확인

이 프로젝트의 최근 PR 목록 보여줘.

Claude Code가 GitHub MCP를 통해 PR 목록을 가져오면 성공입니다.

Step-by-step: Slack MCP 연결하기

1단계: Slack App 생성

1. https://api.slack.com/apps 접속
2. "Create New App" > "From scratch" 선택
3. 앱 이름과 워크스페이스 선택

2단계: Bot Token 발급

1. 좌측 메뉴 "OAuth & Permissions" 클릭
2. Bot Token Scopes 추가:
   • channels:history - 채널 메시지 읽기
   • channels:read - 채널 목록 보기
   • chat:write - 메시지 보내기
   • users:read - 사용자 정보 보기
3. "Install to Workspace" 클릭
4. Bot User OAuth Token 복사 (xoxb-로 시작)

3단계: .env에 토큰 저장

# .env
SLACK_BOT_TOKEN=xoxb-여기에_토큰_붙여넣기

4단계: .mcp.json에 Slack 서버 추가

{
  "mcpServers": {
    "slack": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-slack"],
      "env": { "SLACK_BOT_TOKEN": "${SLACK_BOT_TOKEN}" }
    }
  }
}

5단계: 동작 확인

#talk_ai 채널 최근 메시지 요약해줘.

Slack 앱을 사용하려는 채널에 초대해야 합니다. 채널에서 /invite @앱이름을 실행하세요.

MCP 도구 네이밍 규칙

MCP를 통해 추가된 도구는 mcp__<서버명>__<도구명> 형식으로 이름이 붙습니다. 서버명은 .mcp.json에서 지정한 키 이름입니다.

이 네이밍을 알면 Claude Code 로그에서 어떤 MCP 서버의 어떤 도구가 호출되었는지 쉽게 파악할 수 있습니다.

실전 활용 시나리오

1. GitHub MCP - PR 자동 생성, 이슈 관리

이번 작업 내용으로 PR 만들어줘. 리뷰어는 @김개발, 라벨은 "enhancement".

이슈 #42에 달린 코멘트 읽고, 요청된 수정사항 반영해줘.

최근 일주일간 머지된 PR 목록 정리해줘.

2. Slack MCP - 채널 메시지 읽기/보내기

#talk_ai 채널에서 오늘 논의된 내용 요약해줘.

방금 만든 재고 알림 결과를 #한끼통살-운영 채널에 보내줘.

#일반 채널에서 이번 주 논의된 배포 관련 내용만 정리해줘.

3. Filesystem MCP - 안전한 폴더 접근

특정 폴더만 접근을 허용하여 실수로 다른 프로젝트를 건드리는 사고를 방지합니다.

{
  "mcpServers": {
    "egnis-data": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@anthropic-ai/mcp-server-filesystem", "/Users/me/Documents/egnis-data"]
    }
  }
}

위 설정을 하면 /Users/me/Documents/egnis-data 폴더 내의 파일만 읽고 쓸 수 있습니다.

4. 여러 MCP 조합 - 워크플로우 자동화

MCP의 진짜 힘은 여러 서버를 조합할 때 나옵니다:

Slack #요청-채널에서 최근 기능 요청 읽고,
각 요청을 GitHub 이슈로 등록해줘.
라벨은 "feature-request"로 달아줘.

이렇게 하면 Claude Code가:

1. Slack MCP로 채널 메시지를 읽고
2. 내용을 분석하여 요청을 추출한 뒤
3. GitHub MCP로 이슈를 생성합니다

서브에이전트에 MCP 연결하기

커스텀 서브에이전트에 특정 MCP 서버만 사용하도록 제한할 수 있습니다. 에이전트 마크다운 파일의 YAML 프런트매터에 mcpServers를 지정합니다:

---
name: slack-reporter
description: Slack 채널 모니터링 및 보고 담당
mcpServers:
  - slack
---
# Slack 보고 에이전트

1. 지정된 채널의 최근 메시지를 읽습니다
2. 주요 논의사항을 요약합니다
3. 결과를 지정된 채널에 보고합니다

이렇게 하면 이 서브에이전트는 slack MCP 서버에만 접근 가능합니다. 불필요한 도구 접근을 차단하여 보안과 효율성을 높일 수 있습니다.

---
name: github-manager
description: GitHub 이슈/PR 관리 담당
mcpServers:
  - github
---
# GitHub 관리 에이전트

1. 열린 이슈를 확인합니다
2. PR 상태를 모니터링합니다
3. 리뷰 요청을 정리합니다

주의사항

보안

• .mcp.json에 토큰 직접 입력 금지: 이 파일은 Git에 올라갈 수 있습니다. 반드시 .env + ${VAR_NAME} 방식을 사용하세요.
• .env를 .gitignore에 추가: 토큰이 원격 저장소에 올라가면 즉시 무효화하고 재발급하세요.
• MCP 서버는 인터넷 접근 가능: 연결된 MCP 서버를 통해 외부 서비스에 데이터가 전송될 수 있습니다. 민감한 데이터를 다룰 때 주의하세요.

사내 정책

• MCP 서버 추가 전, 사내 보안 정책을 확인하세요. 특히 Slack, GitHub 등 회사 서비스 연결 시 관리자 승인이 필요할 수 있습니다.
• 외부 MCP 서버(커뮤니티 제작)는 코드를 확인한 후 사용하세요. 공식/Anthropic 제작 서버를 우선 사용하는 것을 권장합니다.

문제 해결

한 페이지 요약

MCP = Claude Code에 플러그인을 꽂는 표준 방식

설정 파일: .mcp.json (프로젝트 루트)
토큰 관리: .env + ${VAR_NAME} 참조
상태 확인: /mcp 명령어

자주 쓰는 서버: GitHub, Slack, Filesystem, Brave Search
도구 네이밍: mcp__서버명__도구명
핵심 주의: .mcp.json에 토큰 직접 입력 금지, .env는 .gitignore에 추가