참고: 일관되고 높은 성능의 환경을 보장하기 위해 이 실습에서는 일부 모델 요청에 대해 캐시된 응답을 제공할 수 있습니다.

GENAI124

개요

이 실습에서는 외부 서비스, 데이터 소스, 도구, 애플리케이션 간의 원활한 통합을 지원하는 개방형 표준인 모델 컨텍스트 프로토콜(MCP)을 살펴봅니다. 기존 MCP 서버에서 제공하는 도구를 사용하여 에이전트 개발 키트(ADK) 에이전트에 MCP를 통합하고 ADK 워크플로를 개선하는 방법을 알아봅니다. 또한 커스텀 빌드된 MCP 서버를 통해 load_web_page와 같은 ADK 도구를 노출하여 MCP 클라이언트와의 광범위한 통합을 지원하는 방법도 알아봅니다.

모델 컨텍스트 프로토콜(MCP)이란 무엇인가요?

모델 컨텍스트 프로토콜(MCP)은 Gemini 및 Claude와 같은 대규모 언어 모델(LLM)이 외부 애플리케이션, 데이터 소스, 도구와 통신하는 방식을 표준화하기 위해 설계된 개방형 표준입니다. LLM이 컨텍스트를 가져오고, 작업을 실행하고, 다양한 시스템과 상호작용하는 방식을 간소화하는 범용 연결 메커니즘이라고 생각하면 됩니다.

MCP는 클라이언트-서버 아키텍처를 따르며, 데이터(리소스), 상호작용형 템플릿(프롬프트), 실행 가능한 함수(도구)가 MCP 서버에 의해 노출되고 MCP 클라이언트(LLM 호스트 애플리케이션 또는 AI 에이전트)에 의해 소비되는 방식을 정의합니다.

이 실습에서는 두 가지 기본 통합 패턴을 다룹니다.

• ADK 내에서 기존 MCP 서버 사용: ADK 에이전트는 MCP 클라이언트 역할을 하며 외부 MCP 서버에서 제공하는 도구를 활용합니다.
• MCP 서버를 통한 ADK 도구 노출: ADK 도구를 래핑하는 MCP 서버를 빌드하여 모든 MCP 클라이언트가 ADK 도구에 액세스할 수 있도록 합니다.

목표

이 실습에서는 다음 작업을 수행하는 방법을 알아봅니다.

• ADK 에이전트를 MCP 클라이언트로 사용하여 기존 MCP 서버의 도구와 상호작용합니다.
• 자체 MCP 서버를 구성하고 배포하여 ADK 도구를 다른 클라이언트에 노출합니다.
• 표준화된 MCP 통신을 통해 ADK 에이전트를 외부 도구와 연결합니다.
• MCP를 사용하여 LLM과 도구 간의 원활한 상호작용을 지원합니다.

설정 및 요건

실습 시작 버튼을 클릭하기 전에

다음 안내를 확인하세요. 실습에는 시간 제한이 있으며 일시중지할 수 없습니다. 실습 시작을 클릭하면 타이머가 시작됩니다. 이 타이머는 Google Cloud 리소스를 사용할 수 있는 시간이 얼마나 남았는지를 표시합니다.

실무형 실습을 통해 시뮬레이션이나 데모 환경이 아닌 실제 클라우드 환경에서 실습 활동을 진행할 수 있습니다. 실습 시간 동안 Google Cloud에 로그인하고 액세스하는 데 사용할 수 있는 새로운 임시 사용자 인증 정보가 제공됩니다.

이 실습을 완료하려면 다음을 준비해야 합니다.

• 표준 인터넷 브라우저 액세스 권한(Chrome 브라우저 권장)

참고: 이 실습을 실행하려면 시크릿 모드(권장) 또는 시크릿 브라우저 창을 사용하세요. 개인 계정과 학습자 계정 간의 충돌로 개인 계정에 추가 요금이 발생하는 일을 방지해 줍니다.

