From 29f01893700cca7d70be2012dcb906025aff2f51 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 10 Jul 2026 00:42:37 +0000 Subject: [PATCH 1/2] docs: add MCP server broken-connection recovery guidance --- guides/ai-agents/mcp-servers.mdx | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx index 86a972ab..08383f14 100644 --- a/guides/ai-agents/mcp-servers.mdx +++ b/guides/ai-agents/mcp-servers.mdx @@ -140,6 +140,42 @@ 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. + +### Re-test connection + +The refresh icon next to the **Connected** badge (also available as **Re-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 \** 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. That prompt is posted **once per user + server** — subsequent turns in the same thread will not re-post it while the server is still waiting for that user to sign in. + +Disconnecting the server (from the MCP servers page, or from Slack) resets the prompt, so it will appear again the next time the agent needs that user to sign in. + ## Security - All credentials (bearer tokens and OAuth tokens) are encrypted at rest. From 6067e94b737e2e4aceb6ab18a95b8e568953bce8 Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Sat, 11 Jul 2026 00:42:16 +0000 Subject: [PATCH 2/2] docs: rename to Test connection and refine Slack MCP prompt rules --- guides/ai-agents/mcp-servers.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx index acccc5cf..c215c8d1 100644 --- a/guides/ai-agents/mcp-servers.mdx +++ b/guides/ai-agents/mcp-servers.mdx @@ -151,9 +151,9 @@ Tokens get rotated, OAuth sessions expire, and popup windows get closed. When a Open **Settings → AI agents → MCP servers** and use the controls on the server card. -### Re-test connection +### Test connection -The refresh icon next to the **Connected** badge (also available as **Re-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: +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. @@ -177,9 +177,12 @@ If a user abandons the OAuth popup partway through, the server no longer stays s ### 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. That prompt is posted **once per user + server** — subsequent turns in the same thread will not re-post it while the server is still waiting for that user to sign in. +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: -Disconnecting the server (from the MCP servers page, or from Slack) resets the prompt, so it will appear again the next time the agent needs that user to sign in. +- 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