MCP로 외부 도구 연결하기

Claude Code는 기본적으로 내 컴퓨터의 파일과 터미널만 다룹니다. GitHub 이슈를 읽거나 데이터베이스를 조회하거나 Slack에 글을 남기려면 그 시스템으로 통하는 문이 필요하고, 그 문의 표준 규격이 MCP(Model Context Protocol)입니다. 이 글은 MCP가 왜 생겼는지, 어떤 부품으로 이루어졌는지, claude mcp add로 어떻게 붙이고 어느 스코프에 저장하는지, 무엇을 붙이지 말아야 하는지를 다룹니다. 읽고 나면 서버 하나를 스스로 판단해 연결하고, 팀과 공유할지 혼자 쓸지 정할 수 있습니다.

「MCP와 확장」 코스의 첫 글입니다. 다음 글 「서브 에이전트로 작업 나누기」에서 연결한 도구를 별도 컨텍스트에서 돌리는 방법으로 이어집니다.

핵심 요약

• MCP는 AI 모델과 외부 도구를 잇는 오픈 표준입니다. 서버를 한 번 만들면 여러 클라이언트가 같은 서버를 씁니다.
• 서버는 내 컴퓨터에서 프로세스로 도는 로컬(stdio) 서버와 URL로 접속하는 리모트(HTTP) 서버로 나뉩니다. 공식 문서는 원격 연결에 HTTP를 권장하고 SSE는 더 이상 권장하지 않습니다.
• claude mcp add는 기본적으로 local 스코프(나만, 이 프로젝트만)에 저장합니다. 팀 공유는 --scope project(.mcp.json), 전 프로젝트는 --scope user입니다.
• 우리 6주차 원칙은 "설치해 보고 아는 게 아니라 README와 .env.example로 먼저 판단하고, 승인된 1개만 최소 권한 토큰으로 연결"입니다.

왜 표준이 필요했나

MCP가 없던 시절에는 도구마다 연동 코드를 따로 짰고, AI 도구를 바꾸면 연동을 처음부터 다시 만들어야 했습니다. MCP는 이 문제를 "서버는 한 번 만들고, 클라이언트는 한 번 구현한다"로 정리한 오픈 표준입니다. 서버가 도구 목록과 입력 형식을 표준 방식으로 알려 주면 어떤 클라이언트든 그 목록을 읽어 호출합니다.

우리 6주차 교재는 이 구조를 운전에 비유합니다. CLI는 운전대, LLM은 두뇌, MCP는 두뇌에 능력을 붙이는 내비게이션과 연료, 타이어입니다. 요청은 사용자 → CLI → LLM → MCP → 외부 도구 순서로 흐릅니다. 2주차에 "MCP는 아직 설치하지 마세요"라고 막아 둔 이유가 여기서 풀립니다. 골라 쓸 판단력이 생긴 뒤에 붙여야 힘이 됩니다.

MCP는 어떻게 구성되나

등장인물은 셋입니다. **호스트(클라이언트)**는 Claude Code처럼 모델을 돌리는 쪽으로, 서버에 연결해 도구 목록을 모델에게 보여 주고 모델이 호출을 결정하면 실행합니다. 서버는 "이슈를 검색한다", "SQL을 실행한다" 같은 기능을 도구 단위로 노출합니다. **전송(transport)**은 둘 사이의 통신 방식으로, 표준 입출력(stdio) 아니면 HTTP입니다.

서버가 제공하는 것은 세 종류입니다.

• 도구(tools): 모델이 호출하는 함수입니다. Claude Code 안에서는 mcp__<서버이름>__<도구이름> 이름으로 나타나고, 권한 규칙이나 서브에이전트의 tools 필드에서 이 이름을 그대로 씁니다.
• 리소스(resources): 파일처럼 참조하는 데이터입니다. 프롬프트에서 @서버이름:프로토콜://경로로 언급하면 자동으로 가져와 첨부됩니다.
• 프롬프트(prompts): 서버가 미리 정의한 명령으로, /mcp__서버이름__프롬프트이름 슬래시 명령이 됩니다.

로컬 서버와 리모트 서버의 차이

전송은 HTTP가 원격 권장 방식이고, SSE는 공식 문서에 "더 이상 사용되지 않음" 경고가 붙어 있으며, stdio는 로컬 전용입니다.

로컬 서버의 첫 실행은 npx가 패키지를 내려받느라 느릴 수 있어 claude mcp list가 잠시 ✗ Failed to connect를 보여 주기도 합니다. 시작 제한을 늘리려면 MCP_TIMEOUT을 밀리초로 지정합니다(macOS는 MCP_TIMEOUT=60000 claude, Windows PowerShell은 $env:MCP_TIMEOUT = "60000"; claude).

