개발자가 쓰는 AI 일기

클로드 코드(Claude Code)를 사용하다 보면 한 가지 답답한 순간이 옵니다. AI가 제 코드는 술술 읽고 수정해 주는데, 정작 깃허브(GitHub) 이슈는 제가 직접 복사해서 붙여 넣어야 하고, 데이터베이스 결과도 제가 직접 쿼리해서 가져다줘야 한다는 점입니다. "이거 한 번에 처리할 수 없을까?"라는 생각이 든다면, 바로 그 답이 **MCP(Model Context Protocol)**입니다.

이번 글에서는 MCP가 정확히 무엇이고, 클로드 코드에서 어떻게 활용하는지를 아주 쉬운 예제와 함께 풀어드립니다. 공식 문서를 기반으로 작성했기 때문에 안심하고 따라 하실 수 있습니다.

1. MCP란 무엇인가요?

**MCP(Model Context Protocol)**는 앤트로픽(Anthropic)이 2024년 11월에 공개한 오픈 소스 표준입니다. 한 줄로 정리하면 "AI 애플리케이션이 외부 도구·데이터와 소통하기 위한 공통 규격"입니다. 공식 사이트는 modelcontextprotocol.io에서 확인하실 수 있습니다.

쉬운 비유: USB-C 같은 존재

MCP를 가장 쉽게 이해하는 방법은 USB-C 포트를 떠올리는 것입니다.

USB-C가 등장하기 전에는 휴대폰마다 충전 단자가 다 달랐습니다. 삼성용 케이블, 애플용 케이블, 구형 안드로이드용 케이블을 따로따로 들고 다녔어야 했지요. 그런데 USB-C가 표준이 된 이후에는 케이블 하나로 거의 모든 기기를 연결할 수 있게 되었습니다.

MCP도 똑같은 역할을 합니다. 예전에는 AI를 깃허브에 연결하려면 깃허브 전용 통합 코드를 짜고, 슬랙(Slack)에 연결하려면 슬랙 전용 통합 코드를 또 짜야 했습니다. MCP가 등장한 이후에는 "MCP 서버"라는 표준 규격만 만들어 두면 어떤 AI 도구에서도 그 서버를 가져다 쓸 수 있게 되었습니다.

MCP가 해결하는 핵심 문제: M×N에서 M+N으로

조금 더 기술적인 시각에서 보면, MCP는 "M×N 문제"를 "M+N 문제"로 바꿔 줍니다.

AI 애플리케이션이 M개, 외부 도구가 N개 있을 때
MCP가 없으면: 각 조합마다 통합을 만들어야 하므로 M×N개의 연결 코드가 필요합니다
MCP가 있으면: 도구 제공자는 N개의 MCP 서버만 만들면 되고, AI 애플리케이션 개발자는 M개의 MCP 클라이언트만 만들면 되므로 결과적으로 M+N개의 통합으로 충분합니다

2. MCP의 구조: 3가지 핵심 구성 요소

MCP는 다음 3가지 구성 요소로 이루어져 있습니다. 식당에 비유하면 이해가 쉽습니다.

구성 요소	역할	식당 비유
MCP 호스트(Host)	사용자가 직접 사용하는 AI 애플리케이션	손님(여러분)
MCP 클라이언트(Client)	호스트 안에서 서버와의 연결을 관리	주문을 전달하는 종업원
MCP 서버(Server)	외부 도구·데이터를 노출하는 프로그램	음식을 만드는 주방

클로드 코드는 이 중 호스트 역할을 합니다. 여러분이 "깃허브에서 이슈 가져와 줘"라고 명령하면, 클로드 코드 안의 클라이언트가 깃허브 MCP 서버에 요청을 보내고, 서버가 실제로 깃허브 API를 호출해서 결과를 가져오는 식입니다.

MCP 서버가 제공하는 3가지 기능

MCP 서버는 다음 3가지 종류의 기능을 클라이언트에게 노출합니다.

도구(Tools): AI가 호출해서 어떤 작업을 수행하는 함수입니다. 예: "이슈 만들기", "데이터베이스에 쿼리하기"
리소스(Resources): AI가 읽어 들이는 데이터입니다. 예: 파일, 문서, API 응답
프롬프트(Prompts): 미리 정의된 명령 템플릿입니다. 예: "PR 리뷰 템플릿"

3. 클로드 코드에서 MCP가 작동하는 방식

클로드 코드 공식 문서에 따르면, 클로드 코드는 수백 개의 외부 도구·데이터 소스와 MCP를 통해 연결될 수 있습니다.

연결 후에는 자연어로 다음과 같은 명령을 내릴 수 있습니다.

