코딩 에이전트가 구버전 API를 추천하거나, 로컬 파일 구조를 전혀 모른 채 엉뚱한 경로를 제안한 경험이 있을 겁니다. 이 문제의 근본 원인은 LLM이 텍스트만 처리할 수 있다는 구조적 한계입니다.

MCP(Model Context Protocol)는 이 한계를 해결하는 표준 인터페이스입니다. LLM에 실제 파일 시스템 읽기·쓰기, 외부 API 호출, 터미널 명령 실행 권한을 부여합니다. 그 결과 에이전트는 여러분의 프로젝트 폴더를 직접 열어보고, 실제 코드를 수정하며, 테스트까지 돌릴 수 있습니다.

이 글은 Gemini CLI를 기준으로 MCP 서버를 구축하고 실제 프로젝트에 연동하는 과정을 처음부터 끝까지 다룹니다.

Model Context Protocol(MCP)이란 무엇인가?

MCP는 LLM과 외부 자원을 연결하는 표준 통신 규약입니다. Anthropic이 2024년 말 오픈 프로토콜로 제안했고, 현재 Google(Gemini), OpenAI(GPT), Anthropic(Claude) 등 주요 LLM 공급사가 모두 지원합니다.

구조는 세 요소로 이루어집니다.

구성 요소	역할	예시
MCP 서버	도구(Tool)를 외부에 노출하는 프로세스	파일시스템 서버, GitHub 서버
MCP 클라이언트	서버에 연결하여 도구를 호출하는 LLM 호스트	Gemini CLI, Cursor, Claude Code
도구(Tool)	서버가 제공하는 실제 기능 단위	read_file, create_issue, run_query

일반 LLM 챗봇 vs MCP 연동 에이전트를 직접 비교하면 차이가 명확해집니다.

비교 항목	일반 LLM 챗봇	MCP 연동 에이전트
파일 접근	❌ 불가 (텍스트 붙여넣기만 가능)	✅ 직접 읽기/쓰기/생성
외부 API 호출	❌ 불가	✅ GitHub, Jira, Slack 등
터미널 명령 실행	❌ 불가	✅ npm test, git commit 등
최신 문서 참조	❌ 학습 데이터 컷오프 한계	✅ 실시간 API Docs MCP
할루시네이션	높음 (컨텍스트 부재)	낮음 (실제 파일/문서 기반)

핵심은 LLM이 ‘보는’ 세계의 크기입니다. MCP 없이는 대화 창 안의 텍스트가 전부입니다. MCP를 연결하면 실제 코드베이스, 외부 서비스, 최신 문서 전체가 에이전트의 작업 공간이 됩니다.

Gemini CLI 설치 및 코딩 에이전트 기본 세팅

필수 조건 확인

# Node.js 18 이상 필요
node --version   # v18.x.x 이상이어야 합니다

# npm 또는 npx 사용 가능 여부 확인
npm --version

Node.js가 없다면 nodejs.org에서 LTS 버전을 설치합니다.

Gemini CLI 설치

# 글로벌 설치 (권장)
npm install -g @google/gemini-cli

# 설치 확인
gemini --version

Google AI Studio API 키 발급 및 등록

1. Google AI Studio에 접속합니다.
2. 우측 상단 Get API Key → Create API key 클릭
3. 생성된 키를 복사합니다.

환경 변수에 등록합니다. 쉘 설정 파일(.zshrc 또는 .bashrc)에 추가하는 방식이 가장 안전합니다.

# ~/.zshrc 또는 ~/.bashrc에 추가
export GEMINI_API_KEY="AIza..."

# 변경 사항 즉시 적용
source ~/.zshrc

기본 동작 확인

# 터미널에서 Gemini와 대화 시작
gemini

# MCP 서버 목록 확인 (아직 없으면 빈 목록 출력)
gemini mcp list

나만의 커스텀 MCP 서버 연결 (JSON 설정)

Gemini CLI의 MCP 설정은 ~/.gemini/settings.json 파일로 관리합니다. 프로젝트별 설정은 .gemini/settings.json(프로젝트 루트)에 작성합니다.

글로벌 설정 파일 생성

mkdir -p ~/.gemini
touch ~/.gemini/settings.json

파일시스템 MCP 서버 연결 (가장 기본)

아래 JSON을 ~/.gemini/settings.json에 붙여넣습니다.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/your-username/projects"
      ]
    }
  }
}

/Users/your-username/projects 부분을 에이전트가 접근할 실제 폴더 경로로 변경합니다. 보안상 꼭 필요한 폴더만 지정하세요.

GitHub MCP 서버 추가

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

GitHub 토큰은 GitHub Settings → Tokens에서 발급합니다. 필요한 스코프는 repo, issues, pull_requests입니다.

Cursor IDE 연동 설정

Cursor를 사용하는 경우 프로젝트 루트의 .cursor/mcp.json에 동일한 형식으로 작성합니다.

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

Cursor는 설정 파일 저장 후 IDE를 재시작하면 MCP 서버가 자동으로 연결됩니다. 좌측 하단 MCP 상태 표시줄에서 연결 여부를 확인할 수 있습니다.

최신 Gemini API Docs MCP 연동 — 할루시네이션 없는 에이전트 만들기

2026년 4월 Google이 공식으로 공개한 Gemini API Docs MCP는 에이전트가 Gemini API 최신 문서를 직접 참조할 수 있게 해줍니다. 구버전 API를 추천하거나 존재하지 않는 파라미터를 만들어내는 문제를 해결합니다.

Gemini API Docs MCP 설정 추가

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/your-username/projects"
      ]
    },
    "gemini-api-docs": {
      "command": "npx",
      "args": ["-y", "@google/gemini-api-docs-mcp"],
      "env": {
        "GEMINI_API_KEY": "AIza..."
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

실전 워크플로우: 내 프로젝트를 분석하고 코드를 수정하는 에이전트

설정 완료 후 터미널에서 바로 테스트할 수 있습니다.

# 프로젝트 폴더로 이동
cd ~/projects/my-astro-blog

# Gemini CLI 실행
gemini

# 에이전트에게 요청
> 현재 프로젝트 폴더 구조를 파악하고, package.json의 의존성을 분석해줘.
> 사용 중인 Astro 버전에 맞는 최신 Image 컴포넌트 API를 적용해서 최적화해줘.

에이전트는 MCP를 통해 실제로 파일을 열어 분석하고, Gemini API Docs MCP에서 최신 문서를 조회한 뒤 코드를 수정합니다. 수정 내역은 git diff로 검토할 수 있습니다.

# 에이전트가 수정한 내용 확인
git diff

# 문제 없으면 커밋
git add -A && git commit -m "chore: Astro Image 컴포넌트 API 최신화"

자동 테스트 루프 설정

에이전트가 코드를 수정한 뒤 자동으로 테스트를 실행하고 실패 시 스스로 수정하는 루프를 구성할 수 있습니다.

# 터미널에서 에이전트에게 요청
> src/components/Header.tsx를 리팩토링하고 npm test를 실행해줘.
> 테스트가 실패하면 에러 로그를 분석해서 다시 수정해줘.

이 흐름이 기존 LLM 챗봇과 가장 큰 차이입니다. 챗봇은 코드를 제안하고 끝입니다. MCP 에이전트는 제안→실행→검증→재수정을 스스로 반복합니다.

트러블슈팅: 자주 발생하는 에러와 해결법

에러 1: spawn npx ENOENT

Error: spawn npx ENOENT

npx의 절대 경로를 지정합니다.

# npx 경로 확인
which npx
# 예: /usr/local/bin/npx

{
  "mcpServers": {
    "filesystem": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/your-username/projects"]
    }
  }
}

에러 2: MCP 서버 패키지 버전 충돌

npm error peer dep missing: @modelcontextprotocol/sdk@^1.0.0

각 MCP 서버 패키지의 버전을 명시합니다.

"args": ["-y", "@modelcontextprotocol/server-filesystem@latest"]

또는 node_modules 캐시를 초기화합니다.

npm cache clean --force

에러 3: Gemini API Docs MCP 인증 실패

Error: UNAUTHENTICATED: API key not valid

환경 변수 설정을 확인합니다.

echo $GEMINI_API_KEY  # 값이 출력되어야 합니다

출력이 없으면 source ~/.zshrc를 실행하거나 터미널을 재시작합니다.

관련 글

• Claude Code 실전 가이드 — 터미널에서 AI와 페어 프로그래밍하는 법
• Cursor AI 한국어 설정 방법 — .cursorrules 완벽 가이드
• Gemini 3.1 Pro 코딩 실전 테스트 — ChatBot Arena 결과 분석

자주 묻는 질문 (FAQ)

MCP 서버란 무엇인가요?

MCP(Model Context Protocol) 서버는 LLM이 파일 시스템, 외부 API, 데이터베이스 등 외부 자원에 접근할 수 있도록 연결해주는 표준 인터페이스입니다. Anthropic이 제안한 오픈 프로토콜로 현재 Gemini, Claude 등 주요 LLM이 지원합니다.

Gemini CLI는 무료로 사용할 수 있나요?

Google AI Studio API 키를 발급받아 사용하며, 개인 사용자는 무료 티어(분당 요청 수 제한 있음)로 시작할 수 있습니다. 실제 프로젝트 규모에 따라 유료 플랜 전환을 검토할 수 있습니다.

MCP 서버 설정 파일은 어디에 위치해야 하나요?

Gemini CLI의 경우 ~/.gemini/settings.json 또는 프로젝트 루트의 .gemini/settings.json에 작성합니다. Cursor는 프로젝트 루트의 .cursor/mcp.json을 사용합니다.

MCP 서버와 일반 LLM 챗봇의 차이점은 무엇인가요?

일반 LLM 챗봇은 텍스트 입력만 처리합니다. MCP 서버를 연동한 에이전트는 실제 파일을 읽고 수정하거나, GitHub 이슈를 생성하거나, 터미널 명령을 실행하는 등 실제 액션을 수행합니다.

Gemini API Docs MCP는 무엇인가요?

2026년 4월 Google이 공개한 공식 MCP 서버로, 에이전트가 Gemini API 최신 문서를 직접 참조할 수 있게 해줍니다. 구버전 API 추천이나 할루시네이션 문제를 크게 줄일 수 있습니다.

---

위 JSON 설정을 복사해서 지금 바로 여러분만의 코딩 에이전트를 세팅해 보세요. 연동 과정에서 발생하는 에러는 댓글로 남겨주시면 함께 해결하겠습니다.

---