Handle metrics_with_related read timeouts (#770)

## Summary

The `metrics_with_related` GQL query is known to be a bit slow. We are
seeing some timeouts in our backend that seem to be related to this.
Since this path optionally adds extra context, it isn't necessary for
`list_metrics` to behave correctly. Getting dimensions and entities can
still be achieved through individual tool calls.

## Checklist
- [x] I have performed a self-review of my code
- [x] I have made corresponding changes to the documentation (in
https://github.com/dbt-labs/docs.getdbt.com) if required -- Mention it
here
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes

Author: DevonFulcher

.changes/unreleased/Under the Hood-20260511-133701.yaml

@@ -0,0 +1,3 @@
+kind: Under the Hood
+body: Handle metrics_with_related read timeouts
+time: 2026-05-11T13:37:01.154417-05:00

src/dbt_mcp/semantic_layer/client.py

@@ -1,6 +1,7 @@
 import asyncio
 import base64
 import json
+import logging
 from collections.abc import Callable
 from contextlib import AbstractContextManager
 from datetime import date, datetime, time, timedelta
@@ -29,15 +30,17 @@
     GetMetricsCompiledSqlError,
     GetMetricsCompiledSqlResult,
     GetMetricsCompiledSqlSuccess,
+    ListMetricsResponse,
     MetricToolResponse,
     OrderByParam,
     QueryMetricsError,
     QueryMetricsResult,
     QueryMetricsSuccess,
     SavedQueryToolResponse,
-    ListMetricsResponse,
 )
 
+logger = logging.getLogger(__name__)
+
 
 def DEFAULT_RESULT_FORMATTER(table: pa.Table) -> str:
     """Convert PyArrow Table to JSON string with ISO date formatting.
@@ -130,18 +133,35 @@ async def list_metrics(
             {"query": GRAPHQL_QUERIES["metrics"], "variables": {"search": search}},
         )
         metrics_count = len(metrics_result["data"]["metricsPaginated"]["items"])
+        dimensionless_response = ListMetricsResponse(
+            metrics=[
+                MetricToolResponse(
+                    name=m.get("name"),
+                    type=m.get("type"),
+                    label=m.get("label"),
+                    description=m.get("description"),
+                    metadata=(m.get("config") or {}).get("meta"),
+                )
+                for m in metrics_result["data"]["metricsPaginated"]["items"]
+            ]
+        )
         if metrics_count and metrics_count <= config.metrics_related_max:
             # Re-fetch with the same search filter using a single query that includes
             # per-metric dimensions and entities. This avoids the N×2 parallel calls
             # approach: the nested GQL fields return per-metric data accurately (not
             # an intersection like dimensionsPaginated with multiple metrics would).
-            full_result = await submit_request(
-                config,
-                {
-                    "query": GRAPHQL_QUERIES["metrics_with_related"],
-                    "variables": {"search": search},
-                },
-            )
+            try:
+                full_result = await submit_request(
+                    config,
+                    {
+                        "query": GRAPHQL_QUERIES["metrics_with_related"],
+                        "variables": {"search": search},
+                    },
+                    timeout=5.0,
+                )
+            except Exception as e:
+                logger.warning(f"Error fetching metrics with related: {e}")
+                return dimensionless_response
             return ListMetricsResponse(
                 metrics=[
                     MetricToolResponse(
@@ -156,18 +176,7 @@ async def list_metrics(
                     for m in full_result["data"]["metricsPaginated"]["items"]
                 ]
             )
-        return ListMetricsResponse(
-            metrics=[
-                MetricToolResponse(
-                    name=m.get("name"),
-                    type=m.get("type"),
-                    label=m.get("label"),
-                    description=m.get("description"),
-                    metadata=(m.get("config") or {}).get("meta"),
-                )
-                for m in metrics_result["data"]["metricsPaginated"]["items"]
-            ]
-        )
+        return dimensionless_response
 
     async def list_saved_queries(
         self,

src/dbt_mcp/semantic_layer/gql/gql_request.py

@@ -7,12 +7,13 @@
 async def submit_request(
     sl_config: SemanticLayerConfig,
     payload: dict,
+    timeout: float = 30.0,
 ) -> dict:
     if "variables" not in payload:
         payload["variables"] = {}
     payload["variables"]["environmentId"] = sl_config.prod_environment_id
 
-    async with httpx.AsyncClient(timeout=30.0) as client:
+    async with httpx.AsyncClient(timeout=timeout) as client:
         response = await client.post(
             sl_config.url,
             json=payload,

tests/unit/semantic_layer/test_client.py

@@ -343,7 +343,7 @@ def _make_query_dispatcher():
     query by checking for the presence of nested 'dimensions {' in the query string.
     """
 
-    def dispatch(_, payload):
+    def dispatch(_, payload, **kwargs):
         query = payload.get("query", "")
         if "metricsPaginated" in query:
             if "dimensions {" in query: