책에 포함된 노트Claude Code 실전 활용법: 설치부터 자동화·MCP·운영까지

MCP로 외부 도구 연결: GitHub·DB·브라우저·Slack·Figma

2026-03-22Views 24약 11분

MCP는 왜 '업무 자동화 허브'인가

Claude Code를 단순히 "코드를 잘 써주는 도구"로만 쓰면, 생산성의 상한은 결국 에디터 안에서의 변경에 머뭅니다. 반면 MCP(Model Context Protocol)를 붙이면 Claude Code는 코드 변경을 넘어 업무의 앞뒤를 끊김 없이 이어주는 허브가 됩니다. 이슈 트래커에서 티켓을 읽고, 디자인을 확인하고, DB에서 실제 데이터를 조회하고, 브라우저로 재현 테스트를 돌린 뒤, PR을 만들고 Slack에 보고하는 일련의 흐름이 한 세션에서 이어집니다.¹

MCP는 호스트(Claude Code 같은 앱)와 서버(각 외부 시스템 커넥터)가 표준 규격으로 연결되는 클라이언트–서버 구조입니다. 호스트는 서버가 제공하는 도구(tools)·리소스(resources)·프롬프트(prompts)를 목록으로 발견(list) 하고, 필요한 순간에 호출(call)합니다.² 이 구조 덕분에 "GitHub용 플러그인", "DB용 플러그인"처럼 제각각이던 연결 방식이 하나의 프로토콜로 정리됩니다.³

이 장의 목표는 두 가지입니다.

첫째, MCP 서버를 어디에(어떤 스코프에) 추가할지를 설계해 팀과 개인의 설정이 충돌하지 않게 만드는 것입니다.

둘째, GitHub·DB·브라우저·Slack·Figma를 연결했을 때 가장 값이 크게 나오는 티켓 → 구현 → 보고 시나리오를, 실제 세션 흐름으로 구성하는 것입니다.

Claude Code에서 MCP 서버 추가하기: 설치보다 '설계'가 먼저다

Claude Code는 MCP 서버를 세 가지 방식(원격 HTTP, 원격 SSE, 로컬 stdio)으로 추가할 수 있습니다.¹ 요즘의 실무 감각으로 정리하면 다음처럼 이해하면 쉽습니다.

로컬에서 직접 실행해야 하는 도구(예: 로컬 DB 터널링, 사내 스크립트, 로컬 브라우저 자동화)는 stdio가 자연스럽고, SaaS(예: Slack, Sentry 등)처럼 원격 서비스는 HTTP가 기본 선택입니다.²

서버 추가 기본 명령

원격 HTTP 서버는 다음 형태로 추가합니다.¹

claude mcp add --transport http <name> <url>

로컬 stdio 서버는 Claude Code 옵션과 실제 실행 커맨드를 --로 구분합니다.¹

claude mcp add [options] <name> -- <command> [args...]

서버를 붙인 다음에는 claude mcp list/get/remove로 관리하고, Claude Code 안에서는 /mcp로 연결 상태와 인증 플로우를 확인합니다.¹

스코프 3종(user/local/project) — "어디에 저장할 것인가"가 운영을 결정한다

MCP를 처음 도입할 때 가장 흔한 실패는 "서버를 많이 붙였는데, 팀원이 재현을 못 한다" 혹은 "민감한 토큰이 레포에 섞였다"입니다. 이 둘은 거의 항상 스코프를 설계하지 않고 추가했기 때문입니다.

Claude Code는 MCP 서버 설정을 세 스코프에 저장합니다.¹

Local 스코프: 개인 + 특정 프로젝트 한정(기본값)

Local 스코프는 기본값이며, ~/.claude.json의 "현재 프로젝트 경로 아래"에 저장됩니다.¹ 즉, 내 컴퓨터의 이 레포에서만 작동하고 다른 레포에서는 보이지 않습니다.

이 스코프는 "실험"과 "비공개 자격증명"에 적합합니다. 예를 들어 DB 접근 토큰이 개인마다 다르거나, 아직 팀 합의가 끝나지 않은 커넥터를 시험할 때 local로 붙입니다.

# 기본이 local
claude mcp add --transport http stripe https://mcp.stripe.com

# 명시적으로 local
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

