Google używa technologii AI do tłumaczenia treści na Twój preferowany język. Tłumaczenia wygenerowane przez AI mogą zawierać błędy.

Standardy integracji połączonych aplikacji MCP

Serwer MCP tworzy strukturę do łączenia funkcji aplikacji (narzędzi MCP) z platformą Connected Apps Platform. Aby umożliwić mu bardziej niezawodne wybieranie, wywoływanie i przetwarzanie wyników usługi, konfiguracja MCP musi ściśle odpowiadać tym standardom.

Podstawowe zasady

W przypadku każdej funkcji skup się na intencjach użytkownika i przypadkach użycia, a nie na możliwościach funkcji. Opis to podstawowy sposób na poinformowanie modelu, do czego służy narzędzie i jakie przypadki użycia może obsługiwać.

Obsługa wersji,

Aby zapewnić skalowalne i niezawodne wdrożenia MCP, zastosuj uporządkowaną architekturę identyfikatorów URI, która wykorzystuje obsługę wersji na podstawie ścieżki, np. /v1, /v2. Dzięki temu zachowasz zgodność wsteczną i będziesz mieć możliwość wprowadzania nowych funkcji. Uzupełnienie tego o subdomeny dostawców, takie jak https://gemini.mcp.company.com/mcp/v1, umożliwia szczegółowe zarządzanie ruchem i optymalizację definicji narzędzi dostosowanych do unikalnego kontekstu i zachowań przetwarzania różnych modeli AI.

Zgodność wersji protokołu MCP

Platforma połączonych aplikacji obsługuje specyfikację Model Context Protocol (MCP) do wersji 2025-11-25. Nowsze wersje specyfikacji nie są jeszcze obsługiwane.

Odpowiedzialność dewelopera: odpowiadasz za to, aby serwer MCP ściśle przestrzegał wersji protokołu obsługiwanej przez platformę połączonych aplikacji (2025-11-25) podczas uzgadniania połączenia initialize oraz we wszystkich definicjach narzędzi i schematów.
Zgodność wsteczna platformy: w miarę jak Connected Apps Platform będzie w przyszłości wdrażać nowsze wersje specyfikacji MCP, nasz klient zachowa zgodność wsteczną z wcześniej obsługiwanymi wersjami protokołu, dzięki czemu istniejące integracje produkcyjne będą nadal działać bez zakłóceń.
Zarządzanie uaktualnieniami: gdy będziesz gotowy(-a) do wdrożenia nowo obsługiwanej specyfikacji MCP lub wprowadzenia zmian w schemacie, udostępnij te aktualizacje w nowej ścieżce identyfikatora URI z numerem wersji (np. /mcp/v2), zachowując dotychczasowy punkt końcowy (/mcp/v1) dla aktywnego ruchu.

Zmiany w schematach MCP są dozwolone między wersjami aplikacji. Zalecamy korzystanie z tej funkcji i obsługę wersji punktów końcowych MCP, aby umożliwić łagodne wdrażanie nowych funkcji, lub poleganie wyłącznie na zmianach zgodnych wstecznie.

Specyfikacja protokołu transportowego

Platforma połączonych aplikacji obsługuje wyłącznie transport Streamable HTTP w ramach specyfikacji Model Context Protocol w wersji 2025-03-26 lub nowszej. Nie obsługuje starszego protokołu HTTP z transportem SSE opisanego w specyfikacji z 5 listopada 2024 r.

Pojedynczy punkt końcowy HTTP. Punkt końcowy MCP podany w Połączonej konsoli (np. https://api.example.com/mcp) to pojedynczy adres URL, na który odpowiednie usługi Google wysyłają wszystkie żądania JSON-RPC (initialize, tools/list, tools/call) za pomocą standardowego protokołu HTTP POST.
Strumieniowanie SSE w ramach strumieniowego protokołu HTTP. Starszy transport SSE z wieloma punktami końcowymi nie jest obsługiwany, ale zdarzenia wysyłane przez serwer, takie jak text/event-stream, są obsługiwane w ramach strumieniowego protokołu HTTP. Żądania wychodzące z odpowiednich usług Google zawierają Accept: application/json, text/event-stream, co oznacza, że serwer może zwrócić standardowy ładunek application/json lub przesyłać strumieniowo odpowiedzi przyrostowe za pomocą Content-Type: text/event-stream bezpośrednio w treści odpowiedzi HTTP POST.
GET stream & 405 Method Not Allowed. Klienci mogą spróbować opcjonalnego strumienia GET w punkcie końcowym dla powiadomień serwer-klient. Jeśli serwer jest bezstanowy lub obsługuje tylko żądania i odpowiedzi, zwracanie kodu HTTP 405 Method Not Allowed jest wyraźnie obsługiwane i prawidłowo przetwarzane przez serwer proxy klienta odpowiedniej usługi Google.

Instrukcje dotyczące serwera

Platforma połączonych aplikacji jest zoptymalizowana pod kątem przetwarzania instrukcji serwera, co pozwala na pewien stopień kontroli nad zachowaniem modelu, który nie jest dostępny w inny sposób.

Postępuj zgodnie z instrukcjami dotyczącymi serwera.

Traktuj jako „wskazówkę dla modelu” z kontekstem użycia.

Postępuj zgodnie z tymi wskazówkami dotyczącymi podawania wskazówek modelom.

Zapisz instrukcje jako ogólną „wskazówkę” lub przewodnik, który pomoże LLM zrozumieć ogólny cel i możliwości serwera.
Opisz, co może robić, zamiast wymieniać funkcje lub opisywać, jak model powinien używać narzędzi i zasobów serwera. Jeśli model prawidłowo rozumie „co”, może dość dobrze określić „jak” na podstawie ścieżki użytkownika.
Załóż, że ten tekst zostanie dodany bezpośrednio do promptu systemowego modelu. Powinien być jasny, zawierać instrukcje i być efektywny pod względem tokenów.

Uzupełniaj, nie powielaj

Użyj tego miejsca na globalny kontekst, który dotyczy wszystkich narzędzi, unikając powielania informacji z opisów poszczególnych narzędzi.

Przykłady instrukcji dotyczących serwera

Poniższe przykłady pokazują, co należy, a czego nie należy robić podczas pisania instrukcji dla serwera.

Polecane Niezalecane

Polecane	Niezalecane
Wciel się w rolę wyspecjalizowanego opiekuna repozytorium GitHub. Ten serwer zapewnia szeroki dostęp do metadanych repozytorium, [narzędzia] Issue Tracker i przepływów pracy PR. Używaj go do utrzymywania dobrego stanu projektu, automatyzacji klasyfikacji i zapewniania zgodności ze standardami kodu. Jeśli nie określono inaczej, zakładamy, że wszystkie działania są wykonywane w kontekście uwierzytelnionej organizacji. Skup się na identyfikowaniu nieaktualnych wątków lub niepołączonych PR, aby utrzymać porządek w repozytorium. Zwięzłe, dyrektywne i uzupełniające model Definiuje „co” (stan projektu, klasyfikacja), a nie „jak”. Wspomina o zakresie uwierzytelniania, który dotyczy wszystkich narzędzi	Ten serwer zawiera narzędzia do GitHuba. Gdy użytkownik pyta o problemy, użyj narzędzia `list_issues`. Możesz użyć `create_pull_request`, aby utworzyć PR. Używaj tych narzędzi ostrożnie, aby pomóc użytkownikowi zarządzać kodem. Zawsze sprawdzaj nazwę repozytorium przed wywołaniem narzędzia. Jeśli użytkownik poprosi o podsumowanie, najpierw wywołaj narzędzia, a następnie podsumuj dane wyjściowe. nie wymieniaj ponownie nazw narzędzi, nie mów modelowi, „jak” ma myśleć, ponieważ może to być sprzeczne z wbudowanym rozumowaniem modelu, który wykorzysta kontekst użytkownika, aby dokonać właściwego wyboru. nie wyjaśnia charakteru dostępu serwera ani jego konkretnych ograniczeń)

