Diagnozowanie błędów HTTP 400 Gemini powodowanych przez niezgodne schematy narzędzi MCP

Rozpoznaj wzorzec awarii

Błąd HTTP 400 przy każdym żądaniu nie musi oznaczać problemu z uwierzytelnianiem, limitem ani mapowaniem modelu. W jednej produkcyjnej konfiguracji OpenCode zarejestrowano około 359 deklaracji narzędzi MCP. Po przełączeniu na backend z rodziny Gemini każde żądanie kończyło się błędem AI_APICallError i HTTP 400 około trzech sekund po rozpoczęciu strumienia. Konto miało 100% dostępnego limitu, prawidłowy token i poprawnie zmapowany alias modelu.

To połączenie objawów stanowi użyteczny wzorzec diagnostyczny: dostawca może być osiągalny, a konto może działać prawidłowo, podczas gdy cały ładunek deklaracji funkcji zostaje odrzucony w trakcie obsługi żądania. Dlatego trzeba sprawdzić nie tylko poprawność danych uwierzytelniających i nazwy modelu, lecz także to, czy wybrany dostawca akceptuje schematy wszystkich narzędzi MCP.

Powiąż indeksy błędów walidacji z narzędziami MCP

Ładunek HTTP 400 zawierał błędy walidacji deklaracji funkcji dla indeksów 349, 351 i 354 spośród 359. Komunikaty obejmowały only allowed for OBJECT type oraz $type == Type.ARRAY.

Indeksy zamieniają długą listę narzędzi w ograniczone dochodzenie. Zachowaj kolejność deklaracji używaną do tworzenia żądania do dostawcy, a następnie użyj każdego zgłoszonego indeksu, aby zidentyfikować odpowiadające mu narzędzie MCP. W tym przypadku deklaracje ze zgłoszonych indeksów należały do jednego serwera MCP. Indeksy powiązały więc błąd walidacji na poziomie dostawcy z konkretnym serwerem, zamiast wskazywać bez rozróżnienia na całą konfigurację MCP.

Wartość diagnostyczna wynika z połączenia indeksu i komunikatu walidacji. Indeks wskazuje deklarację, która nie przeszła walidacji, a komunikat określa, którą część jej struktury dostawca odrzucił. Zestawienie tych dwóch informacji sprawia, że naprawa jest możliwa do prześledzenia, zamiast opierać się na metodzie prób i błędów.

Zidentyfikuj unie dopuszczające null w polach tablicowych i obiektowych

Deklaracje wskazane przez indeksy 349, 351 i 354 należały do jednego serwera MCP. Jego pola tablicowe i obiektowe używały typów unii schematu JSON dopuszczających wartość null.

W tym przypadku zgłoszone błędy walidacji odpowiadały polom tablicowym i obiektowym dopuszczającym wartość null w zidentyfikowanych deklaracjach; dostępne dowody nie potwierdzają, że sama liczba deklaracji spowodowała awarię. Dotknięte deklaracje używały unii dopuszczających wartość null w polach, których schematy opisywały tablice i obiekty, a walidacja Gemini odrzucała wynikowe deklaracje funkcji.

Osobny raport na forum Google AI Developers opisuje tę samą granicę z innej perspektywy: użycie właściwości nullable w schemacie wywoływania funkcji powodowało błąd HTTP 400 Bad Request z API Gemini. Raport opisuje również schemat function_declarations jako wybrany podzbiór obiektu schematu OpenAPI 3.0 i wskazuje, że jego dokumentacja schematu różniła się od dokumentacji response_schema używanego dla ustrukturyzowanych danych wyjściowych.

To rozróżnienie ma znaczenie, gdy schemat wygląda na prawidłowy według szerszej interpretacji JSON Schema lub OpenAPI. Deklaracja może być akceptowana przez jeden odbiornik schematu, a mimo to nie przejść walidacji jako deklaracja funkcji Gemini.

Traktuj deklaracje funkcji jako granicę zgodności z dostawcą

Ten sam ładunek narzędzi działał z dostawcą innym niż Gemini. Porównanie to izoluje istotną różnicę: deklaracje narzędzi MCP nie były nieużyteczne w każdym środowisku, lecz nie były zgodne z walidacją deklaracji funkcji rodziny Gemini napotkaną w tym przypadku.

Praktyczny niezmiennik brzmi: zgodność zależy od dostawcy. Serwer MCP może udostępniać ładunek akceptowany przez jednego dostawcę i odrzucany przez innego. Dlatego sprawdzenie uwierzytelniania i limitu nie zastępuje weryfikacji schematu akceptowanego przez wybranego dostawcę. Awaria produkcyjna i raport z forum wskazują na granicę schematu deklaracji funkcji, a wynik dla dostawcy innego niż Gemini pokazuje, że wybór dostawcy zmienia rezultat dla tego samego ładunku narzędzi.

Napraw wskazane deklaracje lub serwer

W tej samej sesji dostawcę natychmiast przywróciły dwie zmiany. Dotknięte pola przekonwertowano na zgodny z Gemini sposób określania wartości null za pomocą nullable: true albo wyłączono dotknięty serwer MCP.

Pierwsza opcja pozwala zachować dostępność serwera, zmieniając strukturę deklaracji na granicy dostawcy. Druga usuwa deklaracje wywołujące błąd walidacji. W tej sesji każda z tych zmian przywróciła działanie dostawcy po wskazaniu deklaracji na podstawie indeksów.

Należy traktować je jako sposoby zapewnienia zgodności dla tej konkretnej integracji. Najważniejsze diagnostycznie jest dopasowanie rozwiązania do deklaracji wskazanych przez indeksy błędów: zmień deklaracje dopuszczające wartość null zidentyfikowane na podstawie indeksów albo wyłącz serwer, aby potwierdzić, że to one odpowiadają za problem.

Uczyń diagnozę niezależnie testowalną

Ten przypadek przemawia za rozdzieleniem dwóch kontroli, które często są ze sobą mylone. Jedna dotyczy dostępu do konta: w opisanej konfiguracji token, limit i alias modelu działały prawidłowo. Druga dotyczy akceptowania przez dostawcę deklaracji funkcji MCP: backend z rodziny Gemini odrzucał deklaracje o indeksach 349, 351 i 354, podczas gdy dostawca inny niż Gemini akceptował ten sam ładunek narzędzi.

Integrację z dostawcą należy więc oceniać pod kątem zgodności z jego wymaganiami dotyczącymi deklaracji funkcji, niezależnie od uwierzytelniania i limitu. Gdy żądanie Gemini kończy się błędem HTTP 400, sprawdź indeksy błędów walidacji, powiąż je z narzędziami MCP i przeanalizuj pola tablicowe oraz obiektowe dopuszczające wartość null, zanim uznasz problem za błąd konta lub konfiguracji modelu.

Najważniejszy wniosek jest wąski, ale istotny: pojedynczy niezgodny schemat MCP może uniemożliwić obsługę żądań przez działającą poza tym integrację Gemini. Indeksy deklaracji konkretyzują miejsce awarii, porównanie dostawców odróżnia problem zgodności od ogólnej poprawności narzędzi, a zastosowanie zgodnego z Gemini sposobu określania wartości null lub wyłączenie dotkniętego serwera daje bezpośrednią drogę naprawy.