Project 스코프: 팀 공유(레포에 커밋되는 .mcp.json)

Project 스코프는 레포 루트의 .mcp.json에 저장되며, 버전관리 대상으로 설계되어 있습니다.¹ 팀이 같은 서버 이름과 동일한 도구 집합을 공유할 수 있다는 점이 핵심입니다.

claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

Project 스코프 서버는 보안상 처음 사용 시 승인 프롬프트가 뜹니다. 승인 선택을 초기화하려면 claude mcp reset-project-choices를 사용합니다.¹

여기서 중요한 원칙은 하나입니다.

"프로젝트 스코프에는 '공유 가능한 구조'만, 비밀은 넣지 않는다."

이를 가능하게 해주는 장치가 .mcp.json의 환경 변수 확장입니다. ${VAR} 또는 ${VAR:-default} 형태로 URL, 헤더, 커맨드, 인자, env를 치환할 수 있습니다.¹

{
  "mcpServers": {
    "slack": {
      "type": "http",
      "url": "${SLACK_MCP_URL:-https://mcp.slack.com/mcp}"
    },
    "db": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--dsn", "${DB_DSN}"]
    }
  }
}

이렇게 해두면 .mcp.json은 커밋해도 안전하고, 실제 토큰/DSN은 각 개발자가 로컬 환경 변수로 주입합니다.

User 스코프: 개인 공용 도구(모든 프로젝트에서 사용)

User 스코프는 ~/.claude.json에 저장되며, 내 모든 프로젝트에서 쓸 수 있습니다.¹ 예를 들어 "개인 메모/문서", "개인용 리서치", "내가 관리하는 공통 GitHub 자동화" 같은 도구가 여기에 어울립니다.

claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

충돌 해결 규칙(우선순위)

같은 이름의 서버가 여러 스코프에 존재할 때, Claude Code는 local → project → user 순으로 우선합니다.¹ 이 규칙이 팀 운영의 안전장치가 됩니다.

예를 들어 팀이 .mcp.json에 github 서버를 정의해두고, 내 로컬에서는 실험용 GitHub 엔드포인트나 다른 토큰을 쓰고 싶다면 local에 같은 이름으로 덮어쓸 수 있습니다. "팀 표준"은 유지하되, 개인 실험은 깨지지 않습니다.

스코프 설계 패턴: "이름은 고정, 비밀은 분리, 변경은 단계적으로"

스코프를 단순한 저장 위치로만 보면 반쪽짜리입니다. 실전에서는 서버 이름, 권한 리스크, 팀 공유 범위를 함께 설계해야 합니다.

패턴 1) 서버 이름을 '업무 언어'로 표준화한다

MCP 세계에서 서버 이름은 곧 "어떤 도구 상자"인지에 대한 힌트입니다. LLM은 도구를 문서처럼 읽고 추론하므로, 이름과 설명이 명확할수록 도구 선택 정확도가 올라갑니다.⁴

팀에서 자주 쓰는 조합은 다음처럼 "대상+의도"로 고정하는 방식이 안전합니다.

github: 레포/이슈/PR 표준 작업
db_ro: 운영 DB 읽기 전용(가능하면)
browser: 브라우저 재현/스크린샷/E2E
slack: 공지/보고/컨텍스트 수집
figma: 디자인 스펙/토큰/컴포넌트 추출

이때 중요한 건 "이름이 길지 않게"가 아니라 "의도가 섞이지 않게"입니다. MCP 서버는 전통 API와 달리 LLM이 설명을 읽고 선택하는 구조라서, 명확성·결정성·일관성이 특히 중요합니다.⁴

패턴 2) 읽기 전용과 변경(쓰기)을 분리한다

Block의 MCP 설계 경험에서는, 사용자가 권한 승인 결정을 하기 쉽도록 도구를 리스크 레벨(읽기/쓰기) 로 분리하는 것이 유리하다고 말합니다.⁵ 이는 Claude Code의 권한 모델(도구 호출 단위 승인)과도 잘 맞습니다.

가장 실용적인 분리는 이런 형태입니다.

db_ro (read-only): 조회, 스키마 확인, 샘플 데이터
db_rw (write): 마이그레이션, 데이터 수정, 배치 실행

