Gemini CLI의 MCP 서버

이 문서는 Gemini CLI에서 Model Context Protocol(MCP) 서버를 구성하고 사용하는 방법에 대한 가이드를 제공합니다.

MCP 서버란 무엇인가요?

MCP 서버는 Model Context Protocol을 통해 Gemini CLI에 도구와 리소스를 노출하여 외부 시스템 및 데이터 소스와 상호 작용할 수 있도록 하는 애플리케이션입니다. MCP 서버는 Gemini 모델과 로컬 환경 또는 API와 같은 기타 서비스 사이의 다리 역할을 합니다.

MCP 서버를 통해 Gemini CLI는 다음을 수행할 수 있습니다:

도구 발견: 표준화된 스키마 정의를 통해 사용 가능한 도구, 설명 및 매개변수를 나열합니다.
도구 실행: 정의된 인자로 특정 도구를 호출하고 구조화된 응답을 받습니다.
리소스 액세스: 서버가 노출하는 특정 리소스(파일, API 페이로드, 보고서 등)에서 데이터를 읽습니다.

MCP 서버를 사용하면 데이터베이스, API, 커스텀 스크립트 또는 전문화된 워크플로와 상호 작용하는 등 기본 기능을 넘어 Gemini CLI의 기능을 확장할 수 있습니다.

핵심 통합 아키텍처

Gemini CLI는 핵심 패키지(packages/core/src/tools/)에 내장된 정교한 발견 및 실행 시스템을 통해 MCP 서버와 통합됩니다:

발견 계층 (`mcp-client.ts`)

발견 프로세스는 discoverMcpTools()에 의해 조정되며, 다음 작업을 수행합니다:

구성된 서버 반복: settings.json의 mcpServers 구성에서 서버를 반복합니다.
연결 수립: 적절한 전송 메커니즘(Stdio, SSE 또는 Streamable HTTP)을 사용하여 연결을 수립합니다.
도구 정의 가져오기: MCP 프로토콜을 사용하여 각 서버에서 도구 정의를 가져옵니다.
위생 처리 및 유효성 검사: Gemini API와의 호환성을 위해 도구 스키마를 위생 처리하고 유효성을 검사합니다.
도구 등록: 충돌 해결과 함께 전역 도구 레지스트리에 도구를 등록합니다.
리소스 가져오기 및 등록: 서버가 리소스를 노출하는 경우 이를 가져와 등록합니다.

실행 계층 (`mcp-tool.ts`)

발견된 각 MCP 도구는 DiscoveredMCPTool 인스턴스로 래핑되며, 이 인스턴스는 다음을 수행합니다:

확인 로직 처리: 서버 신뢰 설정 및 사용자 기본 설정에 따라 확인 로직을 처리합니다.
도구 실행 관리: 적절한 매개변수로 MCP 서버를 호출하여 도구 실행을 관리합니다.
응답 처리: LLM 컨텍스트 및 사용자 표시를 위해 응답을 처리합니다.
연결 상태 유지: 연결 상태를 유지하고 타임아웃을 처리합니다.

전송 메커니즘

Gemini CLI는 세 가지 MCP 전송 유형을 지원합니다:

Stdio 전송: 하위 프로세스를 생성하고 stdin/stdout을 통해 통신합니다.
SSE 전송: Server-Sent Events 엔드포인트에 연결합니다.
Streamable HTTP 전송: 통신에 HTTP 스트리밍을 사용합니다.

MCP 리소스 작업

일부 MCP 서버는 도구 및 프롬프트 외에도 컨텍스트 "리소스"를 노출합니다. Gemini CLI는 이를 자동으로 발견하고 채팅에서 참조할 수 있는 기능을 제공합니다.

발견 및 나열

발견이 실행되면 CLI는 각 서버의 resources/list 결과를 가져옵니다.
/mcp 명령은 모든 연결된 서버에 대해 도구 및 프롬프트와 함께 리소스 섹션을 표시합니다.

이는 URI와 메타데이터의 간결한 일반 텍스트 목록을 반환합니다.

대화에서 리소스 참조하기

로컬 파일을 참조할 때 이미 알려진 @ 구문을 사용할 수 있습니다:

@server://resource/path

리소스 URI는 파일 시스템 경로와 함께 완성 메뉴에 나타납니다. 메시지를 제출하면 CLI가 resources/read를 호출하고 내용을 대화에 주입합니다.

MCP 서버 설정 방법

Gemini CLI는 settings.json 파일의 mcpServers 구성을 사용하여 MCP 서버를 찾고 연결합니다. 이 구성은 다양한 전송 메커니즘을 가진 여러 서버를 지원합니다.

settings.json에서 MCP 서버 구성

settings.json 파일에서 MCP 서버를 구성하는 두 가지 주요 방법이 있습니다: 구체적인 서버 정의를 위한 최상위 mcpServers 객체와 서버 발견 및 실행을 제어하는 전역 설정을 위한 mcp 객체를 통해서입니다.

전역 MCP 설정 (`mcp`)

settings.json의 mcp 객체를 사용하면 모든 MCP 서버에 대한 전역 규칙을 정의할 수 있습니다.

mcp.serverCommand (문자열): MCP 서버를 시작하기 위한 전역 명령입니다.
mcp.allowed (문자열 배열): 허용할 MCP 서버 이름 목록입니다. 이것이 설정되면 이 목록에 있는 서버(mcpServers 객체의 키와 일치)만 연결됩니다.
mcp.excluded (문자열 배열): 제외할 MCP 서버 이름 목록입니다. 이 목록에 있는 서버에는 연결되지 않습니다.

예:

{
  "mcp": {
    "allowed": ["my-trusted-server"],
    "excluded": ["experimental-server"]
  }
}

서버별 구성 (`mcpServers`)

mcpServers 객체는 CLI가 연결할 각 개별 MCP 서버를 정의하는 곳입니다.

구성 구조

settings.json 파일에 mcpServers 객체를 추가하세요:

{ ...file contains other config objects
  "mcpServers": {
    "serverName": {
      "command": "path/to/server",
      "args": ["--arg1", "value1"],
      "env": {
        "API_KEY": "$MY_API_TOKEN"
      },
      "cwd": "./server-directory",
      "timeout": 30000,
      "trust": false
    }
  }
}

구성 속성

각 서버 구성은 다음 속성을 지원합니다:

필수 (다음 중 하나)

command (문자열): Stdio 전송을 위한 실행 파일 경로
url (문자열): SSE 엔드포인트 URL (예: "http://localhost:8080/sse")
httpUrl (문자열): HTTP 스트리밍 엔드포인트 URL

선택 사항

args (문자열[]): Stdio 전송을 위한 명령줄 인수
headers (객체): url 또는 httpUrl 사용 시 사용자 지정 HTTP 헤더
env (객체): 서버 프로세스에 대한 환경 변수. 값은 $VAR_NAME 또는 ${VAR_NAME} 구문을 사용하여 환경 변수를 참조할 수 있습니다.
cwd (문자열): Stdio 전송을 위한 작업 디렉터리
timeout (숫자): 요청 타임아웃(밀리초) (기본값: 600,000ms = 10분)
trust (부울): true일 경우, 이 서버에 대한 모든 도구 호출 확인을 건너뜁니다 (기본값: false).
includeTools (문자열[]): 이 MCP 서버에서 포함할 도구 이름 목록입니다. 지정하면 이 서버에서는 여기에 나열된 도구만 사용할 수 있습니다(허용 목록 동작). 지정하지 않으면 서버의 모든 도구가 기본적으로 활성화됩니다.
excludeTools (문자열[]): 이 MCP 서버에서 제외할 도구 이름 목록입니다. 여기에 나열된 도구는 서버에서 노출하더라도 모델에서 사용할 수 없습니다. 참고: excludeTools는 includeTools보다 우선순위가 높습니다. 도구가 두 목록에 모두 있으면 제외됩니다.
targetAudience (문자열): 액세스하려는 IAP 보호 애플리케이션에 허용된 OAuth 클라이언트 ID입니다. authProviderType: 'service_account_impersonation'과 함께 사용됩니다.
targetServiceAccount (문자열): 가장할 Google Cloud 서비스 계정의 이메일 주소입니다. authProviderType: 'service_account_impersonation'과 함께 사용됩니다.

원격 MCP 서버에 대한 OAuth 지원

Gemini CLI는 SSE 또는 HTTP 전송을 사용하는 원격 MCP 서버에 대한 OAuth 2.0 인증을 지원합니다. 이를 통해 인증이 필요한 MCP 서버에 안전하게 액세스할 수 있습니다.

자동 OAuth 발견

OAuth 발견을 지원하는 서버의 경우, OAuth 구성을 생략하고 CLI가 자동으로 발견하도록 할 수 있습니다:

{
  "mcpServers": {
    "discoveredServer": {
      "url": "https://api.example.com/sse"
    }
  }
}

CLI는 자동으로 다음을 수행합니다:

서버가 OAuth 인증을 요구할 때 감지 (401 응답)
서버 메타데이터에서 OAuth 엔드포인트 발견
지원되는 경우 동적 클라이언트 등록 수행
OAuth 흐름 및 토큰 관리 처리

인증 흐름

OAuth 지원 서버에 연결할 때:

초기 연결 시도가 401 Unauthorized로 실패
OAuth 발견이 권한 부여 및 토큰 엔드포인트를 찾음
사용자 인증을 위해 브라우저가 열림 (로컬 브라우저 액세스 필요)
인증 코드가 액세스 토큰으로 교환됨
토큰이 안전하게 저장됨 (미래 사용을 위해)
유효한 토큰으로 연결 재시도 성공

브라우저 리디렉션 요구 사항

중요: OAuth 인증을 위해서는 로컬 머신이 다음을 수행할 수 있어야 합니다:

인증을 위한 웹 브라우저 열기
http://localhost:7777/oauth/callback에서 리디렉션 수신

이 기능은 다음 환경에서는 작동하지 않습니다:

브라우저 액세스가 없는 헤드리스 환경
X11 포워딩 없는 원격 SSH 세션
브라우저 지원이 없는 컨테이너화된 환경

OAuth 인증 관리

/mcp auth 명령을 사용하여 OAuth 인증을 관리하세요:

