Claude Code MCP 설정 완전 가이드 — PostgreSQL·파일시스템·GitHub 연동

백엔드 개발자라면 "AI 코딩 도구가 내 데이터베이스를 직접 조회해줄 수 있다면?"이라는 상상을 한 번쯤 해봤을 겁니다. 2024년 11월 Anthropic이 공개한 Model Context Protocol(MCP) 은 그 상상을 현실로 만들어 주는 오픈 표준입니다. OpenAI가 2025년 3월 공식 지원을 발표하고, Cloudflare·Stripe·Supabase·Linear 같은 주요 SaaS가 자체 MCP 서버를 제공하기 시작하면서 AI 에이전트 연동 방식의 사실상 표준으로 자리를 잡아가고 있습니다.

이 글은 터미널 명령어와 JSON 설정 파일을 직접 다뤄본 경험이 있는 백엔드 개발자를 대상으로 합니다. MCP의 동작 원리부터 Claude Code에서 PostgreSQL·파일시스템·GitHub를 연결하는 실제 설정 방법, 그리고 실무에서 반드시 챙겨야 할 보안 고려사항까지 한 번에 다룹니다. 이 글을 읽고 나면 Claude Code에 MCP 서버를 추가하고, 자연어로 데이터베이스를 쿼리하며, 팀 전체가 동일한 MCP 환경을 공유하는 워크플로를 직접 구성할 수 있게 됩니다.

핵심 개념

MCP란 무엇인가 — 클라이언트-서버 연결 표준

USB-C가 스마트폰·노트북·모니터를 하나의 규격으로 연결하듯, MCP는 AI 애플리케이션과 외부 시스템 사이의 공통 커넥터 역할을 합니다. 단, USB-C와 다른 점이 있습니다. USB-C는 두 장치가 대등하게 연결되지만, MCP는 Host(AI 앱)가 Server(외부 도구)를 호출하는 비대칭 구조입니다. 이전에는 도구마다 별도의 통합 코드를 작성해야 했지만, MCP를 쓰면 표준 인터페이스 하나로 수백 가지 도구를 AI에 연결할 수 있습니다.

MCP(Model Context Protocol): Anthropic이 2024년 11월에 오픈 표준으로 공개한 프로토콜. AI 언어 모델이 외부 데이터 소스·도구·서비스와 표준화된 방식으로 통신할 수 있도록 설계되었습니다. JSON-RPC 2.0 기반으로 작동합니다.

클라이언트-서버 아키텍처

MCP는 세 가지 레이어로 구성됩니다.

전송 방식은 사용 환경에 따라 선택합니다.

• stdio(Standard I/O): 로컬 프로세스 간 통신. MCP 자체는 JSON-RPC 기반의 비동기 요청-응답 모델이며, stdio는 그 메시지를 전달하는 파이프입니다. 외부 네트워크 노출 없이 로컬 DB·파일시스템 연동에 적합합니다.
• Streamable HTTP: 원격 서버와의 통신. 실시간 스트리밍을 지원하며, OAuth 2.1(Authorization Code + PKCE 흐름)로 인증합니다. 2025년 스펙에서 기존 SSE 방식을 대체했습니다.

MCP의 세 가지 핵심 Primitive

MCP 서버가 AI에게 제공할 수 있는 기능은 세 종류로 정의됩니다.

Resources는 단순 조회뿐 아니라 구독(subscribe) 기능도 포함합니다. 파일이나 DB 레코드가 변경될 때 AI에게 실시간으로 알릴 수 있는 구조입니다.

Tool Search(지연 로딩): Claude Code는 세션 시작 시 도구 이름만 로드하고, 실제 스키마는 필요한 순간에만 불러옵니다. MCP 서버를 여러 개 추가해도 컨텍스트 윈도우 낭비가 최소화되는 이유입니다.

실전 적용

빠른 시작: CLI로 MCP 서버 관리하기

Claude Code는 CLI 명령어로 MCP 서버를 추가·관리합니다.

# HTTP 전송으로 GitHub MCP 추가
claude mcp add --transport http github https://mcp.github.com/mcp
 
# stdio 전송으로 PostgreSQL MCP 추가
claude mcp add postgres-server -- npx @modelcontextprotocol/server-postgres postgresql://localhost/mydb
 
# 등록된 MCP 서버 목록 확인
claude mcp list
 
# MCP 서버 제거
claude mcp remove github

