Skip to content

Document GitHub App connect flow and ai-mcp-github-pat flag #1111

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

Document GitHub App connect flow and ai-mcp-github-pat flag #1111

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
28 changes: 27 additions & 1 deletion guides/ai-agents/mcp-servers.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,8 @@ Once an MCP server is connected to an agent, the agent can use its tools as part
- **Confluence** — search the knowledge base for context before answering, or publish summaries. See [Getting started with the Atlassian Remote MCP Server](https://support.atlassian.com/atlassian-rovo-mcp-server/docs/getting-started-with-the-atlassian-remote-mcp-server/).
- **Lightdash Docs** — give agents access to the complete Lightdash documentation so they can answer questions about Lightdash concepts, configuration, and best practices. URL: `https://docs.lightdash.com/mcp`, auth type `None`. See [Lightdash Docs MCP](/references/integrations/lightdash-mcp#lightdash-docs-mcp).
- **Slack** — search channels, threads, and messages so agents can pull team context into answers. Slack requires extra app setup — see [Connect the Slack MCP server](#connect-the-slack-mcp-server).
- Any other service that exposes a remote MCP server (GitHub, Jira, internal tooling, etc.)
- **GitHub** — let the agent read the code behind your metrics. GitHub has a guided one-click connect flow — see [Connect GitHub](#connect-github).
- Any other service that exposes a remote MCP server (Jira, internal tooling, etc.)

The agent decides when to call MCP tools based on the user's question and the agent's instructions, the same way it decides when to query your data.

Expand Down Expand Up @@ -65,6 +66,31 @@ MCP servers are configured per project and can be attached to one or more agents
</Step>
</Steps>

## Connect GitHub

GitHub has a one-click **Connect GitHub** button in **Settings → AI agents → MCP servers**. Use it instead of adding the hosted GitHub MCP URL as a generic bearer-token server — the guided flow handles credentials for you and picks the most secure connection mode your organization has available.

### Connection modes

| Mode | Credentials | Availability |
| ---- | ----------- | ------------ |
| **Lightdash GitHub App** (default) | The Lightdash GitHub App mints a short-lived installation token per agent run. Nothing long-lived is stored. | Requires an org admin to install the Lightdash GitHub App from **Organization settings → Integrations**. |
| **Personal access token** | You paste a long-lived GitHub PAT that is stored (encrypted) and reused for every agent run. | Off by default. Enable the `ai-mcp-github-pat` feature flag per org as a stopgap for orgs that cannot install the GitHub App. [Contact Lightdash support](mailto:support@lightdash.com) to turn it on. |

The **Connect GitHub** button behaves based on what's available for your org:

- **GitHub App installed** — clicking **Connect GitHub** connects the server in one click using the app installation.
- **`ai-mcp-github-pat` on and GitHub App not installed** — clicking **Connect GitHub** opens a modal to paste a personal access token.
- **Neither available** — clicking **Connect GitHub** shows a modal pointing an admin to install the Lightdash GitHub App from **Organization settings → Integrations**.

<Info>
Storing long-lived GitHub personal access tokens as MCP credentials expands the blast radius of an application compromise into your source repositories. We recommend the GitHub App for every org that can install it. When `ai-mcp-github-pat` is off, any previously stored PATs are also ignored at runtime.
</Info>

<Info>
Preview projects never accept GitHub PATs, even if the flag is enabled on the parent organization.
</Info>

## Connect the Slack MCP server

Slack's hosted MCP server (`https://mcp.slack.com/mcp`) needs more setup than most providers because Slack [does not support Dynamic Client Registration](https://docs.slack.dev/ai/slack-mcp-server/). You must bring your own OAuth client, and Slack only accepts clients backed by a registered Slack app that is either **published in the Slack Marketplace** or an **internal app** in your workspace — unlisted apps are rejected. The steps below walk through creating an internal Slack app and connecting it to Lightdash.
Expand Down
Loading