Wciel się w rolę wyspecjalizowanego opiekuna repozytorium GitHub. Ten serwer zapewnia szeroki dostęp do metadanych repozytorium, [narzędzia] Issue Tracker i przepływów pracy PR. Używaj go do utrzymywania dobrego stanu projektu, automatyzacji klasyfikacji i zapewniania zgodności ze standardami kodu. Jeśli nie określono inaczej, zakładamy, że wszystkie działania są wykonywane w kontekście uwierzytelnionej organizacji. Skup się na identyfikowaniu nieaktualnych wątków lub niepołączonych PR, aby utrzymać porządek w repozytorium.

Zwięzłe, dyrektywne i uzupełniające model

Definiuje „co” (stan projektu, klasyfikacja), a nie „jak”.
Wspomina o zakresie uwierzytelniania, który dotyczy wszystkich narzędzi

Ten serwer zawiera narzędzia do GitHuba. Gdy użytkownik pyta o problemy, użyj narzędzia list_issues. Możesz użyć create_pull_request, aby utworzyć PR. Używaj tych narzędzi ostrożnie, aby pomóc użytkownikowi zarządzać kodem. Zawsze sprawdzaj nazwę repozytorium przed wywołaniem narzędzia. Jeśli użytkownik poprosi o podsumowanie, najpierw wywołaj narzędzia, a następnie podsumuj dane wyjściowe.

nie wymieniaj ponownie nazw narzędzi,
nie mów modelowi, „jak” ma myśleć, ponieważ może to być sprzeczne z wbudowanym rozumowaniem modelu, który wykorzysta kontekst użytkownika, aby dokonać właściwego wyboru.
nie wyjaśnia charakteru dostępu serwera ani jego konkretnych ograniczeń)

Wytyczne dotyczące narzędzi

Poniższe wytyczne opisują sprawdzone metody tworzenia konfiguracji serwera MCP dla różnych funkcji lub narzędzi w aplikacji.

Konwencje nazewnictwa narzędzi

Przestrzegaj tych wskazówek dotyczących nazewnictwa narzędzi:

Używaj intuicyjnych, zrozumiałych dla człowieka nazw.

Używaj nazw zrozumiałych dla człowieka, które mają jasne, intuicyjne znaczenie, zamiast nazw niejednoznacznych. Na przykład get_user_information jest bardziej bezpośrednie niż userInfo.

Używaj odpowiedniego stylu wielkości liter

Przestrzegaj tych zasad dotyczących wielkości liter w nazwach funkcji narzędzi i wyzwalaczach aplikacji:

Wielkość liter w nazwach funkcji narzędzi. Użyj snake_case lub camelCase w przypadku nazw funkcji narzędzi zdefiniowanych w schemacie MCP (np. get_user_information lub publishDraft).
Obudowa uchwytu aktywującego aplikację. W przypadku aktywatorów i wzmianek aplikacji (np. @MyTwoWordApp) wielkość liter nie jest rozróżniana. Platforma normalizuje dane wejściowe użytkownika, używając małych liter (@mytwowordapp), PascalCase (@MyTwoWordApp) i camelCase (@myTwoWordApp).
Formatowanie wyświetlanej nazwy. Zarejestruj oficjalny tytuł aplikacji, używając PascalCase lub standardowych spacji, aby zapewnić czytelność w elementach interfejsu.
Obsługa literówek. Wielkość liter jest obsługiwana automatycznie, ale literówki (np. @mytwowrodapp) są rozpoznawane przez intencję zastępczą, a nie przez bezpośrednie dopasowanie ciągu znaków. Deweloperzy powinni zachęcać do poprawnego zapisywania nicków w dokumentacji.

Używaj jednoznacznych nazw w formie czasownik-rzeczownik

Używaj konkretnych nazw verb_noun i unikaj niejednoznaczności – na przykład publish_draft jest lepsze niż handle_content.

Szczegółowość narzędzia

Przestrzegaj tych wskazówek dotyczących szczegółowości narzędzi.

Traktowanie narzędzi jako niepodzielnych punktów końcowych

Traktuj narzędzia jako niepodzielne punkty końcowe bez warunków wewnętrznych ani wielu funkcji z odpowiednimi wymaganymi parametrami. Szczegółowe narzędzia umożliwiają modelowi logiczne łączenie kroków, co zmniejsza liczbę halucynacji.

Używanie bardziej płaskich schematów

Jeśli do sprawdzania poprawności danych wejściowych potrzebujesz głęboko zagnieżdżonych obiektów lub złożonej logiki schematu oneOf / anyOf, narzędzie jest prawdopodobnie zbyt ogólne.

Przestrzeganie zasad dotyczących wstępnej agregacji i ładunku

Chociaż wstępna agregacja danych nie jest ściśle wymagana przez protokół w przypadku małych, ograniczonych ładunków, w praktyce jest ona zdecydowanie zalecana podczas pracy z dużymi zbiorami rekordów, historią podłużną i zbiorami danych z wielu źródeł. Connected Apps Platform wymusza zabezpieczenia dotyczące limitów okna kontekstu, opóźnienia wykonywania i kroków rozumowania modelu. Aby przestrzegać tych zasad, postępuj zgodnie z tymi wskazówkami:

Filtrowanie i podsumowywanie w backendzie. Zawsze filtruj, wstępnie agreguj lub podsumowuj duże strumienie danych na serwerze MCP przed zwróceniem odpowiedzi do odpowiednich usług Google.
Unikaj nieprzetworzonych zrzutów. Nigdy nie umieszczaj nieprzetworzonych wierszy bazy danych ani pełnych nieindeksowanych dzienników w ładunku zwracanym przez narzędzie.