MCP로 무엇을 할 수 있나

1. 데이터베이스 직접 접근

읽기 전용 계정으로 DB 서버를 붙이면 "이번 달 신규 고객 수를 세어 줘"처럼 자연어로 질의하고 스키마를 읽어 마이그레이션 초안을 잡게 할 수 있습니다. 우리 과정은 여기에 서버 3단계 원칙을 겹칩니다. 운영 DB는 성역입니다. 연결하더라도 읽기 전용 계정, 그것도 개발 DB부터입니다.

2. GitHub 연동

GitHub 원격 서버는 세분화된 개인 액세스 토큰(PAT)을 헤더로 넘겨 인증합니다. "PR 456을 검토해 줘", "방금 찾은 버그로 이슈를 만들어 줘"가 됩니다. 다만 gh CLI가 있으면 MCP 없이도 같은 일을 터미널 명령으로 합니다(FAQ 참고).

3. 커뮤니케이션 도구 연동

Slack, Notion 같은 서비스는 리모트 서버를 제공하고 OAuth로 로그인합니다. 회의록을 읽어 할 일을 뽑거나 작업 완료를 채널에 알리는 흐름이 가능합니다.

4. 브라우저 자동 조작

Playwright MCP 서버를 로컬로 붙이면 Claude가 실제 브라우저를 열어 이동하고 클릭하고 화면을 읽습니다. 계정이 필요 없어 첫 로컬 서버 실습에 적합합니다. 우리는 사이트 작업 뒤 모바일 잘림을 이 경로로 실측합니다. 캡처를 눈으로 보는 대신 scrollWidth를 숫자로 비교하는 것이 "정지 규칙은 증거"의 실제 모습입니다.

5. 최신 문서 취득

모델의 학습 데이터는 오래됩니다. 라이브러리 공식 문서를 그때그때 가져오는 서버를 붙이면 없는 API를 지어내는 일이 줄어듭니다. 이 코스 마지막 글 「Context7 MCP로 시작하는 첫 MCP 서버」가 이 용도입니다.

서버를 연결하는 방법

명령은 claude 세션 안이 아니라 터미널에서 실행합니다.

# 리모트 HTTP 서버 (권장)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 토큰을 헤더로 넘기는 리모트 서버
claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

# 로컬 stdio 서버: -- 뒤가 실제 실행 명령
claude mcp add playwright -- npx -y @playwright/mcp@latest

# 환경 변수를 서버에 넘기는 로컬 서버
claude mcp add --env AIRTABLE_API_KEY=YOUR_KEY --transport stdio airtable \
  -- npx -y airtable-mcp-server

--(이중 대시)가 중요합니다. 앞은 Claude Code의 옵션(--transport, --env, --scope), 뒤는 서버를 띄우는 명령과 인수입니다. 빼먹으면 서버 쪽 플래그를 Claude Code가 자기 옵션으로 해석하려다 실패합니다. --env 바로 뒤에 서버 이름이 오면 이름을 또 하나의 KEY=value로 읽고 거부하니, 위 예처럼 사이에 다른 옵션을 하나 둡니다.

claude mcp list          # ✓ Connected / ! Needs authentication / ✗ Failed to connect / ⏸ Pending approval
claude mcp get github    # 서버 상세와 저장된 스코프
claude mcp remove github # 제거 (여러 스코프에 있으면 --scope 지정)

세션 안에서는 /mcp로 같은 목록을 보고 재연결, 인증, 프로젝트 서버 승인을 처리합니다. claude mcp add는 Windows PowerShell과 명령 프롬프트에서도 동일하게 동작하며, 설정 파일 ~/.claude.json은 Windows에서 %USERPROFILE%\.claude.json입니다.

스코프는 어떻게 고르나

기준은 두 질문입니다. "다른 프로젝트에서도 쓰나?"가 예이면 user, "팀원도 같은 서버가 필요한가?"가 예이면 project, 둘 다 아니면 local입니다. 개인 실험이나 자격 증명이 섞인 서버는 local이 안전합니다.

project 스코프는 .mcp.json에 기록되어 커밋됩니다. 복제한 팀원이 세션을 시작하면 승인 프롬프트가 뜨는데, 남이 올린 저장소가 동의 없이 내 컴퓨터에서 프로세스를 띄우지 못하게 막는 장치입니다. 거부했다가 다시 검토하려면 claude mcp reset-project-choices로 초기화합니다.

