Jak diagnozować HTTP 400 w Gemini powodowane przez niezgodne schematy narzędzi MCP

Gdy po zmianie backendu każde żądanie do modelu zaczyna kończyć się HTTP 400, pierwszym podejrzanym zwykle jest token, limit konta albo błędne mapowanie modelu. Przy dużej liczbie narzędzi MCP warto jednak sprawdzić jeszcze jedną rzecz: czy Gemini w ogóle akceptuje wszystkie przesyłane deklaracje funkcji.

W opisanym przypadku OpenCode miał około 359 deklaracji narzędzi MCP. Po przełączeniu na backend Gemini każde żądanie kończyło się AI_APICallError 400 około 3 sekundy po rozpoczęciu strumienia. Konto raportowało 100% limitu, token był prawidłowy, a alias poprawny. Powtarzalność błędu przy każdym żądaniu wskazywała więc na problem wcześniejszy niż samo wykonanie modelu.

Indeksy z odpowiedzi 400 potrafią wskazać konkretny serwer MCP

Ładunek błędu zawierał problemy z walidacją deklaracji o indeksach 349, 351 i 354 spośród 359. W komunikatach pojawiały się między innymi:

only allowed for OBJECT type

$type == Type.ARRAY

Przy kilkuset narzędziach takie indeksy są bardzo użyteczne. Zamiast przeglądać cały zestaw deklaracji, można odtworzyć ich kolejność i sprawdzić tylko pozycje wskazane przez Gemini.

W tym przypadku wszystkie trzy deklaracje należały do jednego serwera MCP. To mocno zawęziło dalszą diagnozę.

Problemem były schematy dopuszczające null

Wskazane deklaracje zawierały pola tablicowe i obiektowe opisane jako unie schematu JSON dopuszczające null.

Raport na forum Google AI Developers opisuje tę samą granicę zgodności: użycie nullable w schemacie wywoływania funkcji może prowadzić do HTTP 400 Bad Request. Istotnym szczegółem jest to, że function_declarations obsługują wybrany podzbiór schematu OpenAPI 3.0, a dokumentacja dla tego mechanizmu różniła się od dokumentacji response_schema.

Nie wystarczy więc stwierdzić, że schemat jest poprawnym JSON Schema albo że działa u innego dostawcy.

Schemat narzędzia jest częścią kontraktu z dostawcą modelu

Ten sam zestaw deklaracji działał z dostawcą innym niż Gemini. Problem nie leżał więc w ogólnej poprawności narzędzia MCP, tylko w zgodności konkretnego sposobu opisania jego parametrów z backendem Gemini.

To praktyczny niezmiennik dla systemów obsługujących wielu dostawców: deklaracja funkcji zaakceptowana przez jeden backend nie musi zostać zaakceptowana przez drugi.

Dwie zmiany natychmiast przywróciły działanie

Diagnozę potwierdziły dwa rozwiązania. Pierwszym było poprawienie wskazanych deklaracji przez użycie nullable: true. Drugim — wyłączenie serwera MCP, do którego należały deklaracje o zgłoszonych indeksach.

W obu przypadkach Gemini zaczęło ponownie działać. Zgodność między indeksami z odpowiedzi HTTP 400 a deklaracjami konkretnego serwera pozwoliła więc naprawić problem bez przypadkowego zmieniania konfiguracji konta, tokenów czy aliasów modeli.

Oddziel dostęp do konta od walidacji deklaracji

Przy podobnym błędzie warto potraktować jako dwa osobne testy pytanie, czy konto ma dostęp do Gemini, oraz pytanie, czy Gemini akceptuje komplet przesyłanych function_declarations.

Jeżeli każde żądanie kończy się HTTP 400, warto najpierw:

sprawdzić, czy odpowiedź zawiera indeksy błędnych deklaracji,

powiązać te indeksy z konkretnymi narzędziami MCP,

przeanalizować pola obiektowe i tablicowe dopuszczające null.

Dopiero po wykluczeniu błędu walidacji schematów ma sens wracać do diagnozy konta, limitów czy mapowania modelu.