# 인증이 필요한 서버 나열
/mcp auth
 
# 특정 서버로 인증
/mcp auth serverName
 
# 토큰이 만료된 경우 재인증
/mcp auth serverName

OAuth 구성 속성

enabled (부울): 이 서버에 대해 OAuth 활성화
clientId (문자열): OAuth 클라이언트 식별자 (동적 등록 시 선택 사항)
clientSecret (문자열): OAuth 클라이언트 비밀 (공용 클라이언트의 경우 선택 사항)
authorizationUrl (문자열): OAuth 권한 부여 엔드포인트 (생략 시 자동 발견)
tokenUrl (문자열): OAuth 토큰 엔드포인트 (생략 시 자동 발견)
scopes (문자열[]): 필수 OAuth 범위
redirectUri (문자열): 사용자 지정 리디렉션 URI (기본값 http://localhost:7777/oauth/callback)
tokenParamName (문자열): SSE URL의 토큰 쿼리 매개변수 이름
audiences (문자열[]): 토큰이 유효한 대상

토큰 관리

OAuth 토큰은 자동으로:

~/.gemini/mcp-oauth-tokens.json에 안전하게 저장됩니다.
만료 시 새로 고침됩니다 (새로 고침 토큰이 있는 경우).
각 연결 시도 전에 유효성 검사됩니다.
유효하지 않거나 만료된 경우 정리됩니다.

인증 공급자 유형

authProviderType 속성을 사용하여 인증 공급자 유형을 지정할 수 있습니다:

authProviderType (문자열): 인증 공급자를 지정합니다. 다음 중 하나일 수 있습니다:
- dynamic_discovery (기본값): CLI가 서버에서 OAuth 구성을 자동으로 발견합니다.
- google_credentials: CLI가 Google 애플리케이션 기본 자격 증명(ADC)을 사용하여 서버에 인증합니다. 이 공급자를 사용할 때는 필수 범위를 지정해야 합니다.
- service_account_impersonation: CLI가 Google Cloud 서비스 계정을 가장하여 서버에 인증합니다. IAP로 보호되는 서비스에 액세스할 때 유용합니다(Cloud Run 서비스를 위해 특별히 설계됨).

Google 자격 증명

{
  "mcpServers": {
    "googleCloudServer": {
      "httpUrl": "https://my-gcp-service.run.app/mcp",
      "authProviderType": "google_credentials",
      "oauth": {
        "scopes": ["https://www.googleapis.com/auth/userinfo.email"]
      }
    }
  }
}

서비스 계정 가장(Impersonation)

서비스 계정 가장을 사용하여 서버에 인증하려면 authProviderType을 service_account_impersonation으로 설정하고 다음 속성을 제공해야 합니다:

targetAudience (문자열): 액세스하려는 IAP 보호 애플리케이션에 허용된 OAuth 클라이언트 ID입니다.
targetServiceAccount (문자열): 가장할 Google Cloud 서비스 계정의 이메일 주소입니다.

CLI는 로컬 애플리케이션 기본 자격 증명(ADC)을 사용하여 지정된 서비스 계정 및 대상에 대한 OIDC ID 토큰을 생성합니다. 그런 다음 이 토큰을 사용하여 MCP 서버에 인증합니다.

설정 지침

OAuth 2.0 클라이언트 ID를 생성 (opens in a new tab)하거나 기존 ID를 사용합니다. 기존 OAuth 2.0 클라이언트 ID를 사용하려면 OAuth 클라이언트 공유 방법 (opens in a new tab)의 단계를 따르세요.
애플리케이션의 프로그래밍 방식 액세스 (opens in a new tab)를 위해 허용 목록에 OAuth ID를 추가합니다. Cloud Run은 아직 gcloud iap에서 지원되는 리소스 유형이 아니므로 프로젝트에서 클라이언트 ID를 허용 목록에 추가해야 합니다.
서비스 계정을 생성합니다. 문서 (opens in a new tab), Cloud Console 링크 (opens in a new tab)
Cloud Run 서비스 자체의 "보안(Security)" 탭 또는 gcloud를 통해 IAP 정책에 서비스 계정과 사용자를 모두 추가합니다.
MCP 서버에 액세스할 모든 사용자 및 그룹에게 서비스 계정을 가장 (opens in a new tab)하는 데 필요한 권한(즉, roles/iam.serviceAccountTokenCreator)을 부여합니다.
프로젝트에 대해 IAM Credentials API를 활성화 (opens in a new tab)합니다.

구성 예시

Python MCP 서버 (stdio)

{
  "mcpServers": {
    "pythonTools": {
      "command": "python",
      "args": ["-m", "my_mcp_server", "--port", "8080"],
      "cwd": "./mcp-servers/python",
      "env": {
        "DATABASE_URL": "$DB_CONNECTION_STRING",
        "API_KEY": "${EXTERNAL_API_KEY}"
      },
      "timeout": 15000
    }
  }
}

Node.js MCP 서버 (stdio)

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["dist/server.js", "--verbose"],
      "cwd": "./mcp-servers/node",
      "trust": true
    }
  }
}

Docker 기반 MCP 서버

