🎓 유데미 강의 추천
Claude Code 실전 강의 — AI 코딩을 지금 시작하세요
설치부터 자동화·에이전트 활용까지, 실무에서 바로 쓰는 Claude Code 활용법을 단계별로 배울 수 있습니다.
강의 보러가기 →
Claude Code 가이드 #4 — MCP 서버 연결하기
한 줄 요약: MCP 서버를 Claude Code에 연결하면 데이터베이스 조회, GitHub API 호출, 파일 시스템 접근 등을 AI가 직접 수행할 수 있어 작업 범위가 크게 확장된다. MCP(Model Context Protocol)는 Claude Code가 외부 도구와 통신하는 표준 프로토콜이다. 이 가이드는 MCP 서버 연결 방법, 주요 서버 목록, 보안 설정을 정리한다.
by Lee
한 줄 요약: MCP 서버를 Claude Code에 연결하면 데이터베이스 조회, GitHub API 호출, 파일 시스템 접근 등을 AI가 직접 수행할 수 있어 작업 범위가 크게 확장된다.
MCP(Model Context Protocol)는 Claude Code가 외부 도구와 통신하는 표준 프로토콜이다. 이 가이드는 MCP 서버 연결 방법, 주요 서버 목록, 보안 설정을 정리한다.
강의 보러가기 →
MCP란?
MCP는 Claude Code와 외부 서비스를 연결하는 다리입니다. 별도의 API 코드를 작성할 필요 없이, MCP 서버를 설정하면 Claude Code가 해당 서비스의 데이터에 접근할 수 있습니다.
- Google Drive: 디자인 문서, 스프레드시트 읽기
- Jira/Asana: 티켓 생성, 상태 업데이트
- Slack: 채널 메시지 검색, 알림 전송
- 커스텀 도구: 자신만의 MCP 서버 구축 가능
MCP 서버 연결은 .claude/settings.json 또는 claude_desktop_config.json에서 설정한다. 각 MCP 서버는 command(실행 명령)와 args(인수)로 정의하며, 필요한 경우 env로 환경 변수(API 키 등)를 전달한다.
MCP 서버 설정 예시// .claude/settings.json { "mcpServers": { "postgres": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/mydb"] }, "github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"], "env": { "GITHUB_TOKEN": "ghp_xxxx" } }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"] } } }
주요 공식 MCP 서버: server-postgres(PostgreSQL 쿼리), server-github(이슈/PR 관리), server-filesystem(파일 접근), server-brave-search(웹 검색), server-puppeteer(웹 스크래핑/테스트). 커뮤니티 서버로 Slack, Notion, Jira 연동도 가능하다.
MCP 서버 설정 방법
Claude Code 설정 파일에 MCP 서버를 추가합니다.
MCP 서버 등록 (설정 파일){ "mcpServers": { "google-drive": { "type": "url", "url": "https://gdrive.mcp.claude.com/mcp" }, "custom-tool": { "type": "stdio", "command": "node", "args": ["./my-mcp-server.js"] } } }
커스텀 MCP 서버 만들기
팀 내부 도구나 데이터베이스에 Claude Code를 연결하려면 커스텀 MCP 서버를 만들 수 있습니다. Node.js 기반으로 간단하게 구현 가능합니다.
💡 팁: MCP 서버는 uvx를 사용해 배포하면 팀원들과 쉽게 공유할 수 있습니다.
다음 편에서는 에이전트 & 서브에이전트를 다룹니다. Multi-Agent 시스템으로 코드 리뷰를 자동화하는 방법을 알아봅니다.
MCP 보안 설정
최소 권한 원칙: DB 서버는 읽기 전용 사용자로 연결, 파일 시스템은 특정 디렉토리만 허용, GitHub 토큰은 필요한 scope만 부여. 환경 분리: 프로덕션 DB에 직접 연결하지 말 것 — 개발/스테이징 환경만 사용. API 키 관리: 환경 변수나 시스템 키체인을 사용하고, 설정 파일에 직접 기재하지 말 것.
시작 추천: 처음 MCP를 사용한다면
server-filesystem부터 시작하라. 가장 단순하고 안전하며, AI가 프로젝트 외부 파일(문서, 스펙)을 참조할 수 있게 해준다.🎓 관련 강의
Claude Code 완전 정복 — 유데미 강의
이 글에서 다룬 내용을 더 체계적으로 배우고 싶다면 강의를 확인해보세요. 실전 예제 중심으로 구성되어 있습니다.
강의 살펴보기 →
자주 묻는 질문
더 깊게 공부하려면 어떤 자료를 보면 좋을까요?
두 갈래로 파고드시면 좋습니다. 첫째, 프로토콜 자체를 이해하려면 Model Context Protocol 공식 사이트(modelcontextprotocol.io)의 specification 문서를 보세요. 여기서 stdio·URL 트랜스포트, tools·resources·prompts 라는 세 가지 기본 단위, 그리고 메시지가 JSON-RPC 로 오가는 구조를 알면 커스텀 서버를 만들 때 막히지 않습니다. 둘째, 바로 쓸 서버를 늘리려면 깃허브의 modelcontextprotocol/servers 저장소를 보시길 권합니다. 본문에서 다룬 server-postgres·server-github·server-filesystem 외에 Slack·Notion 같은 커뮤니티 서버 구현이 모두 모여 있어, 코드를 그대로 읽으며 자신의 도구를 MCP 로 감싸는 패턴을 익힐 수 있습니다.
Claude Code 가이드 #4, 한 줄로 정리하면 어떻게 되나요?
MCP 서버는 별도 API 코드 없이 Claude Code 를 외부 도구(데이터베이스·깃허브·파일 시스템 등)에 연결하는 표준 다리이며, .claude/settings.json 의 mcpServers 블록에 command·args·env 를 적어 등록합니다. 다만 서버를 붙이는 순간 AI 에게 그 도구의 접근 권한이 그대로 넘어가므로, 읽기 전용 계정·최소 scope·디렉터리 제한 같은 최소 권한 원칙을 지키는 것이 핵심입니다.
실무에서 처음 도입할 때 가장 먼저 확인할 것은 무엇인가요?
권한 범위부터 정하시길 권합니다. MCP 서버는 등록하는 순간 AI에게 그 도구의 접근 권한을 그대로 넘기기 때문에, 어떤 서버를 어느 범위로 붙이느냐가 첫 결정입니다. 가장 안전한 출발점은 server-filesystem 하나를 프로젝트 디렉터리에만 묶어 파일 읽기·쓰기 동작을 눈으로 확인하는 것입니다. 그다음 DB가 필요하면 server-postgres를 읽기 전용 계정으로, GitHub 연동은 토큰 scope를 최소로 좁혀 추가하시면 됩니다. 설정은 .claude/settings.json의 mcpServers 블록에 적고, API 키는 파일에 직접 쓰지 말고 env 항목으로 주입한 뒤 claude mcp list로 connected 상태인지부터 확인하세요.
가장 자주 발생하는 실수나 함정은 무엇인가요?
MCP 연결에서 가장 자주 막히는 지점은 세 가지입니다. 첫째, claude mcp add로 등록한 뒤 uvx·npx 실행 파일을 PATH에서 찾지 못해 서버가 조용히 연결 실패하는 경우로, claude mcp list로 상태(connected/failed)를 먼저 확인하면 빠르게 잡힙니다. 둘째, server-filesystem을 프로젝트 루트가 아닌 상위 디렉터리에 물려 AI가 의도보다 넓은 범위의 파일에 접근하게 되는 보안 실수인데, 접근 경로를 최소 범위로 좁혀야 합니다. 셋째, 커스텀 서버를 만들 때 로그를 표준출력(stdout)에 섞어 protocol 메시지를 깨뜨리는 경우로, 로그는 반드시 표준에러(stderr)로 분리해야 합니다. 처음이라면 본문 권장대로 server-filesystem 하나만 붙여 검증한 뒤 확장하시길 권합니다.
다른 대안과 비교했을 때 어떤 상황에 적합한가요?
MCP 연결은 AI 가 코드 작성을 넘어 실제 데이터나 서비스를 직접 만져야 할 때 적합합니다. 예를 들어 DB 스키마를 보며 쿼리를 짜거나, 이슈·PR 상태를 읽어 작업하거나, 프로젝트 밖 문서·스펙을 참조해야 하는 상황이라면 server-postgres·server-github·server-filesystem 을 붙이는 편이 매번 내용을 복사해 붙여넣는 것보다 훨씬 효율적입니다. 반대로 단일 저장소 안에서 코드만 읽고 고치는 작업이라면 Claude Code 가 이미 파일 시스템에 접근하므로 굳이 MCP 를 추가할 필요가 없습니다. 또 프로덕션 DB 처럼 잘못 건드리면 위험한 자원, 혹은 권한을 안전하게 좁히기 어려운 도구라면 연결 자체를 보류하고 개발·스테이징 환경에서만 검증하는 것이 맞습니다.
claude-code클로드 코드mcp통합google-drivejira