• 실습을 완료하기에 충분한 시간(실습을 시작하고 나면 일시중지할 수 없음)

참고: 이 실습에는 학습자 계정만 사용하세요. 다른 Google Cloud 계정을 사용하는 경우 해당 계정에 비용이 청구될 수 있습니다.

실습을 시작하고 Google Cloud 콘솔에 로그인하는 방법

1. 실습 시작 버튼을 클릭합니다. 실습 비용을 결제해야 하는 경우 결제 수단을 선택할 수 있는 대화상자가 열립니다. 왼쪽에는 다음과 같은 항목이 포함된 실습 세부정보 창이 있습니다.

   • Google Cloud 콘솔 열기 버튼
   • 남은 시간
   • 이 실습에 사용해야 하는 임시 사용자 인증 정보
   • 필요한 경우 실습 진행을 위한 기타 정보

2. Google Cloud 콘솔 열기를 클릭합니다(Chrome 브라우저를 실행 중인 경우 마우스 오른쪽 버튼으로 클릭하고 시크릿 창에서 링크 열기를 선택합니다).

   실습에서 리소스가 가동되면 다른 탭이 열리고 로그인 페이지가 표시됩니다.

   팁: 두 개의 탭을 각각 별도의 창으로 나란히 정렬하세요.

   참고: 계정 선택 대화상자가 표시되면 다른 계정 사용을 클릭합니다.

3. 필요한 경우 아래의 사용자 이름을 복사하여 로그인 대화상자에 붙여넣습니다.

   {{{user_0.username | "Username"}}}

   실습 세부정보 창에서도 사용자 이름을 확인할 수 있습니다.

4. 다음을 클릭합니다.

5. 아래의 비밀번호를 복사하여 시작하기 대화상자에 붙여넣습니다.

   {{{user_0.password | "Password"}}}

   실습 세부정보 창에서도 비밀번호를 확인할 수 있습니다.

6. 다음을 클릭합니다.

   중요: 실습에서 제공하는 사용자 인증 정보를 사용해야 합니다. Google Cloud 계정 사용자 인증 정보를 사용하지 마세요. 참고: 이 실습에 자신의 Google Cloud 계정을 사용하면 추가 요금이 발생할 수 있습니다.

7. 이후에 표시되는 페이지를 클릭하여 넘깁니다.

   • 이용약관에 동의합니다.
   • 임시 계정이므로 복구 옵션이나 2단계 인증을 추가하지 않습니다.
   • 무료 체험판을 신청하지 않습니다.

잠시 후 Google Cloud 콘솔이 이 탭에서 열립니다.

참고: Google Cloud 제품 및 서비스에 액세스하려면 탐색 메뉴를 클릭하거나 검색창에 제품 또는 서비스 이름을 입력합니다.

작업 1. ADK 설치 및 환경 설정

이 실습 환경에서는 Vertex AI API, Routes API, Directions API가 사용 설정되어 있습니다.

Cloud Shell 편집기 탭 준비

1. Google Cloud 콘솔에서 Cloud 콘솔 오른쪽 상단에 있는 Cloud Shell 활성화 버튼()을 클릭합니다.
2. 계속을 클릭합니다.
3. Cloud Shell을 승인하라는 메시지가 표시되면 승인을 클릭합니다.
4. Cloud Shell 터미널 패널의 오른쪽 상단에서 새 창에서 열기 버튼()을 클릭합니다.
5. 창 상단에서 편집기 열기 아이콘()을 클릭하여 파일을 표시합니다.
6. 왼쪽 탐색 메뉴 상단에서 탐색기 아이콘()을 클릭하여 파일 탐색기를 엽니다.
7. 폴더 열기 버튼을 클릭합니다.
8. 폴더 열기 대화상자가 열리면 확인을 클릭하여 학생 계정의 홈 폴더를 선택합니다.
9. 화면 오른쪽에 표시되는 추가 튜토리얼 또는 Gemini 패널을 닫아 코드 편집기에 더 많은 공간을 확보합니다.
10. 이 실습의 나머지 부분에서는 이 창을 Cloud Shell 편집기 및 Cloud Shell 터미널이 있는 IDE로 사용할 수 있습니다.

실습에 필요한 ADK 및 코드 샘플 다운로드 및 설치

이 섹션에서는 Cloud Shell 터미널에서 다음 명령어를 실행합니다.

1. Cloud Shell 터미널에서 다음 명령어를 실행하여 Cloud Storage에서 프로젝트 디렉터리를 복사합니다.

   gcloud storage cp -r gs://{{{project_0.project_id| YOUR_GCP_PROJECT_ID}}}-bucket/* .

2. 다음 명령어를 실행하여 샘플 애플리케이션을 실행하는 데 필요한 에이전트 개발 키트(ADK)와 기타 종속 항목을 설치합니다.

   export PATH=$PATH:"/home/${USER}/.local/bin" python3 -m pip install google-adk==1.22.1 -r adk_mcp_tools/requirements.txt

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. ADK 설치 및 환경 설정

작업 2. ADK 개발 UI에서 ADK 에이전트(MCP 클라이언트로서의 ADK)와 함께 Google 지도 MCP 서버 사용

이 섹션에서는 외부 Google 지도 MCP 서버의 도구를 ADK 에이전트에 통합하는 방법을 보여줍니다. 이는 ADK 에이전트가 MCP 인터페이스를 노출하는 기존 서비스에서 제공하는 기능을 사용해야 하는 경우 가장 일반적인 통합 패턴입니다. MCPToolset 클래스를 에이전트의 tools 목록에 직접 추가하여 MCP 서버에 원활하게 연결하고, 도구를 검색하고, 에이전트가 사용할 수 있도록 만드는 방법을 알아봅니다. 이러한 예시는 주로 adk web 개발 환경 내의 상호작용에 중점을 둡니다.

MCPToolset

MCPToolset 클래스는 MCP 서버의 도구를 통합하기 위한 ADK의 기본 메커니즘입니다. 에이전트의 tools 목록에 MCPToolset 인스턴스를 포함하면 지정된 MCP 서버와의 상호작용이 자동으로 처리됩니다. 실행 방식은 다음과 같습니다.

• 연결 관리: 초기화 시 MCPToolset는 MCP 서버에 대한 연결을 설정하고 관리합니다. 이는 로컬 서버 프로세스(표준 입력/출력을 통한 통신에 StdioServerParameters 사용) 또는 원격 서버(서버 전송 이벤트에 SseServerParams 사용)일 수 있습니다. 또한 이 도구 모음은 에이전트 및 애플리케이션이 종료될 때 이 연결의 단계적 종료를 처리합니다.
• 도구 검색 및 조정: 연결되면 MCPToolset가 MCP 서버에 사용 가능한 도구를 쿼리합니다(list_tools MCP 메서드 사용). 그런 다음 발견된 MCP 도구의 스키마를 ADK 호환 BaseTool 인스턴스로 변환합니다.
• 에이전트 노출: 이와 같이 조정된 도구는 기본 ADK 도구처럼 LlmAgent에서 사용할 수 있게 됩니다.
• 도구 호출 프록시: LlmAgent가 이러한 도구 중 하나를 사용하기로 결정하면 MCPToolset는 call_tool MCP 메서드를 사용하여 MCP 서버에 대한 호출을 투명하게 프록시하고, 필요한 인수를 전송하고, 서버의 응답을 에이전트에 반환합니다.
• 필터링(선택사항): MCPToolset를 만들 때 tool_filter 파라미터를 사용하여 에이전트에 모든 도구를 노출하는 대신 MCP 서버에서 특정 도구 하위 집합을 선택할 수 있습니다.

API 키 가져오기 및 API 사용 설정