팀 단위로 설정을 공유할 때는 프로젝트 루트에 .mcp.json 파일을 사용합니다. 자격증명은 반드시 환경변수(${DATABASE_URL})로 주입하세요. config 파일에 하드코딩하면 git commit 한 번에 비밀번호가 레포지터리에 영구 기록됩니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/Users/you/projects"],
      "transport": "stdio"
    },
    "postgres": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      },
      "transport": "stdio"
    },
    "github": {
      "transport": "http",
      "url": "https://mcp.github.com/mcp"
    }
  }
}

예시 1: PostgreSQL 데이터베이스 연동

데이터 분석 업무에서 Claude Code가 자연어로 쿼리를 실행하도록 읽기 전용 DB를 연결하는 시나리오입니다.

서버 선택 기준: 단일 PostgreSQL 인스턴스라면 @modelcontextprotocol/server-postgres가 공식 지원으로 안정적입니다. PostgreSQL·MySQL·SQLite를 한 설정 파일에서 함께 관리해야 한다면 @bytebase/dbhub가 다중 DB를 지원하여 적합합니다.

# 단일 PostgreSQL — 공식 서버
claude mcp add --transport stdio postgres-server -- \
  npx -y @modelcontextprotocol/server-postgres@latest \
  "postgresql://readonly_user:pw@db.example.com:5432/analytics"
 
# 다중 DB 지원이 필요할 때 — bytebase/dbhub
claude mcp add --transport stdio db -- \
  npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly_user:pw@db.example.com:5432/analytics"

연결이 완료되면 이렇게 요청할 수 있습니다.

"지난 30일 신규 가입자 수를 일별로 보여줘"

MCP 서버는 스키마 인스펙션으로 테이블 구조를 자동으로 파악하고, 적합한 SQL을 작성해 실행한 뒤 결과를 반환합니다.

예시 2: 파일시스템 접근 제어

Claude Code가 프로젝트 파일을 직접 읽고 수정하되, 지정된 경로 밖에는 접근할 수 없도록 설정하는 방법입니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/Users/dev/projects/myapp",
        "/Users/dev/documents"
      ],
      "transport": "stdio"
    }
  }
}

args 배열에 나열한 경로만 접근이 허용됩니다. 홈 디렉터리 전체(~)나 루트(/)를 허용하면 SSH 키, .env 파일 등 민감한 파일이 모두 노출될 수 있으니 필요한 프로젝트 경로만 명시하는 것을 권장합니다.

예시 3: GitHub 워크플로 자동화

claude mcp add --transport http github https://mcp.github.com/mcp

연결 후에는 Claude Code 안에서 이런 자연어 명령이 가능해집니다.

"이 버그 관련 이슈를 열고, 현재 브랜치로 PR을 만들어줘.
 PR 설명에는 변경된 파일 목록과 테스트 방법을 포함해줘."

PR 생성·리뷰, 이슈 트래킹, 코드 검색, 브랜치 관리를 별도 탭 없이 터미널에서 처리할 수 있습니다.

예시 4: 멀티 MCP 복합 워크플로

여러 MCP 서버를 동시에 활용하면 복잡한 업무를 하나의 요청으로 처리할 수 있습니다.

사용자 요청 → Claude Code
  ├── GitHub MCP     : PR 내용 및 변경 파일 조회
  ├── PostgreSQL MCP : 관련 데이터 쿼리 (영향 범위 분석)
  └── Filesystem MCP : 로컬 설정 파일 및 환경 변수 확인
→ 종합 분석 결과 반환

멀티 에이전트 오케스트레이션: MCP는 단일 도구 연동을 넘어, 여러 AI 에이전트가 협력하는 워크플로의 통신 계층으로도 활용되고 있습니다. 단일 요청으로 코드 분석·DB 조회·파일 검토를 동시에 수행하는 패턴이 대표적입니다.

장단점 분석

장점

단점 및 주의사항

SCA(Software Composition Analysis): 오픈소스 패키지의 알려진 취약점과 라이선스 이슈를 자동으로 탐지하는 도구입니다. Snyk, OWASP Dependency-Check 등이 대표적입니다.

프롬프트 인젝션(Prompt Injection): 외부에서 주입된 텍스트가 AI의 지시문처럼 해석되어 의도치 않은 동작을 유발하는 공격입니다. 지원 티켓 내용이나 웹 문서를 통해 AI를 조작한 사례가 실증된 바 있습니다.

보안 체크리스트

MCP 서버를 실무 환경에 도입하기 전, 아래 항목을 점검하는 것을 권장합니다.

