docs/netdata-ai/mcp/mcp-connections.md
An alert tells you what changed. It rarely tells you why. That answer usually lives somewhere else — the pull request that shipped minutes earlier, the incident already open in PagerDuty, the runbook sitting in Confluence.
MCP Connections let Netdata AI reach those systems directly. Through the Model Context Protocol (MCP), Netdata Cloud acts as an MCP client and connects to the tools your team already runs, reading from them while it investigates. It correlates the metrics and anomalies Netdata detects on every node with the context in your stack — so it can tie a latency spike to the deploy that caused it, link an anomaly to the incident already tracking it, and surface the relevant runbook without you going to look for it.
This is the reverse of connecting an AI client to Netdata. Here, Netdata reaches out to your MCP servers. To instead connect an AI assistant (Claude, Cursor, a CLI) to Netdata's own MCP server, see Supported AI Clients.
Go to Settings → AI → MCP Connections.
Select an integration, such as GitHub, or choose Custom MCP Server to point at your own HTTPS MCP endpoint.
Choose an authentication method (see Authentication methods below). The available options depend on the integration.
Provide the required configuration parameters — such as the connection name, or your account URL with the provider — then click Connect & discover tools.
An account URL is the address you use to reach the provider, including your organization's subdomain. For PagerDuty that is https://acme.pagerduty.com, or https://acme.eu.pagerduty.com if your account is hosted in the EU. Netdata derives the correct regional endpoint from it, and refuses the connection if the account you authorize with is not the one configured here.
For OAuth integrations, you'll be redirected to the provider to authorize Netdata. Once you approve, you're sent back and the connection is established automatically.
For GitHub with OAuth, authorizing is not enough on its own — the Netdata MCP GitHub App also has to be installed on the organization that owns your repositories. See GitHub: OAuth or a personal access token.
On success, Netdata retrieves the tools the remote MCP server exposes. Select the tools you want to make available for this connection.
Netdata only enables read-only tools. The server may advertise tools that create, modify, or delete data (for example "Create an incident" or "Delete a team") — these appear in the discovered list but cannot be enabled from the Netdata UI. Netdata AI reads context; it does not act on your systems.
Click Save Changes to complete the configuration. Enabled tools are not active until you save.
GitHub offers both authentication methods — OAuth 2.0 and Personal Access Token — and what limits Netdata AI is different in each.
With OAuth, what Netdata AI can read is decided when the Netdata MCP GitHub App is installed, not when you connect. Authorizing the OAuth flow can succeed while the connection still returns nothing, because the app is not installed on the organization that owns the repositories.
https://github.com/orgs/YOUR-ORG/sso — before you install or authorize. Without an active session the authorization does not cover that organization.Every permission the app asks for is read-only: repository metadata and contents, issues, pull requests, workflow runs and artifact metadata, deployments, discussions, commit statuses, security alerts, and Copilot agent task and variable metadata. GitHub shows the full list on the installation screen. The app cannot write to your repositories, and it subscribes to no webhook events.
Each user still connects individually through OAuth, so a user sees only the repositories they can already access, within what the installation allows. An organization owner uninstalling the app revokes access for everyone at once; a user revoking it under GitHub → Settings → Applications revokes only their own connection.
The Personal Access Token method needs no app installation — Netdata authenticates to GitHub with the token you paste in, so the token's own permissions decide what is reachable. Three things to plan for:
Revoking is done on the token itself, in GitHub → Settings → Developer settings → Personal access tokens — which disconnects the integration for the entire Space at once.
| Method | Who authenticates | Scope | When to use |
|---|---|---|---|
| Bearer token | One shared token, entered once | All users in the Space share this single token | Providers that authenticate with an access token; simplest setup |
| OAuth | Each user authorizes individually with their own credentials | Per user | The standard method for most integrations; keeps per-user access boundaries intact |
For OAuth integrations, enabling a tool does not widen access: each user is still restricted by their own permissions on the underlying resource. A user only sees what they're already allowed to see in the connected system.
Once a connection is saved, Netdata AI can use it during investigations. You control which servers are used, per conversation and per report.
During a conversation you can see all MCP servers enabled for your Space and toggle them on or off for that conversation. The Connected tools row shows which servers Netdata AI will draw on as it answers.
See Conversations for more on live, interactive troubleshooting.
When generating a report, you can select which MCP servers to include before the report runs — so a scheduled Insight or a Custom Investigation can pull in code changes, incidents, or on-call context alongside the metrics.
See Investigations and Scheduled Reports.