Pomiń narzędzia wewnętrzne i metanarzędzia

W odpowiedzi tools/list serwera udostępniaj tylko funkcje przeznaczone dla modelu:

Odfiltruj narzędzia pomocnicze: pomiń wszelkie narzędzia wewnętrzne, administracyjne lub metanarzędzia, które nie są przeznaczone do wywoływania przez model (np. kontrole stanu serwera, wewnętrzne procedury konfiguracji lub narzędzia pomocnicze dla deweloperów).
Wydajność okna kontekstu: wykluczenie niepotrzebnych narzędzi pozwala zachować zwięzłość schematu MCP, zmniejsza zużycie tokenów okna kontekstu i zapobiega problemom z wybieraniem narzędzi przez model. Serwery MCP, które udostępniają dziesiątki narzędzi lub głęboko zagnieżdżone schematy „meganarzędzi”, zostaną oznaczone podczas sprawdzania do poprawienia.

Zalecenia i ograniczenia dotyczące szczegółowości narzędzi

Poniższe przykłady pokazują, co należy, a czego nie należy robić w odniesieniu do nazewnictwa narzędzi i używania szczegółowości.

Polecane Niezalecane

Polecane	Niezalecane
Szczegółowe narzędzia z jasnymi nazwami i parametrami Schemat wejściowy każdego narzędzia jest rygorystyczny. Jeśli LLM chce utworzyć użytkownika, musi podać adres e-mail. Jeśli chcesz usunąć, musisz podać identyfikator. Nie musisz zgadywać. `... @mcp.tool() def create_user(email: str, role: str = "viewer") -> str: """Register a new user. Returns the new User ID.""" # Logic is purely creation return "user_123" @mcp.tool() def delete_user(user_id: str) -> str: """Permanently remove a user by their ID.""" # Logic is purely deletion return f"User {user_id} deleted" @mcp.tool() def update_user_role(user_id: str, new_role: str) -> str: """Change an existing user's permission level.""" return f"User {user_id} is now {new_role}" ...`	Nazwa narzędzia: manage_user Opis: „Użyj tego narzędzia, aby tworzyć, aktualizować, usuwać lub pobierać użytkowników”. ... @mcp.tool() def manage_user( action: Literal["create", "update", "delete", "get"], user_id: Optional[str] = None, email: Optional[str] = None, role: Optional[str] = "viewer" ) -> str: """ Use this to manage users. WARNING: logic is hidden inside Python, not visible in the schema. """ if action == "create": if not email: return "Error: Email required for creation" # Runtime error, not schema error return f"Created user {email}" elif action == "delete": if not user_id: return "Error: User ID required" return f"Deleted {user_id}" return "Action completed" """ ...

Szczegółowe narzędzia z jasnymi nazwami i parametrami

Schemat wejściowy każdego narzędzia jest rygorystyczny. Jeśli LLM chce utworzyć użytkownika, musi podać adres e-mail. Jeśli chcesz usunąć, musisz podać identyfikator. Nie musisz zgadywać.

...
@mcp.tool()
def create_user(email: str, role: str = "viewer") -> str:
    """Register a new user. Returns the new User ID."""
    # Logic is purely creation
    return "user_123"

@mcp.tool()
def delete_user(user_id: str) -> str:
    """Permanently remove a user by their ID."""
    # Logic is purely deletion
    return f"User {user_id} deleted"

@mcp.tool()
def update_user_role(user_id: str, new_role: str) -> str:
    """Change an existing user's permission level."""
    return f"User {user_id} is now {new_role}"

    ...

Nazwa narzędzia: manage_user

Opis: „Użyj tego narzędzia, aby tworzyć, aktualizować, usuwać lub pobierać użytkowników”.