{
  "mcpServers": {
    "dockerizedServer": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-v",
        "${PWD}:/workspace",
        "my-mcp-server:latest"
      ],
      "env": {
        "API_KEY": "$EXTERNAL_SERVICE_TOKEN"
      }
    }
  }
}

HTTP 기반 MCP 서버

{
  "mcpServers": {
    "httpServer": {
      "httpUrl": "http://localhost:3000/mcp",
      "timeout": 5000
    }
  }
}

사용자 지정 헤더가 있는 HTTP 기반 MCP 서버

{
  "mcpServers": {
    "httpServerWithAuth": {
      "httpUrl": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer your-api-token",
        "X-Custom-Header": "custom-value",
        "Content-Type": "application/json"
      },
      "timeout": 5000
    }
  }
}

도구 필터링이 있는 MCP 서버

{
  "mcpServers": {
    "filteredServer": {
      "command": "python",
      "args": ["-m", "my_mcp_server"],
      "includeTools": ["safe_tool", "file_reader", "data_processor"],
      // "excludeTools": ["dangerous_tool", "file_deleter"],
      "timeout": 30000
    }
  }
}

SA 가장이 있는 SSE MCP 서버

{
  "mcpServers": {
    "myIapProtectedServer": {
      "url": "https://my-iap-service.run.app/sse",
      "authProviderType": "service_account_impersonation",
      "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com",
      "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com"
    }
  }
}

발견 프로세스 심층 분석

Gemini CLI가 시작되면 다음의 상세한 프로세스를 통해 MCP 서버 발견을 수행합니다:

1. 서버 반복 및 연결

mcpServers에 구성된 각 서버에 대해:

상태 추적 시작: 서버 상태가 CONNECTING으로 설정됩니다.
전송 선택: 구성 속성에 따름:
- httpUrl → StreamableHTTPClientTransport
- url → SSEClientTransport
- command → StdioClientTransport
연결 수립: MCP 클라이언트가 구성된 타임아웃 내에 연결을 시도합니다.
오류 처리: 연결 실패 시 로그를 기록하고 서버 상태를 DISCONNECTED로 설정합니다.

2. 도구 발견

연결 성공 시:

도구 나열: 클라이언트가 MCP 서버의 도구 나열 엔드포인트를 호출합니다.
스키마 유효성 검사: 각 도구의 함수 선언에 대한 유효성을 검사합니다.
도구 필터링: includeTools 및 excludeTools 구성을 기반으로 도구를 필터링합니다.
이름 위생 처리: Gemini API 요구 사항을 충족하도록 도구 이름을 정리합니다:
- 잘못된 문자(비 영숫자, 밑줄, 점, 하이픈)는 밑줄로 대체됩니다.
- 63자를 초과하는 이름은 중간 대체(___)로 잘립니다.

3. 충돌 해결

여러 서버가 동일한 이름의 도구를 노출할 때:

첫 번째 등록 우선: 도구 이름을 등록한 첫 번째 서버가 접두사 없는 이름을 가져갑니다.
자동 접두사: 후속 서버는 접두사가 붙은 이름을 받습니다: serverName__toolName
레지스트리 추적: 도구 레지스트리는 서버 이름과 해당 도구 간의 매핑을 유지합니다.

4. 스키마 처리

도구 매개변수 스키마는 Gemini API 호환성을 위해 위생 처리를 거칩니다:

$schema 속성 제거
additionalProperties 제거
**anyOf와 default**가 함께 있는 경우 기본값 제거 (Vertex AI 호환성)
중첩된 스키마에 재귀적 처리 적용

5. 연결 관리

발견 후:

지속적인 연결: 도구를 성공적으로 등록한 서버는 연결을 유지합니다.
정리: 사용 가능한 도구를 제공하지 않는 서버는 연결이 닫힙니다.
상태 업데이트: 최종 서버 상태가 CONNECTED 또는 DISCONNECTED로 설정됩니다.

도구 실행 흐름

Gemini 모델이 MCP 도구를 사용하기로 결정하면 다음 실행 흐름이 발생합니다:

1. 도구 호출

모델은 다음과 함께 FunctionCall을 생성합니다:

도구 이름: 등록된 이름 (잠재적으로 접두사 포함)
인수: 도구의 매개변수 스키마와 일치하는 JSON 객체

2. 확인 프로세스

각 DiscoveredMCPTool은 정교한 확인 로직을 구현합니다:

신뢰 기반 우회

if (this.trust) {
  return false; // 확인 필요 없음
}

동적 허용 목록

시스템은 다음에 대한 내부 허용 목록을 유지합니다:

서버 수준: serverName → 이 서버의 모든 도구를 신뢰함
도구 수준: serverName.toolName → 이 특정 도구를 신뢰함

사용자 선택 처리

확인이 필요한 경우 사용자가 선택할 수 있습니다:

한 번 진행: 이번만 실행
이 도구 항상 허용: 도구 수준 허용 목록에 추가
이 서버 항상 허용: 서버 수준 허용 목록에 추가
취소: 실행 중단

3. 실행

확인(또는 신뢰 우회) 시:

매개변수 준비: 인수가 도구의 스키마에 대해 유효한지 검사합니다.

