Gemini 앱 개발자 모드에서 테스트, 디버그, 평가하기

Gemini 앱 개발자 모드를 사용하면 Google Connected Console에서 검토를 위해 연결된 앱을 제출하기 전에 Model Context Protocol(MCP) 서버를 대화형으로 테스트하고, 스키마 또는 런타임 오류를 진단하고, 도구 품질을 벤치마킹할 수 있습니다.

이 가이드에서는 다음 작업을 설명합니다.

  • Gemini에서 Gemini 앱 개발자 모드를 사용 설정하고, 커스텀 MCP 앱을 만들고, 초기 도구 검색을 확인합니다.
  • 실패한 도구 호출을 디버그하고, 업데이트된 스키마를 동기화하고, 인증을 테스트합니다.
  • 사용자 환경 컨텍스트를 시뮬레이션하고 클라이언트 인증을 구성합니다.

작업공간 레이아웃 및 검사기 탭에 관한 소개는 Gemini 앱 개발자 모드 개요를 참고하세요.

Gemini 앱 개발자 모드 사용 설정

Google Connected Console에서 MCP 서버를 온보딩하는 경우 Gemini 앱 개발자 모드를 사용 설정하면 등록된 앱을 이미 사용할 수 있으며 2단계를 건너뛸 수 있습니다. 배포된 HTTPS MCP 서버 엔드포인트를 콘솔에 등록하기 전에 Gemini에서 직접 테스트하려면 두 단계를 모두 수행하여 Gemini 앱 개발자 모드를 사용 설정하고 서버를 커스텀 MCP 앱으로 연결하세요.

1단계: Gemini 앱 개발자 모드 사용 설정하기

  1. 웹브라우저에서 Gemini를 엽니다.
  2. 설정 > Gemini 앱 개발자 모드를 클릭하거나 gemini.google.com/devmode로 직접 이동합니다.

(선택사항) 2단계: 커스텀 MCP 앱 만들기 및 테스트하기

Gemini 앱 개발자 모드에서 MCP 서버를 커스텀 앱으로 연결하려면 다음 단계를 따르세요.

  1. 앱 선택 대화상자에서 + 새로 만들기를 클릭합니다.
  2. MCP 서버에 연결 대화상자에서 MCP 서버 URL에 서버의 공개 HTTPS 엔드포인트를 입력합니다. URL은 https://로 시작해야 합니다(예: https://your-app-link.com/mcp).
  3. 서버에 사전 등록된 OAuth 사용자 인증 정보가 필요한 경우 추가 설정 > 더보기를 클릭하여 OAuth 클라이언트 ID 및 클라이언트 보안 비밀번호를 입력한 후 다음을 클릭합니다.
  4. 보안 및 개인 정보 보호 확인 대화상자에서 Gemini가 커스텀 MCP 서버와 상호작용하는 방식을 검토합니다.
    • 도구 실행: Gemini는 MCP 서버의 도구를 실행하여 사용 가능한 함수를 트리거하고 실행하여 요청을 처리합니다.
    • 데이터 검색 및 공유: Gemini는 MCP 서버의 엔드포인트에서 노출하는 리소스, 스키마, 컨텍스트를 검색하고 관리하며, Google 계정 설정에 따라 또는 다른 연결된 앱과 상호작용할 때 액세스 권한이 있는 정보를 공유할 수 있습니다.
    • 신뢰 및 연결 해제: 계속 진행하기 전에 MCP 서버를 신뢰할 수 있는지 확인하고 개인정보처리방침을 검토하세요. 언제든지 연결된 앱 페이지에서 서버를 연결 해제하거나 Google 계정 연결에서 링크를 삭제할 수 있습니다.
  5. 이 맞춤 앱을 연결할 때 발생할 수 있는 보안 및 개인 정보 보호 위험을 이해했으며 이에 동의합니다를 선택한 후 연결을 클릭합니다.
  6. 커스텀 앱 저장 대화상자에서 커스텀 앱의 표시 이름을 입력하고, 서버의 도구가 사용 가능한 작업 목록에 표시되는지 확인한 후 연결을 클릭합니다.
  7. Gemini 앱 개발자 모드 측면 패널에서 도구 스키마 탭을 선택하여 연결된 앱의 각 도구에 관한 정보(매개변수 정의, 안전 배지(읽기 전용, 파괴적, 인증 필요), 원시 스키마, 응답 구조)를 검토합니다.
  8. 왼쪽 채팅 창에서 자연어 또는 @mention 프롬프트(예: @MyApp show my profile)를 입력하고 이벤트 로그 탭을 모니터링하여 도구가 어떻게 작동하는지 확인합니다.