...
@mcp.tool()
def manage_user(
    action: Literal["create", "update", "delete", "get"],
    user_id: Optional[str] = None,
    email: Optional[str] = None,
    role: Optional[str] = "viewer"
) -> str:
    """
    Use this to manage users.
    WARNING: logic is hidden inside Python, not visible in the schema.
    """
    if action == "create":
        if not email: return "Error: Email required for creation" # Runtime error, not schema error
        return f"Created user {email}"
    elif action == "delete":
        if not user_id: return "Error: User ID required"
        return f"Deleted {user_id}"
    
    return "Action completed"
    """
    ...

Deklarowanie adnotacji dotyczących narzędzi ze względów bezpieczeństwa

Skonfiguruj adnotacje protokołu w definicjach narzędzi, aby przekazywać informacje o zachowaniu podczas wykonywania i aktywować wbudowane bramki bezpieczeństwa w odpowiednich usługach Google:

Bramki potwierdzenia w czasie działania: odpowiednie usługi Google używają flag annotations.destructiveHint: true i annotations.openWorldHint: true jako kluczowych do wywoływania próśb o potwierdzenie użytkownika w czasie działania. Zadeklaruj destructiveHint: true w przypadku działań zmieniających stan, zapisujących lub niszczących i ustaw openWorldHint: true dla narzędzi, które wchodzą w interakcję z otwartym światem lub środowiskami zewnętrznymi, aby platforma natywnie prosiła użytkownika o potwierdzenie przed wykonaniem działania.
Wskazówka dotycząca zapytania tylko do odczytu: ustaw readOnlyHint: true w narzędziach do wysyłania zapytań, które tylko pobierają dane bez modyfikowania stanu backendu.
Domyślne ustawienia adnotacji jawnych: zgodnie ze specyfikacją protokołu Model Context Protocol pominięcie readOnlyHint powoduje, że klienci domyślnie zakładają readOnlyHint: false i destructiveHint: true ze względów bezpieczeństwa. Wyraźne deklarowanie adnotacji we wszystkich narzędziach zapewnia przewidywalne kierowanie do odpowiedniego modelu i prawidłowe bezpieczeństwo wykonywania.

Opisy narzędzi

Opis jest jedynym kontekstem, na podstawie którego model decyduje, czy narzędzie może rozwiązać dany problem. Przestrzegaj tych wskazówek dotyczących pisania opisów:

Pisz instrukcje, a nie komentarze

Opisy narzędzi powinny mieć formę instrukcji, a nie komentarzy do kodu, które często są pasywne. Duże modele językowe dobrze reagują na dyrektywy.

Wyjaśnij, jak to zrobić.

Dobry opis wypełnia lukę między „Mam narzędzie” a „Wiem, jak włączyć to narzędzie do rozmowy”.

Wyjaśnij, dlaczego

Odróżnij to narzędzie od podobnych, na przykład: „Używaj tego narzędzia w przypadku użytkowników wewnętrznych, a customer_update w przypadku użytkowników zewnętrznych”.

Podaj link.

Powiedz modelowi, gdzie ma szukać argumentów, na przykład „z narzędzia order_search”.

Określanie formatu

Określ jednostki (metry lub stopy) i formaty (daty ISO, wersje semantyczne).

Unikaj swobody modelu

Nie instruuj modelu, aby używał „najlepszego osądu”, ani nie sugeruj opcjonalnych, nieukierunkowanych działań.

Przykłady opisów narzędzi

Poniższe przykłady pokazują, co należy, a czego nie należy robić podczas pisania opisów narzędzi.

Polecane Niezalecane

Polecane	Niezalecane
Nadrzędne źródło danych "Aktualizuje adres e-mail użytkownika. Musisz użyć identyfikatora UUID „id” zwróconego przez narzędzie `search_users`. Nie próbuj odgadywać identyfikatorów użytkowników”. (Wyraźnie łączy dane wyjściowe jednego narzędzia z danymi wejściowymi tego narzędzia).	"Aktualizuje adres e-mail użytkownika." (Model może odgadnąć identyfikator, np. 12345).
Format i ograniczenie „Zaplanuj spotkanie. „date” musi być w formacie ISO 8601 (RRRR-MM-DD). Jeśli użytkownik powie „jutro” lub użyje innego względnego odniesienia, oblicz datę na podstawie bieżącego kontekstu”.	„Zaplanuj spotkanie na podany dzień”. (wygląda poprawnie dla człowieka (np. „jutro”), ale nie przechodzi weryfikacji schematu (wymaga „2025-10-12”))
Oczekiwane dane wyjściowe "Pobiera logi serwera. Zwraca ostatnie 50 wierszy nieprzetworzonego tekstu. Aby uniknąć limitów tokenów, poproś o analizę mniejszych przedziałów czasu”.	„Pobierz logi serwera”. (Model może wywołać narzędzie, oczekując podsumowania, otrzymać nieprzetworzony zrzut JSON o rozmiarze 5 MB i pogorszyć wrażenia użytkownika).
`@mcp.tool() def update_campaign_status(campaign_id: str, status: str) -> str: """ Promotes or pauses an advertising campaign. CRITICAL USAGE RULES: 1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'. 2. 'status': Must be exactly one of: ['active', 'paused', 'archived']. Returns: A confirmation string with the new status and timestamp. """ # Logic... ...` Ten opis działa jak miniinstrukcja. Obsługuje źródło (skąd pobrać identyfikator), ograniczenia (prawidłowe typy wyliczeniowe) i działanie.	`@mcp.tool() def update_campaign_status(id: str, status: str) -> str: """ Updates the campaign status in the database. """ # Logic...` W tym przypadku całą pracę wykonują nazwy zmiennych. Model musi zgadywać, jakie są prawidłowe wartości parametru „status”.

Nadrzędne źródło danych

"Aktualizuje adres e-mail użytkownika. Musisz użyć identyfikatora UUID „id” zwróconego przez narzędzie search_users. Nie próbuj odgadywać identyfikatorów użytkowników”.

(Wyraźnie łączy dane wyjściowe jednego narzędzia z danymi wejściowymi tego narzędzia).

"Aktualizuje adres e-mail użytkownika."

(Model może odgadnąć identyfikator, np. 12345).

Format i ograniczenie

„Zaplanuj spotkanie. „date” musi być w formacie ISO 8601 (RRRR-MM-DD). Jeśli użytkownik powie „jutro” lub użyje innego względnego odniesienia, oblicz datę na podstawie bieżącego kontekstu”.

„Zaplanuj spotkanie na podany dzień”.

(wygląda poprawnie dla człowieka (np. „jutro”), ale nie przechodzi weryfikacji schematu (wymaga „2025-10-12”))

Oczekiwane dane wyjściowe

"Pobiera logi serwera. Zwraca ostatnie 50 wierszy nieprzetworzonego tekstu. Aby uniknąć limitów tokenów, poproś o analizę mniejszych przedziałów czasu”.

„Pobierz logi serwera”.

(Model może wywołać narzędzie, oczekując podsumowania, otrzymać nieprzetworzony zrzut JSON o rozmiarze 5 MB i pogorszyć wrażenia użytkownika).

@mcp.tool()
def update_campaign_status(campaign_id: str, status: str) -> str:
    """
    Promotes or pauses an advertising campaign.
    
    CRITICAL USAGE RULES:
    1. 'campaign_id': Must be the 32-character UUID retrieved from 'list_campaigns'.
    2. 'status': Must be exactly one of: ['active', 'paused', 'archived'].
    
    Returns: A confirmation string with the new status and timestamp.
    """
    # Logic...

    ...

Ten opis działa jak miniinstrukcja. Obsługuje źródło (skąd pobrać identyfikator), ograniczenia (prawidłowe typy wyliczeniowe) i działanie.

@mcp.tool()
def update_campaign_status(id: str, status: str) -> str:
    """
    Updates the campaign status in the database.
    """
    # Logic...

W tym przypadku całą pracę wykonują nazwy zmiennych. Model musi zgadywać, jakie są prawidłowe wartości parametru „status”.

Parametry narzędzia

Oprócz samego narzędzia opisz parametry, aby były jednoznaczne.

Typy jawne

Używaj silnych, konkretnych typów (string, integer, boolean, array).

Używanie typów wyliczeniowych w przypadku stałych zbiorów wartości

Jeśli parametr akceptuje tylko stały zestaw wartości (np. daylight, cool, warm), wymień je w tablicy enum. To znacznie poprawia dokładność.

Jasno określ wymagane parametry

Wyraźnie określ, które parametry są wymagane do działania funkcji.

Zastosuj semantyczne dopasowywanie schematów

Podczas integracji aplikacji może być wymagane dopasowanie schematu semantycznego parametrów narzędzi do branży, dla której tworzysz aplikację. Podczas procesu wprowadzania otrzymasz oczekiwany schemat branżowy (schemat JSON).

Przykłady parametrów narzędzia

Poniższe przykłady pokazują, co należy, a czego nie należy robić w przypadku parametrów narzędzia.

