Skip to content

docs: document one-click GitHub MCP connect for AI agents #770

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
mintlify wants to merge 1 commit into from
Closed

docs: document one-click GitHub MCP connect for AI agents #770

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions guides/ai-agents/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Loading