도구 호출 디버그

도구 호출이 실패하거나 예기치 않은 인수가 생성되면 대화 기록을 지우지 않고도 진단 원격 분석을 검사하고, 백엔드 MCP 서버를 업데이트하고, 스키마를 핫 리로드할 수 있습니다.

실패한 도구 호출을 디버깅하려면 다음 단계를 따르세요.

  1. 오른쪽 창에서 이벤트 로그 탭을 선택합니다.
  2. 원격 분석 목록에서 실패한 이벤트를 클릭하여 세부정보를 펼치고 Tool call 요청 페이로드와 Tool result 응답을 검사합니다.
    • 연결 및 네트워크 오류: 오류 메시지와 지연 시간을 확인하여 엔드포인트에 연결할 수 있는지 확인합니다.
    • 인증 오류: 이벤트가 401 또는 403를 반환하는 경우 인증 탭에서 OAuth 토큰 상태 또는 클라이언트 사용자 인증 정보를 확인합니다.
    • 스키마 검증 불일치: 서버에서 MCP 잘못된 매개변수 오류(-32602)를 반환하는 경우 Tool call의 모델 생성 JSON 인수를 도구 스키마 탭의 매개변수 유형, 필수 속성, 형식 안내와 비교합니다.
    • 서버 런타임 예외: Tool result에서 JSON-RPC 오류 코드와 메시지를 검사하여 백엔드 예외를 진단합니다.
  3. 이 문제를 해결하려면 MCP 서버 구현을 업데이트하거나 도구 및 파라미터 설명을 세분화하세요. 명확한 도구 스키마와 오류 응답을 작성하는 방법에 관한 안내는 MCP 연결 앱 통합 표준을 참고하세요.
  4. 도구 스키마 탭에서 스키마 동기화를 클릭합니다. Gemini는 MCP 서버에서 tools/list를 다시 가져오고 현재 채팅 대화목록을 유지하면서 활성 도구 정의를 업데이트합니다.
  5. 쿼리를 다시 시도합니다. 이벤트 로그 탭에서 재생된 도구 호출이 200 OK를 반환하고 채팅 미리보기에 예상 응답을 렌더링하는지 확인합니다.

환경 컨텍스트 및 인증 시뮬레이션

검사기 창에서 바로 MCP 도구가 다양한 사용자 위치, 시간대, 언어, 인증 방법에 어떻게 응답하는지 테스트할 수 있습니다.

환경 컨텍스트 재정의

날짜, 시간 또는 언어에 민감한 도구의 사용자 컨텍스트를 시뮬레이션하려면 다음 단계를 따르세요.

  1. 오른쪽 창에서 환경 탭을 선택합니다.
  2. 날짜 및 시간에서 시뮬레이션된 날짜 및 시뮬레이션된 시간을 선택하여 상대 시간 표현(예: '내일 아침' 또는 '이번 주 토요일 오후')을 테스트합니다.
  3. 환경설정에서 언어를 선택하여 사용자 언어(예: en-US)를 시뮬레이션합니다.
  4. 채팅 창에서 테스트 프롬프트를 실행하여 시뮬레이션된 컨텍스트로 도구를 평가합니다.
  5. 기본 환경 설정을 복원하려면 재설정을 클릭합니다.

클라이언트 인증 구성

Gemini 앱 개발자 모드 세션 중에 사용되는 인증 방법을 구성하거나 전환하려면 다음 단계를 따르세요.

  1. 오른쪽 창에서 인증 탭을 선택합니다.
  2. 클라이언트 인증 구성에서 다음 인증 모드 중 하나를 선택합니다.
    • 동적 클라이언트 등록: OAuth 흐름을 사용하여 승인 서버와 사용자 인증 정보를 자동으로 협상합니다. 자세한 내용은 OAuth 2.1 구현 가이드를 참고하세요. 해당하는 경우 맞춤 앱 링크 추가에 엔드포인트를 입력합니다.
    • 수동 클라이언트 등록: 사전 등록된 클라이언트 ID와 클라이언트 보안 비밀번호를 수동으로 제공할 수 있습니다. 고급 설정을 펼쳐 추가 흐름 재정의를 구성합니다.
  3. 저장을 클릭하고 저장됨 메시지가 표시될 때까지 기다립니다. 그런 다음 테스트 프롬프트를 실행하여 인증된 도구가 성공하는지 확인합니다.

추가 리소스