MCP 호출: 기본 CallableTool이 다음을 사용하여 서버를 호출합니다:

const functionCalls = [
  {
    name: this.serverToolName, // 원본 서버 도구 이름
    args: params,
  },
];

응답 처리: 결과는 LLM 컨텍스트와 사용자 표시 모두를 위해 포맷팅됩니다.

4. 응답 처리

실행 결과는 다음을 포함합니다:

llmContent: 언어 모델의 컨텍스트를 위한 원시 응답 부분
returnDisplay: 사용자 표시를 위한 형식이 지정된 출력 (종종 마크다운 코드 블록 내의 JSON)

MCP 서버와 상호 작용하는 방법

`/mcp` 명령 사용

/mcp 명령은 MCP 서버 설정에 대한 포괄적인 정보를 제공합니다:

/mcp

이는 다음을 표시합니다:

서버 목록: 구성된 모든 MCP 서버
연결 상태: CONNECTED, CONNECTING, 또는 DISCONNECTED
서버 세부 정보: 구성 요약 (민감한 데이터 제외)
사용 가능한 도구: 각 서버의 도구 목록 및 설명
발견 상태: 전체 발견 프로세스 상태

`/mcp` 출력 예시

MCP Servers Status:

📡 pythonTools (CONNECTED)
  Command: python -m my_mcp_server --port 8080
  Working Directory: ./mcp-servers/python
  Timeout: 15000ms
  Tools: calculate_sum, file_analyzer, data_processor

🔌 nodeServer (DISCONNECTED)
  Command: node dist/server.js --verbose
  Error: Connection refused

🐳 dockerizedServer (CONNECTED)
  Command: docker run -i --rm -e API_KEY my-mcp-server:latest
  Tools: docker__deploy, docker__status

Discovery State: COMPLETED

도구 사용법

발견된 MCP 도구는 기본 제공 도구처럼 Gemini 모델에서 사용할 수 있습니다. 모델은 자동으로 다음을 수행합니다:

요청에 따라 적절한 도구 선택
확인 대화 상자 표시 (서버가 신뢰되지 않은 경우)
적절한 매개변수로 도구 실행
사용자 친화적인 형식으로 결과 표시

상태 모니터링 및 문제 해결

연결 상태

MCP 통합은 여러 상태를 추적합니다:

서버 상태 (`MCPServerStatus`)

DISCONNECTED: 서버가 연결되지 않았거나 오류가 있음
CONNECTING: 연결 시도 중
CONNECTED: 서버가 연결되어 준비됨

발견 상태 (`MCPDiscoveryState`)

NOT_STARTED: 발견이 시작되지 않음
IN_PROGRESS: 현재 서버 발견 중
COMPLETED: 발견 완료 (오류 유무 관계없음)

일반적인 문제 및 해결 방법

서버가 연결되지 않음

증상: 서버 상태가 DISCONNECTED로 표시됨

문제 해결:

구성 확인: command, args, cwd가 올바른지 확인하세요.
수동 테스트: 서버 명령을 직접 실행하여 작동하는지 확인하세요.
종속성 확인: 필요한 모든 패키지가 설치되어 있는지 확인하세요.
로그 검토: CLI 출력에서 오류 메시지를 찾으세요.
권한 확인: CLI가 서버 명령을 실행할 수 있는지 확인하세요.

도구가 발견되지 않음

증상: 서버는 연결되지만 사용 가능한 도구가 없음

문제 해결:

도구 등록 확인: 서버가 실제로 도구를 등록하는지 확인하세요.
MCP 프로토콜 확인: 서버가 MCP 도구 목록을 올바르게 구현하는지 확인하세요.
서버 로그 검토: 서버 측 오류에 대해 stderr 출력을 확인하세요.
도구 나열 테스트: 서버의 도구 발견 엔드포인트를 수동으로 테스트하세요.

도구가 실행되지 않음

증상: 도구가 발견되지만 실행 중 실패함

문제 해결:

매개변수 유효성 검사: 도구가 예상되는 매개변수를 허용하는지 확인하세요.
스키마 호환성: 입력 스키마가 유효한 JSON 스키마인지 확인하세요.
오류 처리: 도구가 처리되지 않은 예외를 던지는지 확인하세요.
타임아웃 문제: timeout 설정을 늘려보세요.

샌드박스 호환성

증상: 샌드박싱이 활성화되었을 때 MCP 서버가 실패함

해결 방법:

Docker 기반 서버: 모든 종속성을 포함하는 Docker 컨테이너를 사용하세요.
경로 접근성: 서버 실행 파일이 샌드박스에서 사용 가능한지 확인하세요.
네트워크 액세스: 필요한 네트워크 연결을 허용하도록 샌드박스를 구성하세요.
환경 변수: 필요한 환경 변수가 전달되는지 확인하세요.

디버깅 팁

디버그 모드 활성화: 자세한 출력을 위해 --debug로 CLI를 실행하세요 (대화형 모드에서 디버그 콘솔을 열려면 F12 사용).
stderr 확인: MCP 서버 stderr가 캡처되어 기록됩니다 (INFO 메시지는 필터링됨).
테스트 격리: 통합하기 전에 MCP 서버를 독립적으로 테스트하세요.
점진적 설정: 복잡한 기능을 추가하기 전에 간단한 도구로 시작하세요.
/mcp 자주 사용: 개발 중 서버 상태를 모니터링하세요.