.mcp.json은 ${VAR}와 ${VAR:-기본값} 확장을 지원하므로 "Authorization": "Bearer ${API_KEY}"처럼 적어 토큰 값을 파일에 남기지 않고 공유할 수 있습니다. 같은 이름이 여러 스코프에 있으면 local → project → user → 플러그인 → claude.ai 커넥터 순으로 우선하고, 항목은 병합되지 않습니다. 스코프는 추가 시점에 고정되므로 바꾸려면 제거 후 다시 추가합니다.

인증과 토큰 관리

리모트 서버는 대개 OAuth 2.0을 씁니다. 서버가 401이나 403을 돌려주면 "인증 필요"로 표시되고, /mcp → 서버 선택 → Authenticate를 고르면 브라우저 로그인이 열립니다. 토큰은 안전하게 저장되어 자동 갱신되며, 셸에서는 claude mcp login <이름>과 claude mcp logout <이름>을 씁니다.

토큰을 다루는 원칙은 6주차 교재 그대로, README의 환경 변수에서 키의 종류를 먼저 가릅니다.

• 계정 인증용 토큰(GITHUB_TOKEN, NOTION_API_KEY, SLACK_BOT_TOKEN 등): 서비스 계정만 있으면 되고 내 플랜과 권한만 영향을 줍니다.
• 사용량 기반 API 키(OPENAI_API_KEY, PERPLEXITY_API_KEY, FIRECRAWL_API_KEY 등): 서버 코드가 무료여도 호출마다 실비용이 붙을 수 있습니다.

질문은 "이 MCP가 무료냐"가 아니라 "이 MCP가 연결하는 서비스까지 무료냐"입니다. 어떤 토큰이든 최소 권한으로 발급하고, .mcp.json에는 ${VAR}만 적고 실제 값은 로컬 셸 환경에 둡니다.

도구를 너무 많이 붙이면 어떻게 되나

연결된 서버마다 도구 이름과 서버 지침이 모든 세션에 로드되어 컨텍스트를 차지합니다. Claude Code는 서버당 도구 수를 제한하지 않지만 실질 한계는 컨텍스트 예산이고, 기본값인 Tool Search가 도구 정의를 필요할 때만 불러와도 남는 비용이 있습니다.

• 도구 출력이 10,000토큰을 넘으면 경고가 뜨고 기본 상한은 25,000토큰입니다. MAX_MCP_OUTPUT_TOKENS로 올릴 수 있지만 그만큼 대화 컨텍스트가 줄어듭니다.
• 비슷한 도구가 여러 서버에 있으면 엉뚱한 도구를 고를 확률이 올라갑니다.
• 안 쓰는 서버는 시작 시 연결 시도와 실패 보고만 늘립니다.

6주차 실습을 "승인된 1개만 연결"로 잡는 이유입니다. 우리 운영도 실제 호출하는 MCP만 켭니다. 주기적으로 이렇게 물으세요. "지금 연결된 MCP 목록을 보여 주고, 최근 안 쓰는 것이 있으면 알려 줘. 정리 전에 목록부터."

직접 만들 때 지킬 것

자체 서버는 공식 MCP 서버 가이드(modelcontextprotocol.io)를 기준으로 만들되, Claude Code 문서가 명시하는 세 가지를 지킵니다.

1. 서버 지침은 짧고 앞이 무겁게: 서버 지침은 "언제 이 서버의 도구를 찾을지"의 근거이며, 도구 설명과 서버 지침은 각각 2KB에서 잘립니다.
2. 큰 출력은 페이지로 나누거나 선언: 전체 스키마처럼 큰 결과는 _meta["anthropic/maxResultSizeChars"]로 상한을 선언할 수 있습니다(최대 500,000자).
3. 프롬프트 주입을 전제: 외부 콘텐츠 안의 지시문이 모델에게 명령처럼 보일 수 있으니 데이터는 데이터로만 전달합니다.

정리

• MCP는 도구 연동을 표준화한 규약이며 claude mcp add 한 줄로 서버를 붙입니다.
• 원격은 HTTP, 로컬은 stdio입니다. 로컬 서버는 -- 뒤에 실행 명령을 적습니다.
• 스코프는 기본 local, 팀 공유는 project(.mcp.json), 전 프로젝트는 user입니다.
• 인증은 OAuth(/mcp) 또는 헤더 토큰이며, 토큰은 최소 권한과 환경 변수로 다룹니다.
• 붙이기 전에 README와 .env.example로 비용을 판단하고 필요한 것 하나만 연결합니다.

자주 묻는 질문