From a4430960fcefbf7c49a3df9cb9390aedbe3b60f9 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 2 Jun 2026 14:51:20 +0000
Subject: [PATCH] docs(ai-agents): document MCP connection timeout and override
 env var

---
 guides/ai-agents/mcp-servers.mdx | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx
index 75bba2a4..88aa3d0f 100644
--- a/guides/ai-agents/mcp-servers.mdx
+++ b/guides/ai-agents/mcp-servers.mdx
@@ -140,6 +140,20 @@ The agent pulls the data from your warehouse, generates the summary, and appends
 
 The agent searches Confluence for the canonical definition, then answers using both the doc and your data.
 
+## Troubleshooting
+
+### "The MCP server took too long to respond and was disconnected"
+
+Lightdash applies a 20-second timeout when connecting to an MCP server and when discovering its tools. If the server is unreachable or hangs, it is marked as errored with this message and you can retry once the server is healthy. When attached to an agent, a slow server only stalls itself — other MCP servers still load and respond.
+
+If you self-host Lightdash and need a longer (or shorter) timeout — for example because an internal MCP server is behind a slow proxy — set `MCP_CONNECTION_TIMEOUT_MS` on your deployment:
+
+```bash
+MCP_CONNECTION_TIMEOUT_MS=30000
+```
+
+The value is in milliseconds and defaults to `20000`. Lightdash Cloud uses the default.
+
 ## Security
 
 - All credentials (bearer tokens and OAuth tokens) are encrypted at rest.