✅ 자격증명은 환경변수로 관리 (config에 하드코딩 금지)
✅ 파일시스템 서버는 필요한 디렉터리만 허용 경로로 지정
✅ DB 서버는 읽기 전용 계정 사용 (SELECT 권한만 부여)
✅ 서드파티 패키지는 버전 고정 (npx package@1.2.3 형태)
✅ 원격 MCP 서버는 OAuth 2.1 + PKCE 인증 방식 확인
✅ 컨테이너 또는 샌드박스 환경에서 실행 (고보안 환경)
✅ OpenTelemetry 등으로 MCP 상호작용 로깅 구성
✅ 사용 중인 MCP 서버 인벤토리 목록 중앙 관리

특히 다음 세 가지 실수는 실무에서 가장 빈번하게 발생합니다.

1. 자격증명을 .mcp.json에 직접 입력하는 것 — git commit 한 번에 비밀번호가 레포지터리에 영구 기록됩니다. 반드시 ${ENV_VAR} 형태의 환경변수 참조를 사용하는 것이 좋습니다.
2. 파일시스템 서버에 홈 디렉터리 전체를 허용하는 것 — "/Users/dev" 처럼 광범위하게 설정하면 SSH 키, .env 파일 등 민감한 파일이 모두 노출됩니다. 필요한 프로젝트 경로만 명시하는 것을 권장합니다.
3. 서드파티 MCP 패키지를 검증 없이 추가하는 것 — 패키지명이 유사한 악성 패키지(타이포스쿼팅)가 존재할 수 있습니다. 공식 레포지터리(modelcontextprotocol/servers)에서 확인된 패키지만 사용하고, 버전을 고정(npx package@1.2.3)하는 것이 안전합니다.

마치며

MCP는 AI 에이전트가 데이터베이스·파일·외부 API와 표준화된 방식으로 소통할 수 있는 연결 계층이며, Claude Code는 이를 가장 빠르게 체험할 수 있는 출발점입니다. 아래 세 단계로 시작해 보시면 좋겠습니다.

1. 파일시스템 MCP로 워밍업 — 파일시스템 서버를 연결한 뒤 Claude Code에 "이 프로젝트의 README를 요약해줘"라고 입력해 보시면 MCP가 어떻게 동작하는지 바로 체감하실 수 있습니다. npx @modelcontextprotocol/server-filesystem@latest를 사용해 버전을 명시하는 습관도 함께 들이시면 좋습니다.
2. DB를 읽기 전용으로 연결 — 로컬 PostgreSQL 또는 개발 DB에 SELECT 권한만 가진 계정을 만들고, @modelcontextprotocol/server-postgres로 연결해 보시면 자연어 쿼리가 SQL로 변환되는 경험을 하실 수 있습니다.
3. .mcp.json으로 팀 설정 공유 — 프로젝트 루트에 .mcp.json을 작성하고 git에 커밋하시면, 팀원 모두가 동일한 MCP 환경을 바로 사용할 수 있게 됩니다. 자격증명은 .env로 분리해 .gitignore에 포함하는 것도 잊지 않으시면 좋겠습니다.

다음 글: 기존 MCP 서버를 커스터마이징하는 법 — TypeScript SDK로 사내 API를 Claude Code에 연결하는 커스텀 MCP 서버 구현 입문 가이드

참고 자료

• Connect Claude Code to tools via MCP — 공식 Claude Code 문서 (설정 시작점으로 추천)
• Model Context Protocol 공식 스펙 (2025-11-25) (Primitive·Transport 전체 스펙)
• modelcontextprotocol/servers — 공식 레퍼런스 서버 모음 (사용 가능한 서버 목록 확인)
• What is Model Context Protocol (MCP)? — Google Cloud 가이드 (개념 입문자 추천)
• What is Model Context Protocol (MCP)? — IBM Think (개념 입문자 추천)
• MCP Security: Risks and Best Practices — Nudge Security (보안 심화)
• Securing the AI Agent Revolution: A Practical Guide to MCP Security — CoSAI (보안 심화)
• Model Context Protocol Security — Red Hat (보안 심화)
• Build an MCP Server for PostgreSQL — DEV Community (PostgreSQL 연동 실습)
• A Complete Guide to MCP: Architecture, Integration, and Best Practices — BridgeApp (아키텍처 전체 개요)
• The Model Context Protocol's Impact on 2025 — Thoughtworks (업계 트렌드)
• Model Context Protocol — Wikipedia (역사·배경)