Polecane	Niezalecane
Formaty i jednostki argumentów radius: „Promień w metrach. Must be a float > 0." (zapobiega halucynacjom jednostek)	radius: „Promień okręgu”.
Formaty i kontekst identyfikatorów user_id: identyfikator UUID bazy danych (np. 550e8400-e29b...). Nie używaj tu adresów e-mail”. Uwaga: zgodnie ze sprawdzonymi metodami wszystkie pola identyfikatorów numerycznych powinny być traktowane jako wartości typu ciąg znaków. Jeśli Twój identyfikator może mieć co najmniej 10 cyfr, istnieje ryzyko, że zostanie on obcięty przez systemy wewnętrzne (wymuszony w kontenerze 32-bitowym) i ta wersja będzie używana przez model w przyszłych wywołaniach narzędzi. (zapobiega błędom typu)	user_id: „Identyfikator użytkownika”.
Oczekiwane wartości zwracane "Aktualizuje rekord i zwraca zaktualizowany obiekt JSON z nową sygnaturą czasową". (Informuje model, że nie musi wywoływać narzędzia „get” natychmiast po „update”, aby zweryfikować zmianę).	„Aktualizuje rekord”.
`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """ Searches server error logs using Lucene syntax (e.g. 'level:ERROR AND service:auth'). Args: query: A Lucene-formatted search string. limit: Max results to return. capped at 50. Returns: A formatted string of log entries with timestamps. """ ...`	`@mcp.tool() def search_logs(query: str, limit: int = 10) -> str: """Searches the logs.""" ...` LLM nie wie, jaką składnię obsługuje „zapytanie” (SQL? Wyrażenie regularne? Zwykły tekst?) Nie wie, jaki jest maksymalny „limit”.

Odpowiedzi i obsługa błędów

Zgodnie z podstawową zasadą Odpowiedź jest kolejnym promptem narzędzie raportuje wynik wykonania, zwracając ładunek danych, który jest następnie wklejany bezpośrednio do okna kontekstu LLM. To, czy wynik będzie pozytywny czy negatywny, określa, co stanie się dalej:

Jeśli się powiedzie: model potrzebuje wartości zwracanej, aby wiedzieć, co się stało, i zdecydować o następnym kroku.
Jeśli się nie powiedzie: model musi wiedzieć, dlaczego się nie udało i jak to naprawić. Awaria (błąd 500) zatrzymuje rozmowę, a opisowy komunikat o błędzie pozwala modelowi na samodzielną korektę.

Niezależnie od tego, czy podstawowa logika narzędzia działa prawidłowo, czy nie, musisz sformatować ładunek zwracanej wartości, aby model mógł go łatwo przeanalizować. Podczas pakowania danych odpowiedzi postępuj zgodnie z tymi sprawdzonymi metodami.

Użyj formatu JSON

Sformatuj uporządkowane dane w TextContent (ograniczenie tymczasowe). Ponieważ structuredContent nie jest jeszcze obsługiwany na platformie Connected Apps Platform, musisz ręcznie przekształcić dane na postać szeregową. Nawet jeśli zwracasz prostą listę, json.dumps().

Uwzględnianie adresów URL w odpowiedzi

Zwracane adresy URL powinny być stosunkowo krótkie i nie powinny zawierać wielu parametrów. Zalecamy korzystanie z usług skracania adresów URL, aby zmniejszyć liczbę tokenów i ryzyko halucynacji.

Samodzielnie opisujące się ładunki zapobiegające halucynacjom

Zawsze łącz nieprzetworzone kody lub wewnętrzne identyfikatory z wyświetlanymi nazwami zrozumiałymi dla człowieka, wyraźnymi jednostkami miary i zakresami referencyjnymi. Nigdy nie zwracaj skompresowanych kluczy słownikowych ani niezmapowanych kodów numerycznych, które zmuszają model do wnioskowania o kontekście.

Zaimplementuj solidną obsługę błędów

Zwracaj jasne, zrozumiałe komunikaty o błędach, aby model mógł zrozumieć, co poszło nie tak, i poinformować użytkownika. Zapoznaj się z obsługą błędów MCP.

Używanie try/except

Umieść logikę narzędzia w blokach try/except i zwracaj błędy w postaci ciągu tekstowego.

Podawanie błędów, które można naprawić

Zaproponuj w komunikacie o błędzie następny krok (np. „Najpierw spróbuj użyć narzędzia X”).

Potwierdź działania

Nie zwracaj pustych ciągów znaków w przypadku narzędzi, które mają efekty uboczne (tworzenie, aktualizowanie, usuwanie).

Przykłady odpowiedzi i obsługi błędów

Poniższe przykłady pokazują, co należy, a czego nie należy robić w przypadku odpowiedzi i obsługi błędów.

Polecane	Niezalecane
Jawna serializacja `... import json @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # GOOD: Returns '{"id": "cpu", "value": 42}' -> Valid JSON return json.dumps(result, indent=2)`	`... @mcp.tool() def query_metrics(metric_id: str) -> str: result = {"id": metric_id, "value": 42, "unit": "ms"} # BAD: Returns "{'id': 'cpu', 'value': 42}" -> Invalid JSON return str(result)`
Wykrywanie i informowanie `... @mcp.tool() def get_user_details(user_id: str) -> str: try: user = db.get_user(user_id) if not user: # GOOD: Informative error returned as content return f"Error: User with ID '{user_id}' not found. Please verify the ID using 'search_users'." return json.dumps(user) except Exception as e: return f"Error: Database connection failed ({str(e)}). Please try again later."` (Narzędzie technicznie „działa” (zwraca ciąg znaków), ale ciąg znaków zawiera szczegóły błędu. Model odczytuje te informacje, zdaje sobie sprawę, że „ten identyfikator nie istnieje”, i może poprosić użytkownika o podanie prawidłowego identyfikatora).	`... @mcp.tool() def get_user_details(user_id: str) -> str: # BAD: Unhandled exception if ID not found user = db.get_user(user_id) return json.dumps(user)` (Jeśli `get_user` się nie powiedzie, serwer zwróci błąd 500. LLM otrzymuje ogólny błąd wykonania i nie wie, dlaczego (czy identyfikator był nieprawidłowy? Baza danych nie działa? Odmowa dostępu?). Prawdopodobnie spróbuje ponownie użyć tych samych nieprawidłowych danych wejściowych).
Puste odpowiedzi `... @mcp.tool() def post_story(story_content: str) -> str: service_name = "story_service" api_client.post("/stories", json={"content": story_content}) # GOOD: Explicit confirmation of state change. return f"Service '{service_name}' successfully posted content. Status is now 'posted'."`	`... @mcp.tool() def post_story(storyContent: str): subprocess.post(["postsrv", "story", storyContent]) # BAD: Returns null/empty string. Model is confused.` Duże modele językowe często mają problemy z pustymi odpowiedziami. Mogą wygenerować halucynację „Narzędzie nie działa” lub po prostu powtórzyć wywołanie.
Samodzielnie opisujący się ładunek zapobiegający halucynacjom Zawsze łącz nieprzetworzone kody lub wewnętrzne identyfikatory z wyświetlanymi nazwami zrozumiałymi dla człowieka, jednoznacznymi jednostkami miary i normalnymi zakresami referencyjnymi. `{"lab_code": "2345-7", "display_name": "Glucose [Mass/volume] in Blood", "value": 105, "unit": "mg/dL", "reference_range": "70-99 mg/dL"}` (Dzięki temu model wie dokładnie, co oznacza dana wartość, i nie musi domyślać się jednostek ani progów referencyjnych).	nieprzetworzone identyfikatory, niestandardowa kompresja lub niezmapowane kody; Zwracanie nieprzetworzonych wewnętrznych identyfikatorów, skrótów ze słownika niestandardowego lub kodów numerycznych bez etykiet. `{"code": "2345-7", "v": 105}` (Model musi zgadywać, do czego odnosi się liczba 105, co prowadzi do halucynacji dotyczących jednostek, braku kontekstu lub niedokładnych wyjaśnień).