Google 지도 MCP 서버는 API 키가 있어야 Google 지도 서비스와 통신할 수 있습니다. 이 단계에서는 GOOGLE_MAPS_API_KEY라는 새 API 키를 생성하고 보안을 위해 해당 키를 Directions API 및 Routes API로 제한합니다.

1. (Cloud Shell 편집기가 아닌) Google Cloud 콘솔 브라우저 탭으로 이동합니다.

2. 이 브라우저 탭에서 Cloud Shell 터미널 창을 닫아 콘솔 영역을 넓힐 수 있습니다.

3. 페이지 상단의 검색창에서 사용자 인증 정보를 검색합니다. 검색 결과에서 선택합니다.

4. 사용자 인증 정보 페이지에서 페이지 상단의 사용자 인증 정보 만들기를 클릭한 다음 API 키를 선택합니다.

5. 이름에 GOOGLE_MAPS_API_KEY를 입력합니다.

6. 이 키를 사용하여 액세스할 수 있는 API에서 다음 API를 선택합니다.

   • Directions API
   • Routes API

7. 만들기를 클릭합니다.

   API 키 생성 완료 대화상자에 새로 만든 API 키가 표시됩니다. 실습 후반부에 사용할 수 있도록 이 키를 복사해 로컬에 저장해야 합니다.

8. 대화상자에서 닫기를 클릭합니다.

   

Google 지도의 MCPToolset로 에이전트 정의

이제 Google 지도 도구를 사용하도록 에이전트를 구성합니다. MCPToolset를 추가하면 에이전트는 필요할 때 지도 API를 동적으로 검색하고 호출할 수 있습니다.

1. 다음 명령어를 컴퓨터의 일반 텍스트 문서에 붙여넣은 다음 YOUR_ACTUAL_API_KEY 값을 이전 단계에서 생성하고 저장한 Google 지도 API 키로 업데이트합니다.

   cd ~/adk_mcp_tools cat << EOF > google_maps_mcp_agent/.env GOOGLE_GENAI_USE_VERTEXAI=TRUE GOOGLE_CLOUD_PROJECT={{{project_0.project_id | Project }}} GOOGLE_CLOUD_LOCATION=global GOOGLE_MAPS_API_KEY="YOUR_ACTUAL_API_KEY" MODEL={{{project_0.startup_script.gemini_flash_model_id | gemini_flash_model_id}}} EOF

2. 업데이트된 명령어를 Cloud Shell 터미널에 복사하여 붙여넣고 실행하여 이 에이전트 디렉터리에 대한 인증 세부정보를 제공하는 .env 파일을 작성합니다.

3. 다음 명령어를 실행하여 .env 파일을 이 실습 후반부에서 사용할 다른 에이전트 디렉터리로 복사합니다.

   cp google_maps_mcp_agent/.env adk_mcp_server/.env

4. Cloud Shell 편집기의 파일 탐색기 창에서 adk_mcp_tools 폴더를 찾습니다. 클릭하여 전환해 엽니다.

5. adk_mcp_tools/google_maps_mcp_agent 디렉터리로 이동합니다.

6. agent.py를 열고 ## Add the MCPToolset 주석(53번째 줄 다음의 새 줄) 뒤에 다음 코드를 추가하여 Google 지도 MCP 서버에 대한 에이전트의 연결을 구성합니다.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command='npx', args=[ "-y", "@modelcontextprotocol/server-google-maps", ], env={ "GOOGLE_MAPS_API_KEY": google_maps_api_key } ), timeout=15, ), ) ],

7. 파일을 저장합니다.

8. adk_mcp_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 에이전트 개발 키트 개발 UI를 실행합니다.

   adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents

   출력:

   INFO: Started server process [2434] INFO: Waiting for application startup. +----------------------------------------------------+ | ADK Web Server started | | | | For local testing, access at http://localhost:8000.| +----------------------------------------------------+ INFO: Application startup complete. INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

9. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

10. ADK 개발 UI가 표시된 새 브라우저 탭이 열립니다. 왼쪽의 에이전트 선택 드롭다운에서 google_maps_mcp_agent를 선택합니다.

11. 에이전트와 대화를 시작하고 다음 프롬프트를 실행합니다.

    Get directions from GooglePlex to SFO. 참고: API를 처음 사용할 때 API 호출 시간이 초과되면 ADK 개발 UI의 오른쪽 상단에서 + 새 세션을 클릭하고 다시 시도하세요. 프랑스 파리에서 독일 베를린까지 가는 경로가 뭐야?

    출력:

    

12. 번개 표시가 있는 에이전트의 채팅 풍선 옆에 있는 에이전트 아이콘을 클릭합니다. 번개 표시는 함수 호출을 나타냅니다. 이렇게 하면 이 이벤트의 이벤트 검사기가 열립니다.

    

    에이전트 그래프에는 렌치 이모티콘(🔧)으로 식별되는 여러 도구가 표시됩니다. MCPToolset를 하나만 가져왔지만, 이 도구 모음에는 maps_place_details와 maps_directions를 비롯한 여기에 나열된 다양한 도구가 포함되어 있습니다.

    

    이벤트 탭에서 요청의 구조를 확인할 수 있습니다. 이벤트 검사기 상단의 화살표를 사용하여 에이전트의 사고, 함수 호출, 응답을 탐색할 수 있습니다.

13. 이 에이전트에 대한 질문을 마치면 개발 UI 브라우저 탭을 닫습니다.

14. Cloud Shell 터미널 패널로 돌아가서 Ctrl+C를 눌러 서버를 중지합니다.

내 진행 상황 확인하기를 클릭하여 목표를 확인합니다. API 키 생성 및 ADK 에이전트 배포

작업 3. ADK 도구를 사용하여 MCP 서버 빌드(ADK를 노출하는 MCP 서버)

이 섹션에서는 커스텀 빌드된 MCP 서버를 통해 ADK load_web_page 도구를 노출하는 방법을 알아봅니다. 이 패턴을 사용하면 기존 ADK 도구를 래핑하여 모든 표준 MCP 클라이언트 애플리케이션에서 액세스할 수 있도록 만들 수 있습니다.

MCP 서버 스크립트 생성 및 서버 로직 구현

1. Cloud Shell 편집기로 돌아가서 adk_mcp_tools/adk_mcp_server 디렉터리를 선택합니다.

2. adk_server.py라는 Python 파일을 엽니다. 이 파일에는 커스텀 MCP 서버의 로직이 포함되어 있습니다. 코드를 검토하여 ADK 도구를 래핑하고 제공하는 방법을 이해합니다.

   잠시 시간을 내어 파일을 검토하고, 주석을 읽어 코드가 도구를 래핑하고 MCP 서버로 제공하는 방법을 이해합니다. 또한 코드가 MCP 클라이언트로 하여금 사용 가능한 도구를 나열하고 ADK 도구를 비동기적으로 호출하여 MCP 호환 형식으로 요청과 응답을 처리할 수 있도록 하는 방법을 확인하세요.

ADK 에이전트로 커스텀 MCP 서버 테스트

1. adk_mcp_server 디렉터리에서 agent.py를 엽니다.

2. 31번째 줄에서 PATH_TO_YOUR_MCP_SERVER_SCRIPT 값을 다음 경로로 업데이트해 에이전트가 커스텀 서버 스크립트에 연결할 수 있게 합니다.

   /home/{{{project_0.startup_script.updated_lab_username | Username}}}/adk_mcp_tools/adk_mcp_server/adk_server.py

