클로드 코드 MCP 서버 연동 실전 가이드 (2026)

클로드 코드는 Anthropic이 만든 터미널 기반 AI 코딩 도구입니다. 단독으로 써도 코드 생성·리팩터링·디버깅을 처리하는 강력한 어시스턴트지만, MCP 서버를 연결하는 순간 데이터베이스·외부 API·파일 시스템을 AI가 직접 읽고 제어할 수 있게 됩니다. 이 글은 클로드 코드 설치부터 MCP 서버 연동 설정까지, 실제 터미널 명령어와 JSON 설정 파일을 그대로 담은 실전 가이드입니다.

클로드 코드란 무엇인가

클로드 코드(Claude Code)는 터미널에서 실행하는 AI 코딩 어시스턴트입니다. 별도의 IDE 플러그인 없이 명령줄에서 바로 작동하며, 파일 읽기·쓰기, git 조작, 테스트 실행까지 직접 수행합니다. 코드 생성에서 리팩터링, 버그 수정, PR 리뷰까지 개발 워크플로 전반을 커버합니다.

다른 AI 코딩 도구와의 차이점은 에이전트 방식으로 작동한다는 점입니다. 단순히 코드 스니펫을 제안하는 데 그치지 않고, 멀티스텝 작업을 스스로 계획하고 실행합니다. MCP 서버를 연결하면 이 에이전트 능력이 외부 시스템으로 확장됩니다.

클로드 코드를 어떻게 설치하는가

클로드 코드는 npm 패키지로 배포됩니다. 설치 전에 Node.js 18 이상이 필요합니다.

# Node.js 버전 확인
node --version

# 클로드 코드 글로벌 설치
npm install -g @anthropic-ai/claude-code

# API 키 설정 (macOS / Linux)
export ANTHROPIC_API_KEY="sk-ant-..."

# API 키 설정 (Windows PowerShell)
$env:ANTHROPIC_API_KEY = "sk-ant-..."

# 실행
claude

API 키는 Anthropic 콘솔에서 발급받을 수 있습니다. claude를 실행하면 대화형 프롬프트가 열립니다. claude --help로 사용 가능한 옵션을 확인할 수 있습니다.

API 키를 매번 입력하지 않으려면 셸 설정 파일(~/.bashrc 또는 ~/.zshrc)에 export 줄을 추가하면 됩니다.

MCP 서버란 무엇인가

MCP(Model Context Protocol)는 Anthropic이 2024년에 공개한 오픈 표준 프로토콜입니다. 외부 데이터 소스와 도구를 AI가 일관된 방식으로 연결할 수 있도록 표준화한 프로토콜로, USB-C가 다양한 기기를 하나의 포트로 연결하는 것과 비슷한 개념입니다.

MCP 서버를 클로드 코드에 연결하면 다음이 가능해집니다.

• PostgreSQL·SQLite 데이터베이스를 AI가 직접 조회
• 파일 시스템의 특정 디렉토리를 읽고 쓰기
• GitHub 리포지토리의 이슈·PR을 조회하고 생성
• 외부 URL에서 데이터를 가져와 실시간 분석

MCP 서버는 로컬에서 실행되는 프로세스입니다. 클로드 코드가 이 프로세스와 표준화된 방식으로 통신합니다. 서드파티 개발자들도 MCP 서버를 만들 수 있어 생태계가 빠르게 성장 중입니다.

클로드 코드에 MCP 서버를 어떻게 연동하는가

MCP 서버를 추가하는 방법은 두 가지입니다. CLI 명령어를 사용하는 방법과 JSON 설정 파일을 직접 편집하는 방법입니다.

CLI로 추가하기

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/yourname/projects

이 명령어를 실행하면 ~/.claude.json 파일에 서버 설정이 자동으로 저장됩니다.

JSON 설정 파일 직접 편집

~/.claude.json(Windows는 %USERPROFILE%\.claude.json)을 열어 mcpServers 키를 추가합니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/yourname/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:password@localhost:5432/mydb"]
    }
  }
}

설정 파일을 저장한 후 클로드 코드를 재시작하면 MCP 서버가 연결됩니다. /mcp 명령어로 연결 상태를 확인할 수 있습니다.

클로드 코드에서 자주 쓰는 MCP 서버는 무엇인가

공식 MCP 서버 패키지 중 백엔드·풀스택 개발자가 가장 많이 활용하는 5가지를 소개합니다.

1. server-filesystem (@modelcontextprotocol/server-filesystem) — 로컬 파일 시스템의 특정 디렉토리를 읽고 씁니다. 프로젝트 루트를 지정하면 AI가 파일 구조를 파악하고 코드를 수정합니다.
2. server-postgres (@modelcontextprotocol/server-postgres) — PostgreSQL 데이터베이스에 접속해 스키마 탐색, 쿼리 실행, 데이터 분석을 수행합니다. 연결 문자열을 args에 전달합니다.
3. server-github (@modelcontextprotocol/server-github) — GitHub API를 통해 이슈 조회, PR 생성, 코드 검색을 합니다. Personal Access Token을 환경 변수로 설정합니다.
4. server-fetch (@modelcontextprotocol/server-fetch) — 외부 URL의 콘텐츠를 가져옵니다. API 문서나 웹 페이지를 실시간으로 참조할 때 유용합니다.
5. server-sqlite (@modelcontextprotocol/server-sqlite) — 로컬 SQLite 파일에 접속합니다. 소규모 프로젝트나 로컬 개발 환경에서 PostgreSQL 없이도 DB 조회가 가능합니다.

GitHub MCP 서버처럼 인증이 필요한 서버는 env 키로 토큰을 전달합니다.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  }
}

MCP 연동 오류는 어떻게 해결하는가

MCP 서버 연결에 실패하는 경우 다음 체크리스트를 순서대로 확인합니다.

1. JSON 문법 오류 — ~/.claude.json의 문법을 검증합니다. 쉼표 누락이나 따옴표 오류가 가장 흔한 원인입니다.
2. npx 캐시 문제 — npx cache clean --force를 실행한 후 다시 시도합니다.
3. 환경 변수 미설정 — 인증이 필요한 서버의 경우 env 키에 토큰이 올바르게 입력되어 있는지 확인합니다.
4. 경로 오류 — filesystem 서버의 경우 지정한 디렉토리가 실제로 존재하는지 확인합니다.
5. DB 접속 실패 — postgres 서버라면 연결 문자열의 호스트·포트·자격증명을 점검합니다.
6. 재시작 필요 — 설정 파일을 변경한 후에는 클로드 코드를 완전히 종료하고 다시 실행합니다.
7. /mcp 명령어 활용 — 클로드 코드 내에서 /mcp를 입력하면 현재 연결된 MCP 서버 목록과 상태를 확인할 수 있습니다.

클로드 코드 학습을 심화하려면

프롬프트 엔지니어링 설계 원칙, 클로드 모델 아키텍처, 안전성 원칙 등을 체계적으로 공부하고 싶다면 CCA-F(Claude Certified Architect — Foundations) 자격증을 고려해볼 만합니다. API 설계 철학도 폭넓게 다룹니다.

Plinth Prep은 CCA-F 시험 준비를 위한 독립 학습 사이트입니다. Anthropic과 제휴·후원·인증 관계가 전혀 없으며 공식 시험 기관도 아닙니다. 실제 시험 문제를 보유하거나 합격을 보장하지 않습니다.