Slack도 마찬가지입니다. "검색/읽기"와 "메시지 발송"은 사고의 비용이 다르므로, 가능하면 도구/스코프 또는 설정으로 분리해 두는 편이 운영이 편합니다.⁵

패턴 3) project 스코프는 '골격', local/user는 '자격증명과 취향'

실전 팀 세팅의 권장 구조는 다음과 같습니다.

project: 서버 이름, URL/command, 공통 헤더 키(변수로), 안전한 기본 제한(예: read-only 모드)
local: 개인별 토큰, 실험 서버, 개발 중인 사내 MCP
user: 프로젝트와 무관한 개인 도구(문서, 리서치, 개인 업무)

이 구조로 가면 "설정 공유"와 "비밀 분리"가 동시에 됩니다. 그리고 신규 팀원이 왔을 때는 레포를 클론하고 환경 변수만 넣으면 .mcp.json을 통해 동일한 도구 구성이 맞춰집니다.

도구가 늘어날수록 생기는 문제: 컨텍스트·출력·도구 선택

MCP를 붙이다 보면 어느 순간 "되게 강해졌는데, 세션이 무거워졌다"를 체감합니다. 이는 자연스러운 부작용입니다. 도구 정의(스키마/설명)가 컨텍스트를 차지하고, 어떤 도구는 출력이 큰 덩어리로 튀어나오기 때문입니다.

1) MCP Tool Search로 '필요한 도구만' 늦게 불러오기

Claude Code에는 MCP Tool Search가 있어, 많은 MCP 서버를 연결했을 때 도구 정의를 미리 다 넣지 않고 필요할 때 검색해 로딩합니다.¹ 기본적으로 도구 정의가 컨텍스트의 10%를 넘으면 자동 활성화되며, ENABLE_TOOL_SEARCH로 조정할 수 있습니다.¹

2) MCP 출력 한도: 큰 결과는 "경고 + 제한"이 기본

DB 조회나 로그 분석을 MCP로 하면 출력이 급격히 커질 수 있습니다. Claude Code는 MCP 출력이 10,000 토큰을 넘으면 경고를 표시하고, 기본 최대 출력 한도를 25,000 토큰으로 둡니다. 필요하면 MAX_MCP_OUTPUT_TOKENS로 조정합니다.¹

이 값은 무작정 올리기보다, "출력이 큰 도구는 페이지네이션/요약/필터를 먼저 제공"하는 쪽이 안전합니다. 실제 MCP 서버 설계 베스트 프랙티스에서도 실패를 정상으로 보고, 복구 가능한 오류/제한/페이지네이션을 명시하라고 권합니다.⁶

실전 시나리오: 티켓 → 구현 → 보고 (하나의 세션으로 끝내기)

이제 연결된 MCP가 실제로 어떻게 "허브"가 되는지, 가장 흔한 업무 흐름으로 묶어보겠습니다.

가정: 여러분은 GitHub 이슈로 들어온 버그/기능 티켓을 처리해야 합니다. 이슈에는 Figma 링크가 있고, 재현은 브라우저에서만 가능하며, 원인 분석에는 DB 데이터가 필요합니다. 완료 후에는 PR을 만들고 Slack에 보고해야 합니다.

0) 준비: 필요한 MCP 서버를 '최소 세트'로 켠다

처음부터 많은 서버를 켜기보다, 이 시나리오의 최소 세트를 다음처럼 잡습니다.

GitHub: 이슈 읽기, 브랜치/PR 생성, 리뷰 요청
Figma: 디자인 스펙/토큰 확인(혹은 컴포넌트 추출)
DB: 스키마/데이터 조회(가능하면 read-only)
브라우저(Playwright/Puppeteer 등): 재현, 스크린샷, E2E 테스트
Slack: 진행 공유, 결과 보고

MCP 서버는 "많을수록 강하다"가 아니라 "업무 루프를 닫을 수 있을 만큼이면 충분하다"가 기준입니다.⁴

1) 티켓 수집: GitHub 이슈를 '작업 단위'로 변환

Claude Code에게 이렇게 지시합니다.

"GitHub 이슈 #123을 읽고, (1) 문제 요약, (2) 재현 조건, (3) 수락 기준(AC), (4) 변경 파일 후보, (5) 테스트 전략을 정리해줘. 모호한 부분은 질문 리스트로 뽑아줘."