Obsługa błędów MCP

Ważne jest, aby prawidłowo obsługiwać błędy.

W przypadku błędów, które można naprawić (np. nieprawidłowy identyfikator użytkownika lub brak opcjonalnego parametru), zwróć w odpowiedzi narzędzia zwykły ciąg tekstowy zawierający opis błędu. Dzięki temu model może sprawdzić opinię, zrozumieć, co poszło nie tak, i samodzielnie poprawić błąd lub poprosić użytkownika o wyjaśnienie.
W przypadku błędów terminala (takich jak ograniczanie liczby żądań, błędy uwierzytelniania lub uprawnień albo przerwy w działaniu serwera backendu) zgłoś błąd McpError z odpowiednim kodem błędu, aby platforma mogła systematycznie obsługiwać błędy.

Przykładowa treść odpowiedzi z błędem (JSON)

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32302,
    "message": "User permission denied for the requested operation.",
    "data": null
  },
  "id": 1
}

Message zawiera zrzut JSON pola ErrorData MCP. Zwracając prawidłowy code i widoczny dla modelu message, platforma Connected Apps Platform może odczytać komunikat o błędzie i przekazać użytkownikowi przydatne wyjaśnienie w języku naturalnym. Na przykład: „Nie udało mi się znaleźć miejsca o tym identyfikatorze. Czy możesz sprawdzić nazwę?"

MCP umożliwia klientom łączenie się z serwerami MCP przy użyciu specyfikacji JSON-RPC 2.0. JSON-RPC ma pewne wstępnie zdefiniowane błędy wysyłane w przypadku często występujących błędów, takich jak nieprawidłowe żądanie, błędy analizy itp. Ten przewodnik opisuje, jak serwery MCP mogą odsyłać błędy niestandardowe.

Status Code	Wiadomość	Wykorzystanie	Czy musisz wyraźnie zwracać wartość?
Błędy użytkownika/klienta
-32300	USER_RATE_LIMITED	Użytkownik osiągnął maksymalny limit wykorzystania.	TAK
-32301	MISSING_REQUIRED_INFORMATION	Żądanie wejściowe nie zawiera wszystkich wymaganych informacji	TAK
-32302	USER_PERMISSION_DENIED	Użytkownik odmówił uprawnień do korzystania z narzędzia. Na przykład użytkownik musi mieć konto służbowe, spełniać wymagania dotyczące ograniczenia wiekowego, regionu itp. lub nie mieć subskrypcji narzędzia dla przedsiębiorstw.	TAK
Błędy aplikacji / błędy w logice biznesowej
-32400	RUNTIME_ERROR	Podczas wykonywania kodu serwera wystąpił błąd	TAK
-32401	NULL_POINTER_EXCEPTION	Próba uruchomienia wskaźnika/obiektu o wartości null	TAK
-32402	OUT_OF_MEMORY	Niewystarczająca ilość pamięci w kodzie serwera do przydzielenia obiektowi	TAK
Błędy infrastruktury
-32500	DEADLINE_EXCEEDED	Żądanie trwa dłużej niż dozwolony czas. Może to być spowodowane wieloma przyczynami, np. przeciążeniem serwera, problemami z siecią itp.	TAK
-32501	RESOURCE_EXHAUSTED	Na serwerze skończył się brak pamięci (OOM), miejsce na dysku, wątki, czas pracy procesora itp.	TAK
-32502	SERVICE_UNAVAILABLE	Usługa zależna (np.inny mikroserwis, baza danych, pamięć podręczna itp.) jest niedostępna.	TAK
Błędy JSON-RPC (te błędy są częścią transportu MCP)
-32700	PARSE_ERROR	Serwer nie mógł przetworzyć żądania	NIE
-32600	INVALID_REQUEST	Nieprawidłowy format żądania klienta	NIE
-32601	METHOD_NOT_FOUND	Nieprawidłowa nazwa narzędzia MCP	NIE
-32602	INVALID_PARAMS	Nieprawidłowe parametry żądania, w tym brakujące parametry lub niezgodne typy parametrów	NIE
-32603	INTERNAL_ERROR	Domyślna odpowiedź	NIE

Poniżej znajdziesz przykład, jak możesz zgłosić błąd MCP na serwerze za pomocą oficjalnego pakietu SDK w Pythonie (mcp). Zgłoś błąd McpError zawierający ładunek ErrorData, który pakiet SDK automatycznie serializuje do wymaganego formatu błędu JSON-RPC z wypełnionym stanem błędu.

from mcp import types
from mcp.shared.exceptions import McpError

@mcp.tool()
def foo_tool() -> list[types.TextContent]:
  """Always returns an error."""
  raise McpError(
    types.ErrorData(
        code=-32302, # USER_PERMISSION_DENIED
        message="Message to show to the model."
    ),
  )

Kontekst narzędzia

Odpowiednie usługi Google obsługują interfejs Tool Context API do przekazywania sygnałów do serwerów MCP. Ten interfejs API jest używany w przypadkach, które wymagają informacji poufnych – na przykład metadanych, które nie są częścią podstawowej definicji narzędzia, jak w przypadku języka narzędzi, które wymagają lokalizacji. Interfejs Tool Context API jest dostępny tylko w Połączonej konsoli.

Gdy zarejestrujesz sygnał taki jak current_user_location_fine w aplikacji w Połączonej konsoli, odpowiednie usługi Google będą uzupełniać żądania MCP tools/call o dodatkowy wpis _meta zawierający żądane dane. Zestaw obsługiwanych sygnałów:

current_user_location_fine (tylko Gemini, w przypadku dozwolonych branż)
user_locale
current_user_location_coarse

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "find-restaurant",
    "arguments": {"query": "restaurants near me"},
    "_meta": {
      "current_user_location_fine": {
        "latitude_degrees": 37.7749,
        "longitude_degrees": -122.4194,
        "accuracy_meters": 112.4221
      },
      "user_locale": {
        "language_code": "en",
        "region_code": "US"
      }
    }
  }
}

