1. Wprowadzenie
Przegląd
W tym module utworzysz i wdrożysz serwer protokołu kontekstu modelu (MCP). Serwery MCP są przydatne, ponieważ zapewniają LLM dostęp do zewnętrznych narzędzi i usług. Skonfigurujesz ją jako bezpieczną usługę gotową do wdrożenia w środowisku produkcyjnym w Cloud Run, do której można uzyskać dostęp z wielu klientów. Następnie połączysz się ze zdalnym serwerem MCP z poziomu interfejsu Gemini CLI.
Jakie zadania wykonasz
Użyjemy FastMCP, aby utworzyć serwer MCP zoo z 2 narzędziami: get_animals_by_species i get_animal_details. FastMCP to szybki sposób na tworzenie serwerów i klientów MCP w języku Python.
Czego się nauczysz
- Wdróż serwer MCP w Cloud Run.
- Zabezpiecz punkt końcowy serwera, wymagając uwierzytelniania wszystkich żądań, aby tylko autoryzowani klienci i agenci mogli się z nim komunikować.
- Nawiązywanie połączenia z bezpiecznym punktem końcowym serwera MCP z interfejsu wiersza poleceń Gemini
2. Konfiguracja projektu
- Jeśli nie masz jeszcze konta Google, musisz utworzyć konto Google.
- Użyj konta osobistego zamiast konta służbowego lub szkolnego. Konta służbowe i szkolne mogą mieć ograniczenia, które uniemożliwiają włączenie interfejsów API potrzebnych w tym module.
- Zaloguj się w konsoli Google Cloud.
- Włącz rozliczenia w Cloud Console.
- Ukończenie tego modułu powinno kosztować mniej niż 1 USD w zasobach chmury.
- Aby uniknąć dalszych opłat, wykonaj czynności opisane na końcu tego modułu, aby usunąć zasoby.
- Nowi użytkownicy mogą skorzystać z bezpłatnego okresu próbnego, w którym mają do dyspozycji środki w wysokości 300 USD.
- Utwórz nowy projekt lub użyj już istniejącego.
3. Otwórz edytor Cloud Shell
- Kliknij ten link, aby przejść bezpośrednio do edytora Cloud Shell
- Jeśli w dowolnym momencie pojawi się prośba o autoryzację, kliknij Autoryzuj, aby kontynuować.
- Jeśli terminal nie pojawia się u dołu ekranu, otwórz go:
- Kliknij Wyświetl.
- Kliknij Terminal
- W terminalu ustaw projekt za pomocą tego polecenia:
- Format:
gcloud config set project [PROJECT_ID] - Przykład:
gcloud config set project lab-project-id-example - Jeśli nie pamiętasz identyfikatora projektu:
- Aby wyświetlić listę wszystkich identyfikatorów projektów, użyj tego polecenia:
gcloud projects list | awk '/PROJECT_ID/{print $2}'
- Aby wyświetlić listę wszystkich identyfikatorów projektów, użyj tego polecenia:
- Format:
- Powinien wyświetlić się ten komunikat:
Updated property [core/project].
WARNINGi pojawia się pytanieDo you want to continue (Y/n)?, prawdopodobnie identyfikator projektu został wpisany nieprawidłowo. Naciśnijn, a następnieEnteri spróbuj ponownie uruchomić poleceniegcloud config set project.
4. Włącz interfejsy API
W terminalu włącz interfejsy API:
gcloud services enable \
run.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com
Jeśli pojawi się pytanie o autoryzację, kliknij Autoryzuj, aby przejść dalej.
Wykonanie tego polecenia może potrwać kilka minut, ale powinno ostatecznie wyświetlić komunikat o sukcesie podobny do tego:
Operation "operations/acf.p2-73d90d00-47ee-447a-b600" finished successfully.
5. Przygotowywanie projektu w Pythonie
- Utwórz folder o nazwie
mcp-on-cloudrun, w którym będzie przechowywany kod źródłowy do wdrożenia:mkdir mcp-on-cloudrun && cd mcp-on-cloudrun - Utwórz projekt w Pythonie za pomocą narzędzia
uv, aby wygenerować plikpyproject.toml:uv init --description "Example of deploying an MCP server on Cloud Run" --bare --python 3.13uv inittworzy plikpyproject.tomldla Twojego projektu.Aby wyświetlić zawartość pliku, uruchom to polecenie:cat pyproject.toml[project] name = "mcp-on-cloudrun" version = "0.1.0" description = "Example of deploying an MCP server on Cloud Run" requires-python = ">=3.13" dependencies = []
6. Tworzenie serwera MCP zoo
Aby zapewnić wartościowy kontekst do ulepszania korzystania z LLM w przypadku MCP, skonfiguruj serwer MCP w usłudze Zoo za pomocą FastMCP – standardowego frameworka do pracy z protokołem kontekstu modelu. FastMCP to szybki sposób na tworzenie serwerów i klientów MCP w Pythonie. Ten serwer MCP dostarcza dane o zwierzętach w fikcyjnym zoo. Dla uproszczenia przechowujemy dane w pamięci. W przypadku serwera MCP w środowisku produkcyjnym prawdopodobnie chcesz udostępniać dane ze źródeł takich jak bazy danych lub interfejsy API.
- Aby dodać FastMCP jako zależność w pliku
pyproject.toml, uruchom to polecenie:uv add fastmcp==2.11.1 --no-syncuv.lock. - Utwórz i otwórz nowy plik
server.pyz kodem źródłowym serwera MCP:cloudshell edit server.pycloudshell editotworzy plikserver.pyw edytorze nad terminalem. - Dodaj do pliku
server.pyten kod źródłowy serwera MCP zoo:import asyncio import logging import os from typing import List, Dict, Any from fastmcp import FastMCP logger = logging.getLogger(__name__) logging.basicConfig(format="[%(levelname)s]: %(message)s", level=logging.INFO) mcp = FastMCP("Zoo Animal MCP Server 🦁🐧🐻") # Dictionary of animals at the zoo ZOO_ANIMALS = [ { "species": "lion", "name": "Leo", "age": 7, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Nala", "age": 6, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "Simba", "age": 3, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "lion", "name": "King", "age": 8, "enclosure": "The Big Cat Plains", "trail": "Savannah Heights" }, { "species": "penguin", "name": "Waddles", "age": 2, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pip", "age": 4, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Skipper", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Chilly", "age": 3, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Pingu", "age": 6, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "penguin", "name": "Noot", "age": 1, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "elephant", "name": "Ellie", "age": 15, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Peanut", "age": 12, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Dumbo", "age": 5, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "elephant", "name": "Trunkers", "age": 10, "enclosure": "The Pachyderm Sanctuary", "trail": "Savannah Heights" }, { "species": "bear", "name": "Smokey", "age": 10, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Grizzly", "age": 8, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Barnaby", "age": 6, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "bear", "name": "Bruin", "age": 12, "enclosure": "The Grizzly Gulch", "trail": "Polar Path" }, { "species": "giraffe", "name": "Gerald", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Longneck", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Patches", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "giraffe", "name": "Stretch", "age": 6, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Speedy", "age": 2, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Dash", "age": 3, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Gazelle", "age": 4, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "antelope", "name": "Swift", "age": 5, "enclosure": "The Tall Grass Plains", "trail": "Savannah Heights" }, { "species": "polar bear", "name": "Snowflake", "age": 7, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Blizzard", "age": 5, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "polar bear", "name": "Iceberg", "age": 9, "enclosure": "The Arctic Exhibit", "trail": "Polar Path" }, { "species": "walrus", "name": "Wally", "age": 10, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Tusker", "age": 12, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Moby", "age": 8, "enclosure": "The Walrus Cove", "trail": "Polar Path" }, { "species": "walrus", "name": "Flippers", "age": 9, "enclosure": "The Walrus Cove", "trail": "Polar Path" } ] @mcp.tool() def get_animals_by_species(species: str) -> List[Dict[str, Any]]: """ Retrieves all animals of a specific species from the zoo. Can also be used to collect the base data for aggregate queries of animals of a specific species - like counting the number of penguins or finding the oldest lion. Args: species: The species of the animal (e.g., 'lion', 'penguin'). Returns: A list of dictionaries, where each dictionary represents an animal and contains details like name, age, enclosure, and trail. """ logger.info(f">>> 🛠️ Tool: 'get_animals_by_species' called for '{species}'") return [animal for animal in ZOO_ANIMALS if animal["species"].lower() == species.lower()] @mcp.tool() def get_animal_details(name: str) -> Dict[str, Any]: """ Retrieves the details of a specific animal by its name. Args: name: The name of the animal. Returns: A dictionary with the animal's details (species, name, age, enclosure, trail) or an empty dictionary if the animal is not found. """ logger.info(f">>> 🛠️ Tool: 'get_animal_details' called for '{name}'") for animal in ZOO_ANIMALS: if animal["name"].lower() == name.lower(): return animal return {} if __name__ == "__main__": logger.info(f"🚀 MCP server started on port {os.getenv('PORT', 8080)}") asyncio.run( mcp.run_async( transport="http", host="0.0.0.0", port=os.getenv("PORT", 8080), ) )
Kod jest gotowy. Czas wdrożyć serwer MCP w Cloud Run.
7. Wdrażanie w Cloud Run
Teraz wdróż serwer MCP w Cloud Run bezpośrednio z kodu źródłowego.
- Utwórz i otwórz nowy plik
Dockerfiledo wdrożenia w Cloud Run:cloudshell edit Dockerfile - Aby użyć narzędzia
uvdo uruchomienia plikuserver.py, dodaj do pliku Dockerfile ten kod:# Use the official Python image FROM python:3.13-slim # Install uv COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/ # Install the project into /app COPY . /app WORKDIR /app # Allow statements and log messages to immediately appear in the logs ENV PYTHONUNBUFFERED=1 # Install dependencies RUN uv sync EXPOSE $PORT # Run the FastMCP server CMD ["uv", "run", "server.py"] - Uruchom polecenie
gcloud, aby wdrożyć aplikację w Cloud Run.gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp--no-allow-unauthenticated, aby wymagać uwierzytelniania. Jest to ważne ze względów bezpieczeństwa. Jeśli nie wymagane jest uwierzytelnianie, każdy może wywołać serwer MCP i potencjalnie uszkodzić Twój system. - Potwierdź utworzenie nowego repozytorium Artifact Registry. Ponieważ po raz pierwszy wdrażasz w Cloud Run kod źródłowy, zobaczysz:
Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region [europe-west1] will be created. Do you want to continue (Y/n)?
Yi naciśnijEnter. Spowoduje to utworzenie repozytorium Artifact Registry na potrzeby wdrożenia. Jest to wymagane do przechowywania kontenera Docker serwera MCP na potrzeby usługi Cloud Run. - Po kilku minutach zobaczysz komunikat podobny do tego:
Service [zoo-mcp-server] revision [zoo-mcp-server-12345-abc] has been deployed and is serving 100 percent of traffic.
Serwer MCP został wdrożony. Teraz możesz z niej korzystać.
8. Dodawanie zdalnego serwera MCP do interfejsu wiersza poleceń Gemini
Gdy uda Ci się wdrożyć zdalny serwer MCP, możesz połączyć się z nim za pomocą różnych aplikacji, takich jak Google Code Assist czy interfejs wiersza poleceń Gemini. W tej sekcji nawiążemy połączenie z nowym zdalnym serwerem MCP za pomocą Gemini CLI.
- Przyznaj kontu użytkownika uprawnienia do wywoływania zdalnego serwera MCP.
gcloud projects add-iam-policy-binding $GOOGLE_CLOUD_PROJECT \ --member=user:$(gcloud config get-value account) \ --role='roles/run.invoker' - Zapisz dane logowania do Google Cloud i numer projektu w zmiennych środowiskowych, aby używać ich w pliku ustawień Gemini:
export PROJECT_NUMBER=$(gcloud projects describe $GOOGLE_CLOUD_PROJECT --format="value(projectNumber)") export ID_TOKEN=$(gcloud auth print-identity-token) - Otwórz plik ustawień interfejsu wiersza poleceń Gemini
cloudshell edit ~/.gemini/settings.json - Zastępowanie pliku ustawień interfejsu Gemini CLI w celu dodania serwera MCP Cloud Run
{ "mcpServers": { "zoo-remote": { "httpUrl": "https://zoo-mcp-server-$PROJECT_NUMBER.europe-west1.run.app/mcp/", "headers": { "Authorization": "Bearer $ID_TOKEN" } } }, "selectedAuthType": "cloud-shell", "hasSeenIdeIntegrationNudge": true }
- Uruchamianie interfejsu wiersza poleceń Gemini w Cloud Shell
geminiEnter.
- Poproś Gemini o wyświetlenie narzędzi MCP dostępnych w kontekście.
/mcp - Poproś Gemini o znalezienie czegoś w zoo
Where can I find penguins?zoo-remoteserwera MCP, i zapyta, czy chcesz zezwolić na wykonanie MCP. - Użyj strzałki w dół, a następnie naciśnij
Enter, aby wybrać.Yes, always allow all tools from server "zoo-remote"
Wynik powinien zawierać prawidłową odpowiedź i pole wyświetlania wskazujące, że użyto serwera MCP.
Udało Ci się! Udało Ci się wdrożyć zdalny serwer MCP w Cloud Run i przetestować go za pomocą interfejsu Gemini CLI.
Gdy chcesz zakończyć sesję, wpisz /quit, a potem naciśnij Enter, aby zamknąć interfejs Gemini CLI.
Debugowanie
Jeśli zobaczysz taki błąd:
🔍 Attempting OAuth discovery for 'zoo-remote'... ❌ 'zoo-remote' requires authentication but no OAuth configuration found Error connecting to MCP server 'zoo-remote': MCP server 'zoo-remote' requires authentication. Please configure OAuth or check server settings.
Prawdopodobnie token identyfikatora wygasł i wymaga ponownego ustawienia ID_TOKEN.
- Wpisz
/quit, a potem naciśnijEnter, aby zamknąć interfejs wiersza poleceń Gemini. - Ustawianie projektu w terminalu
gcloud config set project [PROJECT_ID] - Zacznij od nowa od kroku 2 powyżej
9. (Opcjonalnie) Weryfikowanie wywołań narzędzi w logach serwera
Aby sprawdzić, czy serwer MCP Cloud Run został wywołany, przejrzyj logi usługi.
gcloud run services logs read zoo-mcp-server --region europe-west1 --limit=5
Powinien pojawić się dziennik wyjściowy z potwierdzeniem, że wywołano narzędzie. 🛠️
2025-08-05 19:50:31 INFO: 169.254.169.126:39444 - "POST /mcp/ HTTP/1.1" 200 OK 2025-08-05 19:50:31 [INFO]: Processing request of type CallToolRequest 2025-08-05 19:50:31 [INFO]: >>> 🛠️ Tool: 'get_animals_by_species' called for 'penguin'
10. (Opcjonalnie) Dodaj prompt MCP do serwera
Prompt MCP może przyspieszyć przepływ pracy w przypadku promptów, których często używasz, tworząc skrót dla dłuższego prompta.
Interfejs Gemini CLI automatycznie przekształca prompty MCP w niestandardowe polecenia z ukośnikiem, dzięki czemu możesz wywołać prompt MCP, wpisując /prompt_name, gdzie prompt_name to nazwa promptu MCP.
Utwórz prompta MCP, aby szybko znaleźć zwierzę w zoo, wpisując /find animal w interfejsie Gemini CLI.
- Dodaj ten kod do pliku
server.pypowyżej głównego zabezpieczenia (if __name__ == "__main__":).@mcp.prompt() def find(animal: str) -> str: """ Find which exhibit and trail a specific animal might be located. """ return ( f"Please find the exhibit and trail information for {animal} in the zoo. " f"Respond with '[animal] can be found in the [exhibit] on the [trail].'" f"Example: Penguins can be found in The Arctic Exhibit on the Polar Path." ) - Ponowne wdrażanie aplikacji w Cloud Run
gcloud run deploy zoo-mcp-server \ --no-allow-unauthenticated \ --region=europe-west1 \ --source=. \ --labels=dev-tutorial=codelab-mcp - Odświeżanie ID_TOKEN na zdalnym serwerze MCP
export ID_TOKEN=$(gcloud auth print-identity-token) - Po wdrożeniu nowej wersji aplikacji uruchom interfejs Gemini CLI.
gemini - W prompcie użyj nowego polecenia niestandardowego, które zostało utworzone:
/find --animal="lions"
Powinno się pojawić, że interfejs Gemini CLI wywołuje narzędzie get_animals_by_species i formatuje odpowiedź zgodnie z instrukcjami w prompcie MCP.
╭───────────────────────────╮
│ > /find --animal="lion" │
╰───────────────────────────╯
╭───────────────────────────────────────────────────────────────────────────────────────────────────╮
│ ✔ get_animals_by_species (zoo-remote MCP Server) get_animals_by_species (zoo-remote MCP Server) │
│ │
│ [{"species":"lion","name":"Leo","age":7,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Nala","age":6,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"Simba","age":3,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah │
│ Heights"},{"species":"lion","name":"King","age":8,"enclosure":"The Big Cat │
│ Plains","trail":"Savannah Heights"}] │
╰───────────────────────────────────────────────────────────────────────────────────────────────────╯
✦ Lions can be found in The Big Cat Plains on the Savannah Heights.
Cele dodatkowe, które pozwolą Ci sprawdzić swoje możliwości
Aby podnieść sobie poprzeczkę, spróbuj wykonać te same czynności, aby utworzyć prompta, który będzie zwracać ciekawe fakty na temat konkretnych gatunków zwierząt w zoo.
Możesz też sprawdzić swoją wiedzę, wymyślając narzędzie, z którego będziesz często korzystać, i wdrażając drugi zdalny serwer MCP. Następnie dodaj go do ustawień interfejsu wiersza poleceń Gemini, aby sprawdzić, czy działa.
11. Podsumowanie
Gratulacje! Udało Ci się wdrożyć bezpieczny zdalny serwer MCP i nawiązać z nim połączenie.
Przejdź do następnego modułu
Ten moduł jest pierwszym z trzech modułów w tej serii. W drugim module użyjesz serwera MCP utworzonego za pomocą agenta ADK.
Używanie serwera MCP w Cloud Run z agentem ADK
(Opcjonalnie) Czyszczenie
Jeśli nie chcesz przechodzić do kolejnego ćwiczenia i chcesz usunąć utworzone zasoby, możesz usunąć projekt w Google Cloud, aby uniknąć dodatkowych opłat.
Cloud Run nie nalicza opłat, gdy usługa nie jest używana, ale może zostać pobrana należność za przechowywanie obrazu kontenera w Artifact Registry. Usunięcie projektu Cloud spowoduje zaprzestanie naliczania opłat za wszelkie zasoby wykorzystywane w ramach tego projektu.
Jeśli chcesz, usuń projekt:
gcloud projects delete $GOOGLE_CLOUD_PROJECT
Możesz też usunąć niepotrzebne zasoby z dysku Cloud Shell. Możesz:
- Usuń katalog projektu ćwiczeń z programowania:
rm -rf ~/mcp-on-cloudrun - Ostrzeżenie! Tej czynności nie można cofnąć. Jeśli chcesz usunąć wszystko z Cloud Shell, aby zwolnić miejsce, możesz usunąć cały katalog domowy. Upewnij się, że wszystko, co chcesz zachować, jest zapisane w innym miejscu.
sudo rm -rf $HOME