From 0de40249e198f24657f83a3aaa18044459109bf3 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Mon, 18 May 2026 07:59:30 +0000
Subject: [PATCH] docs: document MCP server connection status and error
 reporting

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

diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx
index d2f0cfb3..767f328f 100644
--- a/guides/ai-agents/mcp-servers.mdx
+++ b/guides/ai-agents/mcp-servers.mdx
@@ -83,6 +83,17 @@ 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.
 
+## Connection status
+
+Each MCP server shows its current runtime status in the servers list so you can tell at a glance whether agents can reach it. If a server fails to connect or returns an error during use, Lightdash records the latest error message alongside the status. Use this to debug issues like expired credentials, network errors, or invalid endpoints without having to reproduce the failure in a chat.
+
+If a server stays in an error state:
+
+- Check the **URL** is reachable and correct.
+- For **Bearer token** auth, verify the token has not expired or been revoked.
+- For **OAuth**, click **Reconnect** to refresh the authorization.
+- Re-test by attaching the server to an agent and sending a message; the status updates after the next connection attempt.
+
 ## Security
 
 - All credentials (bearer tokens and OAuth tokens) are encrypted at rest.