Aby rozpakować te dane:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("remote_mcp")

@mcp.tool()
async def find_restaurants(query: str, ctx: Context) -> str:
   # Access context directly from _meta
   request_context = ctx.request_context
   meta_dict = ctx.request_context.meta.model_dump() if ctx.request_context.meta else {}

   location_context = meta_dict.get("current_user_location_fine", {})
   lat = location_context.get("latitude_degrees")
   lng = location_context.get("longitude_degrees")
   if lat and lng:
       return f"Finding '{query}' near ({lat}, {lng})"
   return f"Finding '{query}' (no location provided)"

renderowanie UX,

Aplikacje MCP

Odpowiednie usługi Google obsługują integracje z aplikacjami MCP w przypadku wybranych ścieżek użytkownika, aby umożliwić tworzenie niestandardowych interfejsów użytkownika. Postępuj zgodnie ze specyfikacją, aby uzyskać ogólne instrukcje integracji.

Integracja aplikacji MCP w odpowiednich usługach Google wiąże się z tymi zastrzeżeniami.

Pozyskiwanie zasobów podczas rejestracji

Odpowiednie usługi Google pobierają zasoby interfejsu podczas przetwarzania narzędzia, podobnie jak listę i opisy narzędzi. Oznacza to, że wszelkie aktualizacje zasobów, np. zmiany w kodzie JavaScript, nie będą automatycznie uwzględniane i będą wymagały ponownego przetworzenia przez narzędzie.

Rozmiar pojedynczego zasobu interfejsu nie może przekraczać 15 MB, a łączny rozmiar zasobów interfejsu na serwerze nie może przekraczać 100 MB.

Zasoby interfejsu muszą używać jednego z obsługiwanych typów MIME: text/html, text/javascript, text/css lub text/html;profile=mcp-app. Niestandardowe lub specyficzne dla platformy typy MIME nie przejdą weryfikacji podczas przesyłania do podglądu.

Wytyczne dotyczące dostawców usług dla twórców

Odpowiednie usługi Google są zgodne z oficjalną specyfikacją aplikacji MCP, która obejmuje CSP [1], [2], i będą blokować wszelkie żądania naruszające dyrektywy CSP.

W przypadku odpowiednich usług Google należy dodatkowo dodać blob: i data: do CSP, jeśli są używane. Nie zostaną one dodane domyślnie. To deweloper decyduje, czy dodać je do CSP.

Wyjątek script-src

Dozwolone są tylko te dyrektywy: unsafe-inline (dodawana domyślnie), wasm-unsafe-eval i data: (jeśli jest uwzględniona w resource_domains). Jeśli element iframe wczytuje skrypty zewnętrzne, można to rozwiązać, łącząc JS z HTML lub używając hasha integralności zasobów podrzędnych (SRI).

Opcja 1. Umieszczenie kodu JS w kodzie HTML lub pakiecie (najprostsza metoda)
- Kod JS pakietu:
  - Umieść zawartość pliku component-init.js bezpośrednio w tagach <script> w ładunku HTML zwracanym dla zasobu interfejsu:
```
<script>
// Paste component-init.js content directly here
</script>
```
- Usuń tagi zdalne <script src>
  - Usuń <script src="https://api.mycompany.com/..."> odwołania z dokumentu HTML.
- Narzędzie do ponownego przetwarzania i aktualizowania
Opcja 2. Użyj hasha integralności zasobów podrzędnych (SRI):

Użyj tej opcji, jeśli skrypt musi być hostowany zewnętrznie pod adresem https://api.company.com/....
- Obliczanie hasza SHA-256 skryptu
  - Wygeneruj hasz SHA-256 w formacie base64 dla component-init.js
- Dodaj hasz do resourceDomains (musi zawierać prefiks sha256-, aby pasował do atrybutu integrity)
- Zaktualizuj tag HTML <script>
  - Dodaj atrybuty integrity i crossorigin do tagu skryptu w widżecie HTML.
- Sprawdzanie nagłówka CORS w sieci CDN lub na serwerze
  - Upewnij się, że api.company.com obsługuje component-init.js z Access-Control-Allow-Origin: * (lub zezwala na scf.usercontent.goog), aby przeglądarka mogła odczytać treść odpowiedzi na potrzeby weryfikacji SRI.
- Narzędzie do ponownego przetwarzania i aktualizowania

Wytyczne dotyczące bezpieczeństwa w opisie narzędzia MCP

Opis jest jedynym kontekstem, który model ma do zrozumienia możliwości narzędzia, dlatego musi być napisany dokładnie i bezpiecznie, aby zapobiec niezamierzonym zachowaniom. Podczas tworzenia opisów narzędzi postępuj zgodnie z tymi wytycznymi.

Opisz funkcje, ale nie narzucaj zachowania. Opis musi dokładnie opisywać, co robi narzędzie, a nie wydawać polecenia modelowi, aby wykonał kolejne działania.
Określ zakres i wymagania. Jasno określ główny cel narzędzia, konkretne okoliczności (Kiedy), w których należy go używać, oraz wszystkie wymagane Dane wejściowe (parametry/argumenty).
Zapewnij prawdziwość informacji. Opis musi być zgodny z kodem narzędzia. Nie twierdzić, że narzędzie jest tylko do odczytu, jeśli wykonuje operację zapisu lub usuwania.

Zagrożenia dla bezpieczeństwa i sposoby ich unikania

Obszar ryzyka	Polecane	Unikaj tego za wszelką cenę.
Wstrzykiwanie promptów	Używaj obiektywnego, deklaratywnego języka, aby jasno określić cel i funkcje narzędzia.	używać poleceń w trybie rozkazującym, aby zastąpić zachowanie modelu lub zmienić przepływy systemowe (np. „MUSISZ powiedzieć…”, „Po bieganiu MUSISZ…”). Terminy imperatywne, takie jak MUSI lub KRYTYCZNY, są dopuszczalne tylko podczas definiowania ograniczeń parametrów strukturalnych lub reguł użytkowania.
	Użyj standardowego, prostego formatowania tekstu opisu narzędzia.	używać formatowania przyciągającego uwagę, np. nadmiernej liczby wielkich liter i tagów takich jak `VERY IMPORTANT:` lub `CRITICAL`;
	Skup się wyłącznie na funkcji narzędzia i oczekiwanym działaniu.	zawierać instrukcje dotyczące odgrywania ról lub polecenia ignorowania poprzednich instrukcji;
