diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx
index fdacb4f8..c215c8d1 100644
--- a/guides/ai-agents/mcp-servers.mdx
+++ b/guides/ai-agents/mcp-servers.mdx
@@ -145,6 +145,45 @@ 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.
 
+## Recovering a broken connection
+
+Tokens get rotated, OAuth sessions expire, and popup windows get closed. When a connection breaks you can fix it in place — you no longer have to remove and re-add the server (which would orphan it from any agents it was attached to).
+
+Open **Settings → AI agents → MCP servers** and use the controls on the server card.
+
+### Test connection
+
+The refresh icon next to the **Connected** badge (also available as **Test connection** in the ⋯ menu) re-runs the live check against the MCP server and persists the result. Use it after rotating a token upstream or if you suspect the badge is stale:
+
+- If the server responds, the badge stays **Connected**.
+- If the credential is invalid or the server is unreachable, the badge flips to **Reconnect required** instead of staying stuck on green.
+
+### Update a bearer token
+
+For bearer-token servers, the ⋯ menu on the server card now has an **Update token** action. It opens a modal where the name and URL are read-only and you paste the new token.
+
+The new token is validated against the MCP server *before* it replaces the old one:
+
+- **Validation passes** — the stored token is rotated and tools are refreshed.
+- **Validation fails** — the old token stays intact and the error is shown as a toast, so a bad paste can never lock you out.
+
+Tokens are encrypted at rest and are never returned by the API after being set, so **Update token** is the only way to change them.
+
+### Reconnect an OAuth server
+
+For OAuth servers, click **Reconnect** (or **Sign in to \<server name\>** if you have never connected) on the server card to run the OAuth flow again. Personal credentials only affect your own account; a project manager can reconnect the shared credential the same way.
+
+If a user abandons the OAuth popup partway through, the server no longer stays stuck on **Waiting for OAuth to complete…** indefinitely — after about 5 minutes the card reports **not connected** so you can retry or remove it. **Remove** and **Disconnect** stay available in the ⋯ menu the whole time, so you always have an escape hatch even while a connect is in-flight.
+
+### Slack agents: OAuth login prompt
+
+When an agent running in Slack needs a user to log in to an OAuth MCP server, Lightdash posts an ephemeral prompt in the thread with a link to connect. To keep threads clean, the prompt is only posted:
+
+- On the first message of a Slack thread — not on follow-up turns within the same thread.
+- **Once per user + server** across threads while that user is still not connected to that server.
+
+Disconnecting the server (from the MCP servers page, or from Slack) resets the prompt, so it will appear again the next time a new thread needs that user to sign in.
+
 ## Security
 
 - All credentials (bearer tokens and OAuth tokens) are encrypted at rest.