이슈 트래커 연동: "JIRA의 ENG-4521 이슈를 구현하고 깃허브에 PR 만들어 줘."
모니터링 데이터 분석: "센트리(Sentry)에서 최근 24시간 동안 가장 자주 발생한 오류를 확인해 줘."
데이터베이스 쿼리: "이번 달 총 매출이 얼마야?"
워크플로 자동화: "지메일(Gmail)에서 이 사용자 10명에게 피드백 세션 초대 메일 초안을 만들어 줘."

복사·붙여 넣기 없이 한 번의 자연어 명령으로 외부 시스템과 직접 상호 작용할 수 있게 되는 것이 핵심입니다.

4. MCP 서버를 클로드 코드에 추가하는 3가지 방법

공식 문서는 MCP 서버 연결 방법을 3가지로 분류하고 있습니다.

방법 1: HTTP 원격 서버 (권장)

클라우드 기반 서비스에 가장 많이 쓰이는 방식입니다. 공식 문서에서도 원격 MCP 서버 연결 시 가장 권장하는 옵션입니다.

# 기본 문법
claude mcp add --transport http <이름> <URL>

# 노션(Notion) 연결 예시
claude mcp add --transport http notion https://mcp.notion.com/mcp

방법 2: SSE 원격 서버 (사용 비권장)

SSE(Server-Sent Events) 방식은 공식 문서에 따르면 현재 사용이 권장되지 않습니다(deprecated). 가능하면 HTTP 방식을 사용하시는 것이 좋습니다.

# 아사나(Asana) 연결 예시
claude mcp add --transport sse asana https://mcp.asana.com/sse

방법 3: stdio 로컬 서버

내 컴퓨터에서 직접 실행되는 프로세스 형태입니다. 시스템 접근이나 커스텀 스크립트가 필요할 때 적합합니다.

# 에어테이블(Airtable) 연결 예시
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

중요한 주의사항: 모든 옵션(--transport, --env, --scope, --header)은 반드시 서버 이름 앞에 와야 합니다. 그리고 --(이중 대시)로 서버 이름과 실행할 명령을 구분합니다.

5. 쉬운 예제로 배우는 MCP 활용

이제 가장 흔하게 사용되는 예제 3가지를 살펴보겠습니다. 모두 공식 문서에 수록된 내용입니다.

예제 1: 센트리(Sentry)로 오류 모니터링하기

운영 환경에서 발생하는 오류를 클로드 코드로 분석하는 시나리오입니다.

연결 명령:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

인증: 클로드 코드 안에서 다음 명령을 실행하면 브라우저에서 센트리 로그인 화면이 뜹니다.

/mcp

활용 예시:

"최근 24시간 동안 가장 자주 발생한 오류는 뭐야?"
"오류 ID abc123의 스택 트레이스 보여 줘."
"어떤 배포에서 이 새 오류들이 시작된 거야?"

이렇게 하면 센트리 대시보드를 직접 열지 않고도 클로드 코드 터미널에서 바로 디버깅을 진행할 수 있습니다. 센트리에 대해 더 알고 싶으신 분은 센트리 공식 사이트를 참고하세요.

예제 2: 깃허브 연동으로 코드 리뷰하기

깃허브의 원격 MCP 서버는 개인 액세스 토큰(Personal Access Token)으로 인증합니다.

준비 단계:

깃허브 토큰 설정 페이지로 이동합니다.
클로드가 작업할 저장소에 접근 권한을 가진 fine-grained 토큰을 새로 발급받습니다.

연결 명령:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ \
  --header "Authorization: Bearer YOUR_GITHUB_PAT"

활용 예시:

"PR #456을 리뷰하고 개선 사항을 제안해 줘."
"방금 발견한 버그에 대한 새 이슈를 만들어 줘."
"나에게 할당된 열린 PR을 모두 보여 줘."

예제 3: PostgreSQL 데이터베이스 쿼리하기

stdio 방식으로 로컬 데이터베이스에 연결하는 예시입니다.

연결 명령:

claude mcp add --transport stdio db -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

활용 예시:

"이번 달 총 매출이 얼마야?"
"orders 테이블의 스키마를 보여 줘."
"최근 90일 동안 구매가 없는 고객을 찾아 줘."

자연어로 질문하면 클로드가 알아서 SQL을 짜서 실행하고 결과를 정리해 줍니다. 보안을 위해 읽기 전용(readonly) 계정을 쓰는 것이 권장됩니다.

6. MCP 설치 범위(Scope): 3가지 중 무엇을 골라야 할까?

