[Claude Code]MCP 연동하기

1. 도입부: AI 에이전트의 한계를 넘는 '연결의 기술'

AI와 대화하며 코딩하다 보면 가장 번거로운 순간이 있다. 바로 다른 도구(Jira, GitHub, DB 등)에서 데이터를 복사해와서 Claude에게 붙여넣는 과정이다. 아무리 똑똑한 AI라도 외부 시스템의 현재 상태를 실시간으로 모를 때는 개발자의 손이 많이 갈 수밖에 없다.

이런 불편함을 해결하기 위해 등장한 표준이 바로 Model Context Protocol(MCP)이다. MCP는 Claude Code가 외부 데이터 소스나 API에 직접 접근할 수 있도록 돕는 일종의 '통합 인터페이스'다. 이를 연동하면 Claude는 단순히 텍스트를 읽는 수준을 넘어, 직접 이슈를 생성하고 데이터베이스를 쿼리하며 실시간 경고에 반응하는 진정한 에이전트로 거듭난다.

 

2. MCP의 핵심 로직과 워크플로우

MCP 서버가 연결되면 Claude Code는 더 이상 독립적인 채팅창이 아니다. 시스템 전체를 관통하는 조율자가 된다.

연동 후 달라지는 작업 흐름:

• 이슈 트래킹 자동화: "Jira 이슈 번호 #452를 분석해서 GitHub PR을 올려줘."
• 데이터 기반 의사결정: "Sentry 에러 로그를 분석하고 DB에서 해당 유저의 최근 활동을 조회해봐."
• 실시간 대응: Slack이나 Discord의 메시지, Webhook 이벤트에 Claude가 즉각 반응(Channels 기능).

 

3. 상세 가이드: MCP 서버 설치 및 관리

Claude Code에 서버를 추가하는 방법은 전송 방식에 따라 세 가지로 나뉜다.

① 전송 방식별 설치 옵션

방식	특징	주요 사용 사례
HTTP	원격 서버 연결을 위한 권장 옵션	클라우드 기반 서비스 (Notion, Stripe 등)
SSE	서버 전송 이벤트 방식 (현재는 권장되지 않음)	레거시 클라우드 연동
Stdio	로컬 프로세스로 실행	로컬 시스템 접근, 커스텀 스크립트 실행

실제 명령어 예시:

# Notion 연결 (HTTP)
claude mcp add --transport http notion [https://mcp.notion.com/mcp](https://mcp.notion.com/mcp)

# Airtable 연결 (Stdio)
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable -- npx -y airtable-mcp-server

 

② 관리 명령 한눈에 보기

연결된 서버들은 아래 명령어로 간편하게 관리할 수 있다.

• /mcp: Claude Code 내에서 실시간 상태 확인 및 인증 진행
• claude mcp list: 현재 구성된 모든 서버 목록 확인
• claude mcp remove <name>: 특정 서버 제거

 

4. MCP 설치 범위(Scope)와 계층 구조

설정을 어디에 저장하느냐에 따라 팀 공유 여부와 적용 프로젝트가 달라진다.

범위	저장 위치	팀 공유	비고
Local	~/.claude.json	아니오	현재 프로젝트에서만 사용 (비공개)
Project	.mcp.json	예 (Git 포함)	프로젝트 루트에 생성, 팀원과 공유
User	~/.claude.json	아니오	모든 프로젝트에서 공통으로 사용

 

5.  .mcp.json 환경 변수 확장

프로젝트 범위(.mcp.json)로 서버를 관리할 때 가장 큰 고민은 "팀원마다 설치 경로가 다르거나 API 키가 다를 경우"이다. 이를 해결하기 위해 Claude Code는 JSON 내에서 환경 변수 확장을 지원한다.

① 환경 변수 확장 구문

• ${VAR}: 현재 환경 변수 VAR의 값으로 치환된다.
• ${VAR:-default}: 변수가 설정되어 있지 않으면 default 값을 사용한다.

② 실제 활용 예시 JSON

팀원들이 각자의 환경에서 다른 API 엔드포인트나 키를 사용하더라도 하나의 설정 파일로 대응이 가능하다.

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-[https://api.example.com](https://api.example.com)}/mcp",
      "headers": {
        "Authorization": "Bearer ${API_KEY}"
      }
    }
  }
}

Tip: 필수 환경 변수가 설정되어 있지 않고 기본값도 없다면 Claude Code는 해당 구성을 로드하지 못하므로, 가급적 기본값을 설정해 두는 것이 안전하다.

 

6. 기업을 위한 관리 및 보안 정책

보안을 위해 MCP 서버 사용을 제어해야 할 때가 있다. Claude Code는 두 가지 옵션을 제공한다.

① managed-mcp.json을 통한 독점 제어

관리자가 승인한 서버만 로드하게 강제한다. 사용자의 claude mcp add 명령이 차단된다.

② 허용/거부 목록(Allow/Deny List)

완전 차단 대신 특정 조건에 맞는 서버만 허용하도록 유연하게 관리한다.6. 실무 팁 및 최적화 전략

 

🚀 Tool Search로 토큰 절약하기

수많은 MCP 서버를 연결하면 도구 정의만으로도 토큰이 낭비될 수 있다.

• 설정: ENABLE_TOOL_SEARCH=true (기본값)
• 핵심: 매번 쓰는 도구는 alwaysLoad: true로 설정해 검색 지연을 없앨 수 있다.

🔐 OAuth 인증 및 동적 헤더

원격 서버 연결 시 /mcp 명령어를 실행하면 브라우저를 통해 안전하게 인증을 마칠 수 있다.

 

7. 마무리: AI를 단순한 챗봇 이상으로 쓰는 법

Claude Code의 진정한 강력함은 코드를 잘 짜는 것뿐만 아니라, 개발자가 사용하는 수많은 도구와 '대화'할 수 있다는 데서 나온다. MCP는 그 대화의 통로다.

처음에는 설정이 조금 번거로울 수 있지만, 한 번 구축해두면 Claude가 다양한 작업을 자동으로 할 것이다.