MCP: Claude Code를 도구에 연결하기

Claude Code는 파일을 읽고, 코드를 작성하고, 명령어를 실행할 수 있습니다. 하지만 한 가지 한계가 있습니다. 기본적으로 로컬 파일 시스템 밖에 있는 것은 볼 수 없습니다. MCP가 이 문제를 해결합니다. MCP는 Claude Code가 터미널을 떠나지 않고도 데이터베이스, GitHub, Notion 또는 다른 외부 도구와 통신할 수 있게 해주는 메커니즘입니다.

MCP란 무엇인가요?

MCP (Model Context Protocol)는 Anthropic이 만들고 커뮤니티가 채택한 표준화된 오픈소스 프로토콜입니다. 역할은 AI 에이전트(클라이언트)와 외부 도구(서버) 사이의 공통 언어를 정의하는 것입니다.

범용 커넥터라고 생각하면 됩니다. MCP 이전에는 AI와 도구 간의 각 통합이 맞춤 제작된 독점 케이블이었습니다. MCP와 함께라면, 어떤 도구도 구현할 수 있는 단일 포트가 됩니다.

구체적으로, MCP 서버는 세 가지 유형의 프리미티브를 노출합니다.

• Tools : Claude가 호출할 수 있는 함수 (SQL 쿼리, 파일 읽기, API 호출).
• Resources : Claude가 읽을 수 있는 컨텍스트 데이터 (데이터베이스 스키마, 원격 파일 내용).
• Prompts : 상호작용을 구조화하기 위한 재사용 가능한 템플릿.

Claude Code는 MCP 클라이언트 역할을 합니다. 사용 가능한 도구를 발견하고, 모델에 노출하며, 해당 서버로 호출을 전달합니다.

claude mcp add로 MCP 서버 추가하기

Claude Code는 MCP 서버를 연결하기 위한 전용 명령어를 제공합니다. 두 가지 주요 모드가 있습니다. 원격 서버(HTTP)와 로컬 서버(stdio)입니다.

원격 서버 (HTTP)

대부분의 주요 서비스는 현재 호스팅된 MCP 엔드포인트를 제공합니다. 예를 들어 Notion의 경우:

$claude mcp add --transport http notion https://mcp.notion.com/mcp

또는 GitHub (인증 토큰 포함):

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

로컬 서버 (stdio)

일부 서버는 Claude Code 자체가 실행하는 프로세스를 통해 로컬 머신에서 실행됩니다. 데이터베이스 서버나 커맨드라인 도구에서 자주 볼 수 있는 방식입니다.

$claude mcp add --transport stdio --env MA_CLE_API=ta_valeur mon-outil -- npx -y nom-du-paquet-mcp

-- 이후의 부분이 Claude Code가 서버를 시작하기 위해 실행하는 정확한 명령어입니다.

/mcp로 연결된 서버 확인하기

서버를 추가한 후, Claude Code 세션 내에서 /mcp 슬래시 명령어로 상태를 확인할 수 있습니다.

$/mcp

이 명령어는 구성된 모든 MCP 서버, 상태(연결됨, 오류, 인증 대기 중), 그리고 프로젝트별 권한 관리 패널을 엽니다.

세션 밖에서 터미널로도 서버를 나열할 수 있습니다.

$claude mcp list

.mcp.json에 설정 저장하기

claude mcp add 명령어는 서버를 로컬에서 나 자신만을 위해 등록합니다. 팀과 설정을 공유하거나 프로젝트에 버전 관리하려면, 저장소 루트에 .mcp.json 파일을 만드세요.

{
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "ma-base": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "nom-du-paquet-mcp"],
      "env": {
        "MA_CLE_API": "${MA_CLE_API}"
      }
    }
  }
}

${} 사이의 환경 변수는 실행 시 셸에서 해석됩니다. 따라서 버전 관리된 파일에 시크릿을 평문으로 작성할 필요가 없습니다.

알아두면 좋은 MCP 서버들

MCP 사양은 Anthropic이 주도하지만 에코시스템은 개방되어 있습니다. 다양한 사용 사례를 잘 보여주는 서버 세 가지를 소개합니다.

Filesystem - 접근 가능한 폴더를 세밀하게 제어하는 안전한 파일 시스템 접근. Claude Code에 파일 트리의 명시적인 범위를 부여하는 데 유용합니다.

GitHub - 터미널을 떠나지 않고 PR을 읽고, 이슈를 만들고, 리뷰를 게시합니다. Claude가 히스토리를 탐색하고 직접 댓글을 달 수 있습니다.

Supabase - Claude Code를 PostgreSQL 데이터베이스와 Edge Functions에 연결합니다. 이것이 Supabase 측 이 브리지의 다음 단계에서 다룰 예시입니다.