MCP 서버는 3가지 범위(scope) 중에서 골라 설치할 수 있습니다. 어느 프로젝트에서 보일지, 팀원과 공유할지를 결정하는 설정입니다.

범위	적용 범위	팀과 공유	저장 위치
로컬(Local)	현재 프로젝트만	아니요	`~/.claude.json`
프로젝트(Project)	현재 프로젝트만	예 (버전 관리 통해)	프로젝트 루트의 `.mcp.json`
사용자(User)	모든 프로젝트	아니요	`~/.claude.json`

어떤 범위를 골라야 할까요?

개인 실험용 서버: 로컬(local) — 기본값입니다
팀과 공유해야 하는 서버: 프로젝트(project) — .mcp.json 파일이 만들어지고, 이걸 깃에 커밋하면 팀원 모두가 같은 설정을 공유합니다
여러 프로젝트에서 자주 쓰는 개인용 서버: 사용자(user)

예를 들어 깃허브 서버를 팀과 공유하고 싶다면 다음과 같이 입력합니다.

claude mcp add --transport http github --scope project https://api.githubcopilot.com/mcp/

보안 팁: 프로젝트 범위로 설정된 .mcp.json 파일을 처음 사용할 때 클로드 코드는 사용자에게 승인 여부를 묻습니다. 신뢰할 수 있는 서버만 추가하시기 바랍니다.

7. 자주 쓰는 MCP 관리 명령

MCP 서버를 추가한 뒤에는 다음 명령으로 관리할 수 있습니다.

# 등록된 서버 목록 보기
claude mcp list

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

# 서버 제거
claude mcp remove github

클로드 코드 세션 안에서는 다음 명령으로 서버 상태를 실시간 확인할 수 있습니다.

/mcp

8. 클로드 코드를 MCP 서버로 사용하는 흥미로운 활용

공식 문서에는 잘 알려지지 않은 기능이 하나 더 있습니다. 클로드 코드 자체를 MCP 서버로 만들 수 있다는 점입니다.

claude mcp serve

이 명령을 실행하면 클로드 코드의 파일 편집·명령 실행 기능이 다른 MCP 클라이언트(예: 클로드 데스크톱, 커서, 윈드서프 등)에게 노출됩니다. 즉, 다른 AI 도구가 클로드 코드를 호출해서 작업을 위임할 수 있게 되는 것이지요. "AI가 AI를 부린다"는 흥미로운 구도입니다.

클로드 데스크톱에서는 다음과 같이 설정해서 사용할 수 있습니다.

{
  "mcpServers": {
    "claude-code": {
      "type": "stdio",
      "command": "claude",
      "args": ["mcp", "serve"],
      "env": {}
    }
  }
}

9. 실무에서 꼭 알아 두면 좋은 추가 기능

도구 검색(Tool Search): 컨텍스트 절약 기능

MCP 서버를 많이 추가할수록 클로드의 컨텍스트가 부담을 받는 것 아닐까 걱정될 수 있습니다. 하지만 클로드 코드에는 도구 검색(Tool Search) 기능이 기본으로 켜져 있어, 도구 정의를 미리 통째로 불러오는 대신 필요할 때마다 검색해서 가져옵니다. 즉, 서버를 많이 등록해도 컨텍스트 부담이 거의 늘지 않습니다.

출력 토큰 한도 관리

MCP 도구의 출력이 너무 길어지면 컨텍스트가 빠르게 소진됩니다. 이를 방지하기 위해 클로드 코드는 다음과 같이 처리합니다.

경고 임계치: 도구 출력이 10,000 토큰을 넘으면 경고가 표시됩니다
기본 최대치: 25,000 토큰
조정 방법: MAX_MCP_OUTPUT_TOKENS 환경 변수로 변경 가능

export MAX_MCP_OUTPUT_TOKENS=50000
claude

자동 재연결

HTTP나 SSE 서버가 세션 중간에 끊겼을 때 클로드 코드는 지수 백오프 방식으로 자동 재연결을 시도합니다. 1초 간격으로 시작해서 최대 5회까지 재시도하며, 그 후에는 실패로 표시됩니다. stdio 로컬 서버는 자동 재연결되지 않으므로 수동으로 다시 연결해야 합니다.

MCP 리소스 참조 (@ 멘션)

연결된 서버의 리소스를 파일처럼 참조할 수 있습니다. 프롬프트에서 @를 입력하면 자동 완성 메뉴가 뜨고, 다음과 같이 사용할 수 있습니다.

@github:issue://123 을 분석하고 수정안을 제안해 줘.

10. 보안 측면에서 반드시 알아야 할 점

클로드 코드 공식 문서는 타사(third party) MCP 서버 사용에 대해 명확한 경고를 합니다.