여기서 핵심은 이슈 원문을 그대로 붙여 넣지 않아도 된다는 점입니다. GitHub MCP가 이슈/코멘트를 읽어 오고, Claude는 그걸 기반으로 계획을 세웁니다.¹

이 단계의 산출물은 "코딩 지시서"가 아니라 "검증 가능한 작업 정의"여야 합니다. 즉, AC와 테스트 방법이 같이 나와야 다음 단계가 매끄럽습니다.

2) 디자인 동기화: Figma 링크를 '구현 스펙'으로 바꾼다

이슈 본문에 Figma 링크(컴포넌트/프레임)가 있다면, Claude에게 "이 링크에서 변경된 UI 요소(간격, 색상, 타이포, 반응형 조건)를 요약하고, 현재 코드베이스의 컴포넌트 구조와 매핑해 달라"고 시킵니다.

Figma MCP를 붙이면 디자인을 눈으로 보고 옮기는 시간이 줄어듭니다. 실제 엔터프라이즈 사례에서도 Figma MCP로 디자인 스펙을 추출하고 TypeScript 컴포넌트까지 이어붙이는 흐름이 대표적인 '다중 서버 워크플로'로 소개됩니다.⁷

이 단계에서 중요한 습관은 하나입니다.

"디자인 스펙을 '코드 규칙'으로 변환해 CLAUDE.md나 PR 설명에 남긴다."

그래야 다음 리뷰/수정 때 디자인 재확인이 반복되지 않습니다.

3) 데이터 근거 확보: DB에서 '가설을 검증'한다

버그/기능은 대개 데이터와 연결됩니다. 예컨대 "특정 상태의 주문만 화면에서 깨진다" 같은 유형이죠.

이때 DB MCP는 "SQL을 대신 써주는 도구"라기보다, 가설 검증 엔진으로 씁니다.

어떤 레코드가 문제 조건을 만족하는지
스키마 제약(Nullable, enum 성격, 인덱스)이 무엇인지
운영 데이터 분포가 가정과 맞는지

다만 출력이 너무 커지지 않게, 처음에는 표본을 작게(예: 10개) 가져오고 조건을 좁혀야 합니다. 큰 결과는 컨텍스트를 잡아먹고, 다음 추론을 둔하게 만듭니다.¹

4) 재현과 보호막: 브라우저로 '실패를 캡처'하고 E2E를 남긴다

브라우저 자동화 MCP(Playwright/Puppeteer 계열)는 두 가지에 특히 유리합니다.

첫째, "내 로컬에서는 되는데"를 줄입니다. 실패 화면, 네트워크 요청, 콘솔 에러를 자동으로 수집할 수 있기 때문입니다.

둘째, 고친 뒤에 다시 깨지지 않게 회귀 테스트(E2E) 를 남기기 좋습니다.

Claude에게는 이렇게 지시합니다.

"브라우저에서 재현 절차를 자동화해 스크린샷과 콘솔 로그를 남겨줘. 원인이 UI인지 API인지 가설을 2개로 좁히고, 각 가설을 반증할 관찰 포인트를 정의해줘. 수정 후에는 동일 시나리오를 E2E 테스트로 추가해줘."

이렇게 하면 '재현 → 수정 → 재현 확인'이 아니라, '재현 → 증거 확보 → 수정 → 자동 검증'으로 루프가 바뀝니다.

5) 구현: 코드 변경은 "작게, 검증 가능하게"

이 장의 초점은 MCP이지만, 여기서도 원칙은 같습니다.

변경은 작은 커밋 단위로
테스트(단위/통합/E2E) 중 최소 1개는 반드시 같이
PR 설명에 "왜(원인) / 무엇(변경) / 어떻게 검증(재현·테스트)"를 포함

MCP가 강해질수록 더 중요한 건 "Claude에게 많은 일을 맡기는 것"이 아니라 검증 가능한 단위로 쪼개 위임하는 것입니다.

6) PR 생성: GitHub에 "이슈→코드→테스트"를 연결해 올린다

GitHub MCP를 통해 PR을 만들 때는, Claude에게 다음을 한 번에 요구하는 게 효율이 좋습니다.