Ukrywanie i przejmowanie narzędzi	Upewnij się, że opis jest konkretny i ogranicza się do rzeczywistych, powiązanych funkcji narzędzia.	tworzyć zbyt ogólnych lub niejasnych opisów narzędzi ani twierdzić, że jedno narzędzie wykonuje wiele niepowiązanych funkcji;
	Wybierz unikalną, opisową i sensowną nazwę narzędzia.	używają nazwy narzędzia, która jest nieznaczną odmianą nazwy zaufanego narzędzia, lub nazwy ogólnej (np. `do_everything_tool`, `assistant_tool`);
	Nie wymieniaj w opisie nazw innych aplikacji ani narzędzi platform zewnętrznych.	wyraźnie odwoływać się do innych narzędzi ani tworzyć nowych reguł dotyczących tego, kiedy i jak należy używać innych narzędzi.
	Zezwól planiście modelu na wybór najbardziej odpowiedniego narzędzia na podstawie kontekstu użytkownika.	zawierać sformułowań ograniczających konkurencję ani żadnych promptów SEO, które instruują model, aby preferował Twoje narzędzie nad podobnymi.
Manipulowanie wyzwalaczami	Opis nie odnosi się do ogólnych zwrotów z historii rozmów ani na nie nie reaguje.	tworzenie logiki warunkowej, która wywołuje szkodliwe działanie na podstawie typowych, nieszkodliwych wyrażeń użytkownika (np. „dziękuję”, „podsumowując”).
Nadużywanie parametrów	Zdefiniuj tylko parametry niezbędne do działania narzędzia i używaj nazw specyficznych dla danych wejściowych (np. `file_id`, `search_term`).	Zdefiniuj parametry funkcji z nazwami, które odzwierciedlają stan wewnętrzny agenta (np. `system_prompt`, `conversation_history`, `full_context`).
Wydobycie danych	Wbudowane funkcje ochrony prywatności – nieprzejrzyste identyfikatory i uwierzytelnianie zarządzane przez hosta. Używaj identyfikatorów, które nie są poufne, a nie nieprzetworzonych informacji umożliwiających identyfikację. Wszystkie dane muszą być przetwarzane w autoryzowanych, bezpiecznych granicach i nie mogą być wymieniane w publicznym opisie jako wysyłane na zewnątrz. Wykonywanie narzędzia będzie dziedziczyć uprawnienia w sposób niewidoczny dla użytkownika za pomocą uzgadniania OAuth. Wszelkie informacje poufne należy usunąć przed wysłaniem ich do odpowiednich usług Google.	Prosić użytkownika o podanie informacji umożliwiających identyfikację, informacji PHI lub innych danych osobowych bądź informacji poufnych, danych osobowych lub firmowych baz danych albo informacji o podmiocie w jakimkolwiek charakterze, który narusza warunki korzystania z odpowiednich usług Google. Wspominać o wysyłaniu jakichkolwiek danych użytkownika (zapytania, lokalizacji, kontekstu) do nieautoryzowanych adresów URL innych firm, usług logowania lub systemów zewnętrznych ani wymagać takiego wysyłania.

Sprawdzone metody dotyczące funkcji i nazewnictwa

Oprócz zabezpieczenia opisu narzędzia musisz upewnić się, że model może je niezawodnie wybrać i wykonać bez pomyłek. Stosuj te sprawdzone metody dotyczące funkcji i nazewnictwa:

Dokładność parametrów. Upewnij się, że wszystkie nazwy i typy parametrów w opisie dokładnie odpowiadają rzeczywistej implementacji narzędzia.
Sensowne nazewnictwo. Nazwa narzędzia powinna być wyraźną wskazówką dotyczącą jego funkcji. Unikaj zbyt ogólnych nazw, takich jak „execute”. Nazwa musi być też spójna z szerszym ekosystemem narzędzi.

Dodatek: infrastruktura i lista dozwolonych sieci

Jeśli infrastruktura hostingu, brama interfejsów API lub zapora sieciowa ogranicza połączenia przychodzące według źródłowego adresu IP, dodaj do listy dozwolonych te bloki CIDR ruchu wychodzącego Google:

108.177.64.0/20
142.250.88.0/22
172.217.80.0/20
192.178.20.0/22
192.179.0.0/20
74.125.232.0/24
136.121.40.0/21

Upewnij się, że Twoje środowisko zezwala na ruch z tych zakresów adresów IP na porcie HTTPS 443, aby odpowiednie usługi Google mogły połączyć się ze zdalnym serwerem MCP w celu inicjalizacji MCP, wykrywania narzędzi i wykonywania żądań.

Standardy integracji połączonych aplikacji MCP Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Podstawowe zasady

Obsługa wersji,

Zgodność wersji protokołu MCP

Specyfikacja protokołu transportowego

Instrukcje dotyczące serwera

Traktuj jako „wskazówkę dla modelu” z kontekstem użycia.

Uzupełniaj, nie powielaj

Przykłady instrukcji dotyczących serwera

Wytyczne dotyczące narzędzi

Konwencje nazewnictwa narzędzi

Używaj intuicyjnych, zrozumiałych dla człowieka nazw.

Używaj odpowiedniego stylu wielkości liter

Używaj jednoznacznych nazw w formie czasownik-rzeczownik

Szczegółowość narzędzia

Traktowanie narzędzi jako niepodzielnych punktów końcowych

Używanie bardziej płaskich schematów

Przestrzeganie zasad dotyczących wstępnej agregacji i ładunku

Pomiń narzędzia wewnętrzne i metanarzędzia

Zalecenia i ograniczenia dotyczące szczegółowości narzędzi

Deklarowanie adnotacji dotyczących narzędzi ze względów bezpieczeństwa

Opisy narzędzi

Pisz instrukcje, a nie komentarze

Wyjaśnij, jak to zrobić.

Wyjaśnij, dlaczego

Podaj link.

Określanie formatu

Unikaj swobody modelu

Przykłady opisów narzędzi

Parametry narzędzia

Typy jawne

Używanie typów wyliczeniowych w przypadku stałych zbiorów wartości

Jasno określ wymagane parametry

Zastosuj semantyczne dopasowywanie schematów

Przykłady parametrów narzędzia

Odpowiedzi i obsługa błędów

Użyj formatu JSON

Uwzględnianie adresów URL w odpowiedzi

Samodzielnie opisujące się ładunki zapobiegające halucynacjom

Zaimplementuj solidną obsługę błędów

Używanie try/except

Podawanie błędów, które można naprawić

Potwierdź działania

Przykłady odpowiedzi i obsługi błędów

Obsługa błędów MCP

Kontekst narzędzia

renderowanie UX,

Aplikacje MCP

Pozyskiwanie zasobów podczas rejestracji

Wytyczne dotyczące dostawców usług dla twórców

Wytyczne dotyczące bezpieczeństwa w opisie narzędzia MCP

Dodatek: infrastruktura i lista dozwolonych sieci

Standardy integracji połączonych aplikacji MCP