앤트로픽은 모든 MCP 서버의 정확성과 보안을 검증하지 않았습니다. 신뢰할 수 있는 MCP 서버만 설치하시기 바랍니다. 특히 신뢰할 수 없는 콘텐츠를 가져올 가능성이 있는 MCP 서버를 사용할 때는 프롬프트 인젝션(prompt injection) 위험에 노출될 수 있으니 각별히 주의해야 합니다.

또한 위키피디아의 MCP 항목에 따르면, 2025년 4월에 보안 연구자들은 MCP에 다음과 같은 보안 이슈가 존재한다는 분석을 발표했습니다.

프롬프트 인젝션
도구 권한이 결합되어 데이터를 빼낼 가능성
신뢰받는 도구를 조용히 대체할 수 있는 유사 도구(lookalike tools)

따라서 다음 사항을 권장합니다.

자격 증명은 절대 평문으로 저장하지 말고, ${ENV_VAR} 형태의 환경 변수 문법을 사용합니다 (공식 문서 권장)
데이터베이스 연결은 가능한 한 읽기 전용 계정을 사용합니다
검증되지 않은 출처의 MCP 서버는 설치하지 않습니다
깃허브 토큰은 fine-grained 토큰으로 발급해서 필요한 저장소에만 권한을 줍니다

11. 어디서부터 시작하면 좋을까요?

처음 MCP를 시작하시는 분께 다음 순서를 권장합니다.

클로드 코드 공식 문서 정독: 먼저 1차 자료를 차분히 읽어 보시기 바랍니다.
MCP 공식 사이트에서 프로토콜 자체를 학습: MCP의 철학과 구조를 이해하면 응용이 쉬워집니다.
간단한 서버 1~2개부터 연결: 처음부터 욕심내지 말고 깃허브 1개, 데이터베이스 1개 정도로 시작하세요.
공식 MCP 서버 모음 저장소: 앤트로픽이 관리하는 공식·커뮤니티 서버 목록을 둘러볼 수 있습니다.

마무리

MCP는 단순히 "AI에 도구를 붙이는 또 하나의 방법"이 아닙니다. AI 에이전트가 외부 시스템과 표준화된 방식으로 대화할 수 있게 만드는 인프라입니다. 클로드 코드는 그중에서도 가장 적극적으로 MCP를 받아들인 도구이며, 호스트와 서버 양쪽 역할을 모두 수행할 수 있는 흥미로운 설계를 가지고 있습니다.

처음에는 명령이 길어 보이고 설정이 복잡해 보일 수 있지만, 한 번 연결한 서버는 두고두고 시간을 절약해 줍니다. "복사·붙여 넣기"의 굴레에서 벗어나 진짜 자동화된 개발 흐름을 경험해 보시기 바랍니다.

이 글이 도움이 되셨다면 주변 개발자분들에게도 공유해 주세요. 다음 글에서는 직접 MCP 서버를 만들어 보는 방법을 다뤄 보겠습니다.

개발자가 쓰는 AI 일기

2026. 5. 2.

클로드 코드(Claude Code) MCP 완벽 가이드: 쉬운 예제로 배우는 외부 도구 연결법

1. MCP란 무엇인가요?

쉬운 비유: USB-C 같은 존재

MCP가 해결하는 핵심 문제: M×N에서 M+N으로

2. MCP의 구조: 3가지 핵심 구성 요소

MCP 서버가 제공하는 3가지 기능

3. 클로드 코드에서 MCP가 작동하는 방식

4. MCP 서버를 클로드 코드에 추가하는 3가지 방법

방법 1: HTTP 원격 서버 (권장)

방법 2: SSE 원격 서버 (사용 비권장)

방법 3: stdio 로컬 서버

5. 쉬운 예제로 배우는 MCP 활용

예제 1: 센트리(Sentry)로 오류 모니터링하기

예제 2: 깃허브 연동으로 코드 리뷰하기

예제 3: PostgreSQL 데이터베이스 쿼리하기

6. MCP 설치 범위(Scope): 3가지 중 무엇을 골라야 할까?

어떤 범위를 골라야 할까요?

7. 자주 쓰는 MCP 관리 명령

8. 클로드 코드를 MCP 서버로 사용하는 흥미로운 활용

9. 실무에서 꼭 알아 두면 좋은 추가 기능

도구 검색(Tool Search): 컨텍스트 절약 기능

출력 토큰 한도 관리

자동 재연결

MCP 리소스 참조 (@ 멘션)

10. 보안 측면에서 반드시 알아야 할 점

11. 어디서부터 시작하면 좋을까요?

마무리