이슈 링크/키워드 자동 연결
변경 요약(파일/영향 범위)
테스트 결과(로컬/CI, E2E 포함)
위험 요소와 롤백 포인트

즉 "PR 텍스트 작성"이 아니라 "리뷰어가 필요한 정보 패키징"을 시킵니다.

7) 보고: Slack에 '완료 메시지'가 아니라 '의사결정 가능한 요약'을 남긴다

Slack MCP는 검색/요약에도 좋지만, 보고의 품질을 올릴 때 특히 빛납니다. Slack의 공식 MCP 서버는 Streamable HTTP(JSON-RPC 2.0)로 제공되며, 엔드포인트는 https://mcp.slack.com/mcp입니다.⁸ 또한 OAuth 스코프에 따라 검색·메시지 발송·채널/스레드 읽기·캔버스 작업 등 기능이 달라집니다.⁸

보고 메시지는 "PR 링크만 던지기"보다 다음 4요소가 있으면 팀이 바로 움직일 수 있습니다.

무엇이 문제였는지(증상)
왜 생겼는지(원인)
무엇을 바꿨는지(해결)
어떻게 확인하는지(검증)

Claude에게는 이렇게 시킵니다.

"#dev-frontend 채널에 올릴 업데이트 초안을 작성해줘. PR 링크, 영향 범위, 재현/검증 방법, 배포 시 주의점(있다면)을 포함하고, 8줄 이내로 간결하게."

여기까지 오면, 여러분은 코드를 수정했을 뿐 아니라 티켓의 생애주기 전체(이슈→설계→데이터→재현→수정→검증→공유)를 한 세션에서 닫은 것입니다.

MCP 서버를 '팀의 자산'으로 만드는 운영 팁

워크플로에서 거꾸로 설계하라

MCP 서버를 API 엔드포인트처럼 "기능 나열"로 만들면 LLM이 헤매기 쉽습니다. 실제로 여러 팀의 베스트 프랙티스는 공통적으로 "API에서 시작하지 말고, 자동화할 워크플로에서 시작하라"고 강조합니다.⁴⁵

즉 "이슈 만들기/라벨 붙이기/담당자 지정하기" 같은 저수준 도구 3개를 두기보다, "이슈를 표준 템플릿으로 생성한다" 같은 작업 단위 도구가 더 잘 작동합니다.⁵

한 서버는 한 도메인(단일 책임)으로 쪼개라

MCP 서버 개발/운영 가이드에서는 단일 책임 원칙을 강조합니다. DB·파일·외부 API·이메일을 한 서버에 다 넣은 '메가 서버'는 유지보수도 어렵고, 권한 설계도 복잡해집니다.⁶

팀 관점에서는 특히 "도메인 경계"가 곧 "권한 경계"가 됩니다.

서버(혹은 도구)는 5~8개 수준에서 시작하라

MCP 서버를 LLM이 읽는 제품으로 보고, 과도한 도구 수를 경고합니다. 시작은 3~5개 핵심 도구, 전체도 5~8개 정도가 적절하다는 권고가 있습니다.⁴

이는 Claude Code에서도 동일합니다. 도구가 많아질수록 컨텍스트 비용과 선택 오류 가능성이 함께 증가합니다. Tool Search가 있더라도, "처음 설계"는 가벼울수록 좋습니다.¹

다음 장을 위한 연결 고리

이 장에서 MCP는 Claude Code를 "코딩"에서 "업무 자동화"로 확장하는 관문이었습니다. 다음 장에서는 여기서 만든 연결을 더 실전적으로 활용하기 위해, IDE/브라우저/원격 세션을 함께 묶어 멀티 디바이스·원격 작업·UI 검증 루프를 안정적으로 돌리는 방법으로 이어가겠습니다.

참고

¹Connect Claude Code to tools via MCP

²Architecture overview - Model Context Protocol

³Introducing the Model Context Protocol

⁴MCP server design best practices | Workato Docs

⁵Block's Playbook for Designing MCP Servers

⁶MCP Best Practices: Architecture & Implementation Guide

⁷MCP in Action: Workflow Transformations

⁸Overview | Slack Developer Docs (Slack MCP server)

책 목록

Claude Code 실전 활용법: 설치부터 자동화·MCP·운영까지

전체 목차 보기