Diagnosing Gemini HTTP 400 Errors Caused by Incompatible MCP Tool Schemas

Recognize the failure pattern

An HTTP 400 on every request does not necessarily indicate an authentication, quota, or model-mapping problem. In one production OpenCode setup, roughly 359 MCP tool declarations were registered. After switching to a Gemini-family backend, every request failed with an AI_APICallError and HTTP 400 about three seconds after stream start. The account had 100% quota, a valid token, and a correctly mapped model alias.

That combination is a useful diagnostic pattern: the provider can be reachable and the account can be healthy while the complete function-declaration payload is rejected during the observed request. The relevant question is therefore not only whether the credentials and model name are correct, but also whether every MCP tool schema is accepted by the selected provider.

Map indexed validation errors to MCP tools

The HTTP 400 payload contained function-declaration validation errors at declaration indexes 349, 351, and 354 out of 359. The messages included only allowed for OBJECT type and $type == Type.ARRAY.

These indexes turn a large tool list into a bounded investigation. Preserve the declaration order used to construct the provider request, then use each reported index to identify the corresponding MCP tool. In this case, the declarations at the reported indexes all belonged to one MCP server. The indexes therefore connected the provider-level validation failure to a specific server rather than to the whole MCP configuration indiscriminately.

The diagnostic value is in the combination of the index and the validation message. The index identifies which declaration failed; the message indicates which part of the declaration shape the provider rejected. Treating those two pieces together makes the remediation traceable instead of relying on trial and error.

Identify nullable unions in array and object fields

The declarations identified by indexes 349, 351, and 354 belonged to one MCP server. Its array and object fields used JSON-Schema nullable union types.

In this incident, the reported validation errors corresponded to nullable array and object fields in the identified declarations; the evidence does not establish that declaration count alone caused the failure. The affected declarations used nullable unions in fields whose schemas described arrays and objects, and Gemini’s validation rejected the resulting function declarations.

A separate Google AI Developers Forum report describes the same boundary from another angle: using the nullable property in a function-calling schema produced an HTTP 400 Bad Request from the Gemini API. The report also describes the function_declarations schema as a selected subset of an OpenAPI 3.0 schema object and notes that its schema documentation diverged from the documentation for structured-output response_schema.

That distinction matters when a schema appears valid under a broader JSON-Schema or OpenAPI interpretation. A declaration can be acceptable to one schema consumer while still failing validation as a Gemini function declaration.

Treat function declarations as a provider compatibility boundary

The same tool payload worked with a non-Gemini provider. This comparison isolates the relevant difference: the MCP tool declarations were not universally unusable, but they were incompatible with the Gemini-family function-declaration validation encountered here.

The practical invariant is provider-specific compatibility. An MCP server can expose a payload that one provider accepts and another rejects. Consequently, authentication and quota checks do not substitute for checking the schema accepted by the selected provider. The production failure and the forum report both point to the function-declaration schema boundary, while the non-Gemini result shows that provider choice changes the outcome for the same tool payload.

Remediate the affected declarations or server

Two changes restored the provider immediately in the same session. The affected fields were converted to Gemini-compatible nullability using nullable: true, or the affected MCP server was disabled.

The first option keeps the server available while changing the declaration shape at the provider boundary. The second removes the declarations that trigger validation. In this session, either change restored the provider after the indexed declarations were implicated.

These should be treated as compatibility remedies for the affected integration. The important diagnostic requirement is that the selected remedy corresponds to the indexed declarations: change the nullable declarations identified through the error indexes, or disable the server to confirm that those declarations are responsible.

Make the diagnosis independently testable

The incident supports separating two checks that are often conflated. One check concerns account access: in the reported setup, the token, quota, and model alias were healthy. The other concerns the provider’s acceptance of the MCP function declarations: the Gemini-family backend rejected declarations at indexes 349, 351, and 354, while a non-Gemini provider accepted the same tool payload.

A provider integration should therefore be evaluated against its function-declaration compatibility contract independently of authentication and quota. When a Gemini request fails with HTTP 400, inspect the indexed validation errors, map them to the MCP tools, and examine nullable array and object fields before treating the failure as an account or model-configuration problem.

The central lesson is narrow but consequential: a single incompatible MCP schema can prevent an otherwise healthy Gemini integration from serving requests. Declaration indexes make the failure location concrete; provider comparison distinguishes compatibility from general tool validity; and Gemini-compatible nullability or disabling the affected server provides a direct remediation path.