중요 사항

보안 고려 사항

신뢰 설정: trust 옵션은 모든 확인 대화 상자를 우회합니다. 완전히 제어할 수 있는 서버에 대해서만 주의해서 사용하세요.
액세스 토큰: API 키나 토큰이 포함된 환경 변수를 구성할 때 보안에 유의하세요.
환경 변수 수정(Redaction): 기본적으로 Gemini CLI는 stdio 전송을 사용하여 MCP 서버를 생성할 때 민감한 환경 변수(GEMINI_API_KEY, GOOGLE_API_KEY, 그리고 *TOKEN*, *SECRET*, *PASSWORD*와 같은 패턴과 일치하는 변수)를 수정합니다. 이는 자격 증명이 제3자 서버에 의도치 않게 노출되는 것을 방지합니다.
명시적 환경 변수: 특정 환경 변수를 MCP 서버에 전달해야 하는 경우, settings.json의 서버 구성에 있는 env 속성에 명시적으로 정의해야 합니다.
샌드박스 호환성: 샌드박싱 사용 시, MCP 서버가 샌드박스 환경 내에서 사용 가능한지 확인하세요.
개인 데이터: 광범위한 범위의 개인 액세스 토큰을 사용하면 저장소 간 정보 유출로 이어질 수 있습니다.
신뢰할 수 없는 서버: 신뢰할 수 없거나 제3자 소스에서 MCP 서버를 추가할 때 매우 주의하세요. 악성 서버는 노출된 도구를 통해 데이터를 유출하거나 승인되지 않은 작업을 수행하려고 시도할 수 있습니다.

성능 및 리소스 관리

연결 지속성: CLI는 도구를 성공적으로 등록한 서버에 대해 지속적인 연결을 유지합니다.
자동 정리: 도구를 제공하지 않는 서버에 대한 연결은 자동으로 닫힙니다.
타임아웃 관리: 서버의 응답 특성에 따라 적절한 타임아웃을 구성하세요.
리소스 모니터링: MCP 서버는 별도의 프로세스로 실행되며 시스템 리소스를 소비합니다.

스키마 호환성

속성 제거: 시스템은 Gemini API 호환성을 위해 특정 스키마 속성($schema, additionalProperties)을 자동으로 제거합니다.
이름 위생 처리: 도구 이름은 API 요구 사항을 충족하도록 자동으로 정리됩니다.
충돌 해결: 서버 간의 도구 이름 충돌은 자동 접두사를 통해 해결됩니다.

이 포괄적인 통합을 통해 MCP 서버는 보안, 신뢰성 및 사용 편의성을 유지하면서 Gemini CLI의 기능을 확장하는 강력한 방법이 됩니다.

도구에서 풍부한 콘텐츠 반환

MCP 도구는 단순한 텍스트 반환에만 국한되지 않습니다. 단일 도구 응답으로 텍스트, 이미지, 오디오 및 기타 바이너리 데이터를 포함한 풍부한 멀티 파트 콘텐츠를 반환할 수 있습니다. 이를 통해 한 번의 턴으로 모델에 다양한 정보를 제공할 수 있는 강력한 도구를 구축할 수 있습니다.

도구에서 반환된 모든 데이터는 처리되어 모델의 다음 생성을 위한 컨텍스트로 전송되므로, 모델이 제공된 정보를 추론하거나 요약할 수 있습니다.

작동 방식

풍부한 콘텐츠를 반환하려면 도구의 응답이 CallToolResult (opens in a new tab)에 대한 MCP 사양을 준수해야 합니다. 결과의 content 필드는 ContentBlock 객체의 배열이어야 합니다. Gemini CLI는 이 배열을 올바르게 처리하여 텍스트와 바이너리 데이터를 분리하고 모델을 위해 패키징합니다.

content 배열에서 다양한 콘텐츠 블록 유형을 혼합하여 사용할 수 있습니다. 지원되는 블록 유형은 다음과 같습니다:

text
image
audio
resource (임베디드 콘텐츠)
resource_link

예시: 텍스트 및 이미지 반환

다음은 텍스트 설명과 이미지를 모두 반환하는 MCP 도구의 유효한 JSON 응답 예시입니다:

{
  "content": [
    {
      "type": "text",
      "text": "Here is the logo you requested."
    },
    {
      "type": "image",
      "data": "BASE64_ENCODED_IMAGE_DATA_HERE",
      "mimeType": "image/png"
    },
    {
      "type": "text",
      "text": "The logo was created in 2025."
    }
  ]
}

Gemini CLI가 이 응답을 받으면 다음을 수행합니다:

모든 텍스트를 추출하여 모델을 위한 단일 functionResponse 부분으로 결합합니다.
이미지 데이터를 별도의 inlineData 부분으로 표시합니다.
텍스트와 이미지가 모두 수신되었음을 나타내는 깔끔하고 사용자 친화적인 요약을 CLI에 제공합니다.

이를 통해 Gemini 모델에 풍부한 멀티모달 컨텍스트를 제공할 수 있는 정교한 도구를 구축할 수 있습니다.

