AJV schema validation fails with Google's Managed BigQuery MCP - can't resolve reference Range

[isaacraja]

What happened?

When connecting to Google's managed BigQuery MCP server (https://bigquery.googleapis.com/mcp), LibreChat successfully receives the tools/list response from Google, but fails to parse the tool schemas due to AJV being unable to resolve $ref references within $defs.

The MCP server correctly returns tools like list_dataset_ids, get_dataset_info, execute_sql, etc., but LibreChat's schema validation throws:

Error: can't resolve reference Range from id #

As a result, no tools appear in the LibreChat UI, even though the server is marked as "initialized".

Expected behavior: Tools from Google's BigQuery MCP should appear in the LibreChat UI and be usable in agents/chats.

Version Information

• LibreChat Version: v0.8.1-rc1 (Docker: ghcr.io/danny-avila/librechat-dev:latest)
• @modelcontextprotocol/sdk: bundled version
• Deployment: Docker Compose on Ubuntu

Steps to Reproduce

1. Enable Google's managed BigQuery MCP on your GCP project:

   gcloud beta services mcp enable bigquery.googleapis.com --project=YOUR_PROJECT

2. Configure LibreChat with the BigQuery MCP:

   mcpServers:
     bigquery-google:
       type: streamable-http
       url: https://bigquery.googleapis.com/mcp
       timeout: 60000
       oauth:
         authorization_url: https://auth.cloud.google/authorize
         token_url: https://sts.googleapis.com/v1/oauthtoken
         client_id: YOUR_CLIENT_ID
         client_secret: YOUR_CLIENT_SECRET
         redirect_uri: https://your-domain.com/oauth/callback
         scope: "https://www.googleapis.com/auth/cloud-platform"

3. Restart LibreChat

4. Complete OAuth flow (works correctly)

5. Check logs - tools/list response is received but parsing fails

6. Check UI - no tools appear for the bigquery-google MCP server

Relevant log output

1. OAuth and initialization (works):

{"level":"info","message":"[MCP][bigquery-google] OAuth Required: true"}
{"level":"info","message":"[MCP][bigquery-google] Initialized in: 201ms"}

2. tools/list response received (works - tools are returned by Google):

{"level":"debug","message":"[MCP][User: REDACTED][bigquery-google] Transport received: {\"jsonrpc\":\"2.0\",\"id\":2,\"result\":{\"tools\":[{\"name\":\"list_dataset_ids\",\"inputSchema\":{...},\"outputSchema\":{\"$defs\":{\"ListFormatDataset\":{...}},\"properties\":{\"datasets\":{\"items\":{\"$ref\":\"#/$defs/ListFormatDataset\"}}}}}]}}"}

3. AJV schema validation fails:

{"level":"error","message":"[MCP][User: REDACTED][bigquery-google] Connection verification failed: can't resolve reference Range from id #","missingRef":"Range","missingSchema":"Range","stack":"Error: can't resolve reference Range from id #\n    at Object.code (/app/node_modules/ajv/dist/vocabularies/core/ref.js:21:19)\n    at keywordCode (/app/node_modules/ajv/dist/compile/validate/index.js:464:13)\n    at /app/node_modules/ajv/dist/compile/validate/index.js:185:25\n    at CodeGen.code (/app/node_modules/ajv/dist/compile/codegen/index.js:439:13)\n    at CodeGen.block (/app/node_modules/ajv/dist/compile/codegen/index.js:568:18)\n    at schemaKeywords (/app/node_modules/ajv/dist/compile/validate/index.js:185:13)"}

4. Final failure:

{"level":"error","message":"[MCP][User: REDACTED][bigquery-google] Failed to fetch tools:: can't resolve reference Range from id #"}

Root Cause Analysis

Google's BigQuery MCP returns complex JSON schemas with:

• $defs for type definitions (e.g., Range, Access, Expr, TableReference)
• $ref to reference those definitions (e.g., "$ref": "#/$defs/Range")

LibreChat's AJV validator fails to resolve these internal references. This appears to be because AJV needs the $defs to be pre-registered or needs reference resolution enabled.

Suggested Fix Options

1. Use AJV with addMetaSchema or addSchema to pre-register $defs before validation
2. Skip outputSchema validation entirely (only validate inputSchema which is simpler)
3. Use a JSON Schema dereferencer like json-schema-ref-parser before passing to AJV
4. Disable strict schema validation for MCP tools as a fallback
5. Catch the error and continue with tools that have simpler schemas

Additional Context

• Google announced managed MCP servers on December 10, 2025
• This affects integration with bigquery.googleapis.com/mcp, and likely other Google managed MCP servers (Maps, Compute Engine, GKE)
• Custom MCP servers with simpler schemas work fine
• Related: MCP - Handling Complex Schemas + System Prompt #5429, MCP - Handling Complex Schemas + System Prompt #6773 (complex schema handling)

[danny-avila]

This is an incompatibility with the underlying MCP SDK, and should be reported there: https://github.com/modelcontextprotocol/typescript-sdk.

And possibly reported to the authors of the BigQuery MCP Server, as well.

It looks like this issue there might be relevant: modelcontextprotocol/typescript-sdk#283