3. 다음으로 agent.py 파일에서 ## Add the MCPToolset below:라고 표시된 55번째 줄에 다음 코드를 추가하여 에이전트에 MCPToolset를 추가합니다. ADK 에이전트는 MCP 서버의 클라이언트 역할을 합니다. 이 ADK 에이전트는 MCPToolset를 사용하여 adk_server.py 스크립트에 연결합니다.

   tools=[ MCPToolset( connection_params=StdioConnectionParams( server_params=StdioServerParameters( command="python3", # Command to run your MCP server script args=[PATH_TO_YOUR_MCP_SERVER_SCRIPT], # Argument is the path to the script ), timeout=15, ), tool_filter=['load_web_page'] # Optional: ensure only specific tools are loaded ) ],

4. 파일을 저장합니다.

5. MCP 서버를 실행하려면 Cloud Shell 터미널에서 다음 명령어를 실행하여 adk_server.py 스크립트를 시작합니다.

   python3 ~/adk_mcp_tools/adk_mcp_server/adk_server.py

   출력:

   

6. Cloud Shell 터미널 창 상단의 버튼을 클릭하여 새 Cloud Shell 터미널 탭을 엽니다.

7. Cloud Shell 터미널에서 adk_mcp_tools 프로젝트 디렉터리에서 다음 명령어를 사용하여 에이전트 개발 키트 개발 UI를 실행합니다.

   export PATH=$PATH:"/home/${USER}/.local/bin" cd ~/adk_mcp_tools adk web --allow_origins "regex:https://.*.cloudshell.dev" --otel_to_cloud --reload_agents 참고: 이 명령어에는 `PATH`가 추가되어 재설정되었습니다. 새 Cloud Shell 터미널에서 이 명령어를 실행할 때 `PATH`가 없으면 오류가 발생할 수 있기 때문입니다. 대부분의 경우 `adk web`을 찾을 수 없다는 오류가 발생합니다.

8. 새 탭에서 웹 인터페이스를 보려면 터미널 출력에서 http://127.0.0.1:8000 링크를 클릭합니다.

9. 왼쪽의 에이전트 선택 드롭다운에서 adk_mcp_server를 선택합니다.

10. 에이전트에 다음 프롬프트를 입력합니다.

    http://example.com에서 콘텐츠를 로드해 줘.

    출력:

    

    여기서 일어나는 일:

    • ADK 에이전트(web_reader_mcp_client_agent)는 MCPToolset를 사용하여 adk_server.py에 연결합니다.
    • MCP 서버는 call_tool 요청을 수신하고 ADK load_web_page 도구를 실행한 다음 결과를 반환합니다.
    • 이렇게 하면 ADK 에이전트가 이 정보를 전달합니다. ADK Web UI(및 해당 터미널)와 adk_server.py 터미널에서 이를 실행 중인 Cloud Shell 터미널 탭에 로그가 표시됩니다.

    이는 ADK 도구를 MCP 서버 내에 캡슐화하여 ADK 에이전트를 포함한 광범위한 MCP 호환 클라이언트가 ADK 도구에 액세스할 수 있음을 보여줍니다.

수고하셨습니다

이 실습에서는 MCPToolset 클래스를 사용하여 외부 모델 컨텍스트 프로토콜(MCP) 도구를 에이전트 개발 키트(ADK) 에이전트에 통합하는 방법을 알아봤습니다. MCP 서버에 연결하고, 에이전트 내에서 해당 도구를 사용하고, 커스텀 MCP 서버를 통해 load_web_page와 같은 ADK 도구를 노출하는 방법도 알아봤습니다. 이러한 기술을 사용하면 강력한 외부 서비스로 ADK 에이전트를 확장하여 웹 개발 워크플로를 개선할 수 있습니다.

설명서 최종 업데이트: 2026년 4월 21일

실습 최종 테스트: 2026년 4월 21일

Copyright 2026 Google LLC. All rights reserved. Google 및 Google 로고는 Google LLC의 상표입니다. 기타 모든 회사명 및 제품명은 해당 업체의 상표일 수 있습니다.