From f6cd132f31b32c88da336cbca3e62552c2c43f24 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Thu, 4 Jun 2026 16:39:31 +0000
Subject: [PATCH] docs: document one-click GitHub MCP connect for AI agents

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

diff --git a/guides/ai-agents/mcp-servers.mdx b/guides/ai-agents/mcp-servers.mdx
index 75bba2a4..c93cc761 100644
--- a/guides/ai-agents/mcp-servers.mdx
+++ b/guides/ai-agents/mcp-servers.mdx
@@ -91,6 +91,41 @@ Personal OAuth is enabled by default on every OAuth server. To also allow a shar
   Bearer-token servers do not support personal credentials — every user shares the same token.
 </Info>
 
+## Connect GitHub with one click
+
+If your project's dbt connection lives on GitHub, you can attach a GitHub MCP server to an agent in one click — no URL, OAuth app, or manual setup required. The agent uses it to read the dbt code behind your metrics so it can answer questions like "what does this metric measure?" or "which model defines `revenue`?".
+
+Look for the **Connect GitHub** button in two places:
+
+- **Agent settings → MCP servers** — attach GitHub to an agent permanently.
+- **New thread → MCP connections** — connect GitHub for the current conversation only.
+
+<Steps>
+  <Step title="Click Connect GitHub">
+    Lightdash opens a modal explaining how to mint a GitHub personal access token.
+  </Step>
+  <Step title="Create a fine-grained personal access token">
+    Open [GitHub → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new) and:
+    - Under **Repository access**, select only the repos you want the agent to read.
+    - Under **Permissions → Repository**, set **Contents** to **Read-only**.
+    - Generate the token (it starts with `github_pat_`).
+  </Step>
+  <Step title="Choose who can use the token">
+    If you're a project manager, pick the credential scope:
+    - **Just me** — the token is only used when you chat with the agent. Other users connect their own tokens.
+    - **Whole project** — the token is shared with everyone using the agent in this project.
+
+    Non-managers always connect a personal token.
+  </Step>
+  <Step title="Paste the token and connect">
+    Lightdash encrypts the token at rest and attaches the GitHub MCP server to the agent (or the thread). You can remove or rotate it any time from the agent's settings.
+  </Step>
+</Steps>
+
+<Tip>
+  Per-user tokens are the safer default — actions are attributed to the right person and each user only grants access to their own repos. Use a shared token when you want every member of the project to read the same set of repos without managing individual credentials.
+</Tip>
+
 ## Choose which tools are exposed to the agent
 
 Each MCP server exposes a set of tools, and you decide which ones the agent can use. Open an MCP server in your project settings and use **Tool permissions** to enable just the tools that fit the agent's job.