Claude Code MCP 서버 연동 실전 — 로컬 DB·GitHub·파일시스템을 AI 도구로 연결하는 법

한줄 결론: MCP(Model Context Protocol)를 설정 파일에 등록하면 Claude Code가 파일시스템·GitHub·로컬 DB를 직접 조작하는 도구를 손에 쥔다.

Claude Code는 MCP 서버를 연결하는 순간 단순 코드 보조 도구에서 '외부 시스템을 제어하는 에이전트'로 바뀐다. 개발자 워크플로를 자동화하고 싶은 사람, 이미 Claude Code를 쓰면서 반복 작업이 많다고 느끼는 사람이 읽어야 한다. 이 글은 MCP 개념부터 대표 서버 설정, OAuth 인증, 보안 주의점까지 실전에서 바로 쓸 수 있는 수준으로 다룬다.

Claude Code MCP 서버 연동 요약 이미지

Claude Code MCP 서버 연동 구조와 체크포인트를 요약한 AI 생성 대표 이미지.

MCP가 무엇이고, 왜 지금 중요한가?

MCP(Model Context Protocol)는 Anthropic이 2024년 11월 공개한 개방형 표준으로, LLM 클라이언트와 외부 도구 서버를 JSON-RPC로 연결한다. 함수 호출(Function Calling)이 모델에 종속된 독점 인터페이스라면, MCP는 어떤 클라이언트·어떤 서버도 같은 규격으로 붙을 수 있는 'USB-C 같은 범용 커넥터'다. Cursor, Windsurf, Gemini CLI 등도 동일한 MCP 서버를 재사용할 수 있어 생태계가 빠르게 확대되고 있다.

MCP 서버가 제공하는 기능은 크게 3가지다. 첫째, Tools—모델이 직접 호출하는 함수(파일 읽기, DB 쿼리 등). 둘째, Resources—컨텍스트로 주입할 수 있는 데이터(문서, 로그). 셋째, Prompts—서버가 미리 정의한 프롬프트 템플릿. Claude Code는 주로 Tools 레이어를 활용한다.

전송 방식(Transport)은 어떤 것을 골라야 하는가?

전송 방식은 로컬이면 stdio, 원격이면 Streamable HTTP가 현재 권장 표준이다. 2025년 3월 MCP 스펙 개정(2025-03-26)으로 기존 HTTP+SSE 방식은 deprecated됐고, TypeScript SDK 1.10.0(2025년 4월)부터 Streamable HTTP를 공식 지원한다. SSE 방식은 일부 벤더(예: Atlassian Rovo는 2026년 6월 30일)가 개별적으로 종료 시점을 공지하고 있으나, MCP 스펙 자체는 하위 호환을 위해 SSE 엔드포인트 병행 운영을 허용하고 있다. 새로 서버를 구성할 때는 SSE 방식을 선택하지 않는 것이 원칙이다.

Transport	적합한 상황	type 값	비고
stdio	로컬 실행 파일, npx/uvx 서버	`stdio`	가장 일반적, 기본값
Streamable HTTP	원격 서버, 팀 공유 서버	`http`	스펙명 streamable-http, alias http
~~HTTP+SSE~~	-	~~sse~~	2025년 3월 deprecated, 신규 구성 비권장

설정 파일에 MCP 서버를 어떻게 등록하는가?

Claude Code는 3개 레벨로 MCP 설정을 관리한다. User 레벨(~/.claude.json)은 모든 프로젝트에서 사용 가능한 전역 설정이다. Project 레벨(.mcp.json — 프로젝트 루트)은 팀 공유용으로 Git에 포함한다. Local 레벨(.claude/settings.local.json)은 개인 전용으로 버전 관리에서 제외한다. 팀 공유 서버는 .mcp.json에, API 키처럼 민감한 서버는 Local 레벨에 분리하는 것이 실무 원칙이다.

CLI 한 줄로 등록하는 방법이 가장 빠르다.

# stdio 방식 (로컬 npx 서버)
claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/me/projects

# HTTP 방식 (원격 서버 + Bearer 토큰)
claude mcp add --transport http my-api https://api.example.com/mcp \
  --header "Authorization: Bearer ${MY_API_TOKEN}"

# 등록된 서버 목록 확인
claude mcp list

JSON 파일로 직접 편집하는 방법도 동일하게 동작한다. 프로젝트 루트의 .mcp.json 예시는 아래와 같다.

{
  "mcpServers": {
    "filesystem": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
    },
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres",
               "postgresql://user:pass@localhost:5432/mydb"]
    }
  }
}

환경변수는 ${VAR_NAME} 문법으로 주입할 수 있다. API 키를 JSON에 평문으로 기입하지 말고 반드시 환경변수 참조로 처리해야 한다. .mcp.json을 Git에 올릴 때 secrets가 포함되지 않도록 이 점이 핵심이다.

어떤 MCP 서버가 실무에서 즉시 쓸 만한가?