슬래시 명령으로서의 MCP 프롬프트

도구 외에도 MCP 서버는 Gemini CLI 내에서 슬래시 명령으로 실행할 수 있는 미리 정의된 프롬프트를 노출할 수 있습니다. 이를 통해 이름으로 쉽게 호출할 수 있는 일반적이거나 복잡한 쿼리에 대한 바로 가기를 만들 수 있습니다.

서버에 프롬프트 정의하기

다음은 프롬프트를 정의하는 stdio MCP 서버의 간단한 예입니다:

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from 'zod';
 
const server = new McpServer({
  name: 'prompt-server',
  version: '1.0.0',
});
 
server.registerPrompt(
  'poem-writer',
  {
    title: 'Poem Writer',
    description: 'Write a nice haiku',
    argsSchema: { title: z.string(), mood: z.string().optional() },
  },
  ({ title, mood }) => ({
    messages: [
      {
        role: 'user',
        content: {
          type: 'text',
          text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `,
        },
      },
    ],
  }),
);
 
const transport = new StdioServerTransport();
await server.connect(transport);

이것은 settings.json의 mcpServers 아래에 다음과 같이 포함될 수 있습니다:

{
  "mcpServers": {
    "nodeServer": {
      "command": "node",
      "args": ["filename.ts"]
    }
  }
}

프롬프트 호출

프롬프트가 발견되면 이름을 슬래시 명령으로 사용하여 호출할 수 있습니다. CLI는 자동으로 인수 파싱을 처리합니다.

/poem-writer --title="Gemini CLI" --mood="reverent"

또는 위치 인수를 사용하여:

/poem-writer "Gemini CLI" reverent

이 명령을 실행하면 Gemini CLI는 제공된 인수와 함께 MCP 서버에서 prompts/get 메서드를 실행합니다. 서버는 템플릿에 인수를 대입하고 최종 프롬프트 텍스트를 반환할 책임이 있습니다. 그러면 CLI가 이 프롬프트를 실행을 위해 모델로 전송합니다. 이는 일반적인 워크플로를 자동화하고 공유하는 편리한 방법을 제공합니다.

`gemini mcp`로 MCP 서버 관리

settings.json 파일을 수동으로 편집하여 언제든지 MCP 서버를 구성할 수 있지만, Gemini CLI는 프로그래밍 방식으로 서버 구성을 관리하는 편리한 명령 세트를 제공합니다. 이 명령들은 JSON 파일을 직접 편집할 필요 없이 MCP 서버를 추가, 나열 및 제거하는 과정을 간소화합니다.

서버 추가 (`gemini mcp add`)

add 명령은 settings.json에 새 MCP 서버를 구성합니다. 범위(-s, --scope)에 따라 사용자 구성 ~/.gemini/settings.json 또는 프로젝트 구성 .gemini/settings.json 파일에 추가됩니다.

명령:

gemini mcp add [options] <name> <commandOrUrl> [args...]

<name>: 서버의 고유 이름입니다.
<commandOrUrl>: 실행할 명령(stdio용) 또는 URL(http/sse용)입니다.
[args...]: stdio 명령에 대한 선택적 인수입니다.

옵션 (플래그):

-s, --scope: 구성 범위 (user 또는 project). [기본값: "project"]
-t, --transport: 전송 유형 (stdio, sse, http). [기본값: "stdio"]
-e, --env: 환경 변수 설정 (예: -e KEY=value).
-H, --header: SSE 및 HTTP 전송을 위한 HTTP 헤더 설정 (예: -H "X-Api-Key: abc123" -H "Authorization: Bearer abc123").
--timeout: 연결 타임아웃(밀리초) 설정.
--trust: 서버 신뢰 (모든 도구 호출 확인 프롬프트 우회).
--description: 서버 설명 설정.
--include-tools: 포함할 도구의 쉼표로 구분된 목록.
--exclude-tools: 제외할 도구의 쉼표로 구분된 목록.

stdio 서버 추가

로컬 서버를 실행하기 위한 기본 전송입니다.

# 기본 구문
gemini mcp add [options] <name> <command> [args...]
 
# 예: 로컬 서버 추가
gemini mcp add -e API_KEY=123 -e DEBUG=true my-stdio-server /path/to/server arg1 arg2 arg3
 
# 예: 로컬 python 서버 추가
gemini mcp add python-server python server.py -- --server-arg my-value

HTTP 서버 추가

스트리밍 가능한 HTTP 전송을 사용하는 서버를 위한 전송입니다.

# 기본 구문
gemini mcp add --transport http <name> <url>
 
# 예: HTTP 서버 추가
gemini mcp add --transport http http-server https://api.example.com/mcp/
 
# 예: 인증 헤더가 있는 HTTP 서버 추가
gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/

SSE 서버 추가

Server-Sent Events (SSE)를 사용하는 서버를 위한 전송입니다.

# 기본 구문
gemini mcp add --transport sse <name> <url>
 
# 예: SSE 서버 추가
gemini mcp add --transport sse sse-server https://api.example.com/sse/
 
# 예: 인증 헤더가 있는 SSE 서버 추가
gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/

서버 나열 (`gemini mcp list`)

현재 구성된 모든 MCP 서버를 보려면 list 명령을 사용하세요. 각 서버의 이름, 구성 세부 정보 및 연결 상태를 표시합니다. 이 명령에는 플래그가 없습니다.

명령:

gemini mcp list

출력 예시:

✓ stdio-server: command: python3 server.py (stdio) - Connected
✓ http-server: https://api.example.com/mcp (http) - Connected
✗ sse-server: https://api.example.com/sse (sse) - Disconnected

서버 제거 (`gemini mcp remove`)

구성에서 서버를 삭제하려면 서버 이름과 함께 remove 명령을 사용하세요.

명령:

gemini mcp remove <name>

옵션 (플래그):

-s, --scope: 구성 범위 (user 또는 project). [기본값: "project"]

예:

gemini mcp remove my-server

이 명령은 범위(-s, --scope)에 따라 적절한 settings.json 파일의 mcpServers 객체에서 "my-server" 항목을 찾아 삭제합니다.

서버 활성화/비활성화 (`gemini mcp enable`, `gemini mcp disable`)

구성을 제거하지 않고 일시적으로 MCP 서버를 비활성화하거나 이전에 비활성화된 서버를 다시 활성화합니다.

명령:

gemini mcp enable <name> [--session]
gemini mcp disable <name> [--session]

옵션 (플래그):

--session: 변경 사항을 현재 세션에만 적용 (파일에 저장되지 않음).

비활성화된 서버는 /mcp 상태에서 "Disabled"로 표시되며 연결되거나 도구를 제공하지 않습니다. 활성화 상태는 ~/.gemini/mcp-server-enablement.json에 저장됩니다.

동일한 명령을 활성 세션 중에 슬래시 명령으로 사용할 수 있습니다: /mcp enable <name> 및 /mcp disable <name>.

지침

Gemini CLI는 MCP 서버 지침 (opens in a new tab)을 지원하며, 이는 시스템 지침에 추가됩니다.

IDE 통합 확장 프로그램 시작하기

Gemini CLI의 MCP 서버

MCP 서버란 무엇인가요?

핵심 통합 아키텍처

발견 계층 (mcp-client.ts)

실행 계층 (mcp-tool.ts)

전송 메커니즘

MCP 리소스 작업

발견 및 나열

대화에서 리소스 참조하기

MCP 서버 설정 방법

settings.json에서 MCP 서버 구성

전역 MCP 설정 (mcp)

서버별 구성 (mcpServers)

구성 구조

구성 속성

필수 (다음 중 하나)

선택 사항

원격 MCP 서버에 대한 OAuth 지원

자동 OAuth 발견

인증 흐름

브라우저 리디렉션 요구 사항

OAuth 인증 관리

OAuth 구성 속성

토큰 관리

인증 공급자 유형

Google 자격 증명

서비스 계정 가장(Impersonation)

설정 지침

구성 예시

Python MCP 서버 (stdio)

Node.js MCP 서버 (stdio)

Docker 기반 MCP 서버

HTTP 기반 MCP 서버

사용자 지정 헤더가 있는 HTTP 기반 MCP 서버

도구 필터링이 있는 MCP 서버

SA 가장이 있는 SSE MCP 서버

발견 프로세스 심층 분석

1. 서버 반복 및 연결

2. 도구 발견

3. 충돌 해결

4. 스키마 처리

5. 연결 관리

도구 실행 흐름

1. 도구 호출

2. 확인 프로세스

신뢰 기반 우회

동적 허용 목록

사용자 선택 처리

3. 실행

4. 응답 처리

MCP 서버와 상호 작용하는 방법

/mcp 명령 사용

/mcp 출력 예시

도구 사용법

상태 모니터링 및 문제 해결

연결 상태

서버 상태 (MCPServerStatus)

발견 상태 (MCPDiscoveryState)

일반적인 문제 및 해결 방법

서버가 연결되지 않음

도구가 발견되지 않음

도구가 실행되지 않음

샌드박스 호환성

디버깅 팁

중요 사항

보안 고려 사항

성능 및 리소스 관리

스키마 호환성

도구에서 풍부한 콘텐츠 반환

작동 방식

예시: 텍스트 및 이미지 반환

슬래시 명령으로서의 MCP 프롬프트

서버에 프롬프트 정의하기

프롬프트 호출

gemini mcp로 MCP 서버 관리

서버 추가 (gemini mcp add)

stdio 서버 추가

HTTP 서버 추가

SSE 서버 추가

서버 나열 (gemini mcp list)

발견 계층 (`mcp-client.ts`)

실행 계층 (`mcp-tool.ts`)

전역 MCP 설정 (`mcp`)

서버별 구성 (`mcpServers`)

`/mcp` 명령 사용

`/mcp` 출력 예시

서버 상태 (`MCPServerStatus`)

발견 상태 (`MCPDiscoveryState`)

`gemini mcp`로 MCP 서버 관리

서버 추가 (`gemini mcp add`)

서버 나열 (`gemini mcp list`)

서버 제거 (`gemini mcp remove`)

서버 활성화/비활성화 (`gemini mcp enable`, `gemini mcp disable`)