공식 modelcontextprotocol/servers 레포와 커뮤니티 큐레이션을 기준으로 실무 활용도가 높은 서버를 정리한다. 모든 버전·기능은 업데이트가 잦으므로 공식 저장소에서 최신 내용을 재확인하는 것을 권한다.

파일시스템 (@modelcontextprotocol/server-filesystem)

허용 경로를 인수로 지정하면 그 범위 안에서만 읽기·쓰기·디렉터리 탐색이 가능하다. Claude Code 자체 파일 접근과 겹치지만, 특정 경로를 명시적으로 '도구'로 노출해 에이전트 루프 안에서 제어하고 싶을 때 유용하다.

GitHub (@modelcontextprotocol/server-github 또는 공식 github/github-mcp-server)

레포 탐색, 이슈 생성·조회, PR 리뷰, 파일 커밋까지 GitHub API를 자연어 명령으로 처리한다. Personal Access Token(최소 권한 스코프 권장)을 환경변수로 주입한다. GitHub 공식 MCP 서버(github/github-mcp-server)는 별도 레포에서 유지 관리되며, @modelcontextprotocol/server-github와 병행 존재한다.

PostgreSQL (@modelcontextprotocol/server-postgres)

기본적으로 읽기 전용 연결로 동작한다. 스키마 탐색, SELECT 쿼리 실행이 가능하다. 커넥션 문자열에 프로덕션 DB를 직접 연결하는 것은 위험하다. 읽기 전용 레플리카나 개발용 DB를 따로 두는 것이 원칙이다.

SQLite

로컬 .db 파일을 직접 읽고 쿼리한다. 서버를 별도로 올릴 필요 없이 파일 경로만 지정하면 되어 개인 프로젝트, 스크립트 작업에 적합하다.

Git (@modelcontextprotocol/server-git)

로컬 Git 저장소의 로그, diff, blame, 브랜치 정보를 조회한다. 코드 변경 히스토리 분석이나 커밋 자동화 워크플로에 활용한다.

원격 서버의 OAuth 인증은 어떻게 처리하는가?

Notion, Google Drive, Atlassian 등 SaaS 서비스 MCP 서버는 OAuth 2.1 플로를 요구한다. MCP 스펙(2025-11-25 버전 기준)은 공개 원격 서버에 대해 PKCE(Proof Key for Code Exchange) S256 적용을 필수로 규정한다. 단, 사내 도구나 개인용 원격 서버는 static Bearer 토큰 방식도 허용된다. Claude Code는 OAuth 플로를 직접 처리하지 않으므로, 실무에서는 mcp-remote 같은 프록시 도구를 이용해 로컬에서 OAuth를 완료하고 토큰을 캐시한 뒤 Claude Code에 stdio 또는 HTTP로 노출하는 패턴이 많이 쓰인다.

# mcp-remote를 이용한 Notion 공식 MCP 연결 예시 (.mcp.json)
{
  "mcpServers": {
    "notion-remote": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.notion.com/sse"]
    }
  }
}

최초 실행 시 터미널에 OAuth URL이 출력된다. 브라우저에서 해당 URL을 열어 인증을 완료하면 토큰이 로컬(~/.mcp-auth/)에 캐시된다. 이후 재실행 시 자동으로 재사용된다. 인증 상태가 의심스러우면 캐시 디렉터리를 직접 확인하는 것이 빠르다.

MCP 연결 시 어떤 보안 위험을 알아야 하는가?

MCP 서버를 무분별하게 연결하는 것은 실질적인 위험이다. 2025~2026년 사이 여러 보안 연구에서 MCP 관련 취약점이 공개됐다. 서드파티 서버의 툴 설명(description)에 숨겨진 악의적 지시가 Claude를 통해 실행되는 '프롬프트 인젝션' 공격이 대표적이다. 실제로 파일 삭제, API 키 탈취, 원격 코드 실행으로 이어진 사례가 보고됐다.

아래 원칙을 지키면 리스크를 크게 낮출 수 있다.

출처 검증: 공식 레포(modelcontextprotocol/servers, github/github-mcp-server)나 신뢰할 수 있는 조직이 관리하는 서버만 사용한다. 최근 커밋 활동을 확인한다.
최소 권한: 파일시스템 서버는 필요한 경로만, GitHub 토큰은 필요한 스코프만 부여한다. 쓰기 권한은 명시적으로 필요할 때만 추가한다.
프로덕션 DB 직접 연결 금지: 읽기 전용 레플리카나 스테이징 DB를 사용한다.
API 키 평문 금지: .mcp.json에 키를 직접 기입하지 않는다. ${ENV_VAR} 참조 또는 Local 레벨 설정(버전 관리 제외)을 사용한다.
서버 수 제한: 실무에서 동시에 활성화하는 서버는 4~6개 내외가 적정하다. 도구 수가 많아지면 일부 클라이언트에서 성능 저하가 보고된다.

실제로 어떻게 활용하는가? — 워크플로 시나리오 3가지

시나리오 1 — 이슈 기반 코딩: GitHub MCP로 이슈를 조회하고, 해당 내용을 바탕으로 코드를 수정, 커밋, PR까지 한 세션에서 처리한다. '이슈 #42 내용 읽고 수정 PR 올려줘' 한 줄로 반복 작업을 자동화할 수 있다.

시나리오 2 — 로컬 DB 분석: PostgreSQL 또는 SQLite MCP를 연결하면 'users 테이블에서 지난주 가입자 수 알려줘' 같은 자연어 쿼리가 가능하다. BI 도구 없이 빠른 데이터 탐색에 유용하다.

시나리오 3 — Obsidian 노트 연동: 파일시스템 MCP로 Vault 경로를 노출하면 Claude Code가 노트를 읽고 내용을 기반으로 코드를 생성하거나 문서를 업데이트한다.

연결이 안 될 때 어떻게 디버깅하는가?

가장 먼저 claude mcp list로 서버가 등록됐는지 확인한다. 등록됐는데 동작하지 않으면 서버 프로세스 자체를 터미널에서 직접 실행해 에러를 확인하는 것이 빠르다. 예를 들어 npx -y @modelcontextprotocol/server-filesystem /tmp를 직접 실행하면 JSON-RPC 입력을 기다리는 상태가 된다. 이 상태가 되지 않으면 설치나 의존성 문제다.

# 서버 목록 확인
claude mcp list

# 특정 서버 상세 정보 확인
claude mcp get filesystem

# 서버 제거
claude mcp remove filesystem

# 세션 내 /mcp 슬래시 커맨드로 상태 확인
/mcp

타임아웃 에러가 반복되면 해당 서버 설정에 "timeout": 60000(밀리초)을 추가해 볼 수 있다. npx 기반 서버는 최초 실행 시 패키지 다운로드로 수 초가 걸리는 경우가 있다.

FAQ — 자주 나오는 질문 5가지

Q1. MCP 서버를 추가하면 Claude Code가 무엇이든 할 수 있게 되는가?
서버가 노출하는 도구 범위 안에서만 동작한다. 파일시스템 서버에 경로를 지정하지 않으면 다른 경로는 접근하지 못한다. 도구 정의가 곧 권한 경계다.

Q2. .mcp.json을 Git에 올려도 괜찮은가?
API 키 같은 민감 정보가 없다면 올려도 된다. 키는 반드시 ${ENV_VAR}로 참조해야 한다. 팀원이 동일한 환경변수를 로컬에 설정하면 그대로 사용할 수 있어 온보딩이 편해진다.

Q3. Claude Desktop과 Claude Code의 MCP 설정 파일이 다른가?
다르다. Claude Desktop은 ~/Library/Application Support/Claude/claude_desktop_config.json을 사용한다. Claude Code는 ~/.claude.json(User 레벨) 또는 프로젝트 루트의 .mcp.json(Project 레벨)을 사용한다. 공식 문서(code.claude.com/docs)에서 경로를 재확인하는 것을 권한다.

Q4. MCP 서버를 직접 만들 수 있는가?
가능하다. Python SDK(mcp 패키지)와 TypeScript SDK(@modelcontextprotocol/sdk)가 공식으로 제공된다. FastMCP 같은 상위 레이어 프레임워크를 쓰면 boilerplate 없이 빠르게 만들 수 있다.

Q5. 서버를 여러 개 연결하면 성능에 영향이 있는가?
서버 자체는 별도 프로세스로 동작하므로 Claude Code 응답속도에 직접 영향을 주지는 않는다. 단, 도구 목록이 많아지면 컨텍스트 길이가 늘어나고 모델이 적합한 도구를 선택하는 정확도가 떨어질 수 있다. 일반적으로 4~6개 서버, 도구 수는 적을수록 정확도가 높다는 의견이 많다.

3줄 요약

MCP는 Claude Code가 외부 도구를 직접 호출할 수 있게 하는 개방형 표준 프로토콜이다.
~/.claude.json(User 레벨) 또는 프로젝트 루트의 .mcp.json(Project 레벨)에 서버를 등록하면 되고, API 키는 환경변수 참조로만 처리해야 한다.
서드파티 서버는 출처를 꼭 검증하고, 최소 권한 원칙과 프로덕션 DB 직접 연결 금지를 반드시 지켜야 한다.

다음 글 예고: MCP 서버를 직접 만드는 방법 — Python SDK로 사내 시스템을 Claude Code 도구로 노출하기. 서버 구조, 도구 정의, stdio 프로세스 통신 구현을 다룬다.

도구 기능·설정 파일 경로는 업데이트가 잦아 공식 문서 재확인을 권한다.

🤖 AI·자동화 가이드 더 보기

마와린세 패스 완전정리 — 이세시마 여행 [1/9]

5월 29, 2026

자세한 내용 보기

이 블로그 검색

잘난코 여행·맛집 가이드