--- title: "MCP servers | Grafana Cloud documentation" description: "Connect external Model Context Protocol (MCP) servers to Assistant to search issues, browse code, and complete tasks with manual tool confirmations." --- > For a curated documentation index, see [llms.txt](/llms.txt). For the complete documentation index, see [llms-full.txt](/llms-full.txt). # MCP servers Model Context Protocol (MCP) servers extend Grafana Assistant capabilities by connecting to external systems like issue trackers, code repositories, and project management tools. You can investigate incidents by searching for related issues and code changes, automate tasks by creating issues and updating tickets, retrieve knowledge from documentation repositories, and collaborate by sharing findings across team tools. You can also orchestrate these tools using [Skills](/docs/grafana-cloud/platform/grafana-assistant/platform/skills). By defining skill instructions, you can guide agents to perform specific actions, like creating linear tickets or sending Slack notifications, when specific alerts fired. > Warning > > You’re responsible for any MCP server you connect to Assistant, including its security, reliability, data access, and actions performed through its tools. Only connect servers you trust, use least‑privilege tokens, and review tool calls carefully. ## Before you begin You need permissions and feature access to work with MCP servers. - **Permissions**: Refer to [Manage Assistant access with RBAC](/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac) for roles and permissions. - **Feature access**: Your administrator must enable the integrations feature in the Assistant app configuration. Your MCP server must meet these requirements: - **Remote only**: Only remote MCP servers are supported. Local MCP servers aren’t supported. - **Network accessible**: The server must be accessible from your Grafana instance over the network. - **Protocol**: The server must implement the Model Context Protocol specification. - **Response time**: Tool discovery must complete within 60 seconds. Tool calls can run for up to 5 minutes. MCP servers support these authentication methods: - **OAuth**: The server supports MCP OAuth. You can connect your own account to a **Just me** or **Everybody** server. Each user of an **Everybody** server connects separately, so their tool access follows their own account. Assistant discovers OAuth settings automatically when the server supports discovery. Servers that don’t support dynamic client registration can use a pre-registered OAuth client. - **HTTP headers**: The server accepts custom HTTP headers, for example, `Authorization: Bearer ` or `X-API-Key: `. Header values are part of the server configuration and are shared with everyone who can use an **Everybody** server. Use a shared service account token instead of a personal token for shared header authentication. Headers can also be configured alongside personal OAuth connections. - **GitHub App**: For GitHub **Everybody** servers, you can authenticate using a GitHub App installed on your organization instead of a personal access token. This produces short-lived tokens that aren’t tied to any individual user. Refer to [GitHub App authentication](#github-app-authentication) for setup details. - **Unauthenticated**: The server is publicly accessible and doesn’t require authentication. ## View pre-configured servers Pre-configured servers provide quick setup for popular integrations: - **Development and code**: Cursor Cloud Agents, GitHub, GitLab, Atlassian, Postman, Buildkite, Jenkins, and Semgrep - **Project management and collaboration**: Linear, Asana, Notion, Airtable, Miro, monday.com, and Jira through Atlassian - **Deployment and infrastructure**: Netlify, Vercel, Cloudflare, Pulumi, Railway, Render, Port, Aiven, CoreWeave, DigitalOcean, Heroku, and Runpod - **Observability, testing, and data**: Polar Signals, Honeycomb, New Relic, Embrace, Datadog, Dynatrace, Snowflake, ClickHouse, Elasticsearch, MongoDB, Better Stack, OctoPerf, and Webflow - **Creative and collaboration tools**: Canva - **Business and customer data**: Salesforce For authentication requirements and API token setup, refer to the documentation for each service. Some providers support more than one auth method. For example, Embrace supports both interactive OAuth and service account bearer tokens. Datadog requires API key headers, including `DD_API_KEY` and `DD_APPLICATION_KEY`, and may require you to update the server URL for your Datadog site. Salesforce requires a pre-registered OAuth client: create an External Client App in your Salesforce org, register the **Redirect URL** that Assistant displays, and enter the app’s consumer key as the **Client ID**. Enter the consumer secret as well if the app requires one. To access private GitHub repositories in an organization, install the [GitHub App](https://github.com/apps/grafana-assistant/installations/select_target). ## Configure an MCP server Add and configure any MCP server (pre-configured or custom): 1. Open the Assistant **Settings**, click **Integrations**, and select the **MCP servers** tab. 2. Under **MCP Servers**: - For pre-configured servers: Click **Add** for the preset you want to use. - For custom servers: Click **Add Custom Server**. 3. Enter a **Name** to identify the server. 4. Optionally disable **Enabled** if you want to configure the server without activating it immediately. 5. Choose a **Scope**: - **Just me**: The server is visible only to you. - **Everybody**: The server is visible to all users in the Grafana instance. Each user can connect their own OAuth account, or you can configure shared HTTP headers or a GitHub App installation. 6. Enter or confirm the **MCP Server URL**, for example, `https://my.mcp.server.com/mcp`. - Pre-configured servers have the URL pre-filled. - Custom servers require you to provide the endpoint URL. 7. If the server requires header-based authentication, add its header under **HTTP headers**. The header doesn’t have to be named `Authorization`. For **Everybody** servers, use a shared service account or integration token. 8. Leave **Advanced OAuth settings** at its default for automatic OAuth discovery. If the server requires specific scopes or doesn’t support dynamic client registration, refer to [Configure an OAuth client](#configure-an-oauth-client). 9. Click **Add server**. Assistant checks the connection and attempts to discover tools. If the server requests OAuth, click **Connect my account** and complete the sign-in window. For an **Everybody** server, other users open the same MCP server in Assistant settings and connect their own accounts. The server remains configured if you close the sign-in window before connecting. After validation, filter which tools to enable for conversations. Start with one to five tools for optimal performance. More than 16 tools significantly impacts response time and accuracy. ### Configure tool access and approvals After Assistant discovers the server’s tools, configure which tools are available and how they are approved. Each discovered tool can be enabled or disabled. The tool list labels tools as **Read** or **Write** so you can understand whether a tool only retrieves information or can modify data in the connected service. For each tool, choose an approval policy: - **Default**: Use Assistant’s default approval behavior for that tool. - **Auto-approve**: Allow Assistant to run the enabled tool without asking first. - **Always ask**: Require explicit approval every time Assistant wants to run the tool, even if another configuration would allow the tool automatically. You can use quick actions such as **Enable all**, **Enable read-only**, **Disable all**, **Auto-approve enabled**, and **Auto-approve read-only** to configure several tools at once. Use auto-approval carefully. Auto-approving enabled tools lets Assistant run them without prompting you, including tools that may write, modify, or delete data in the connected service. When you want to keep reviewing a tool call before it runs, set that tool to **Always ask**. You can enable or disable a server, edit its settings or tool filters, or remove it permanently. The server’s scope can’t be changed after creation. Changing the URL or OAuth client settings of a shared server can require connected users to sign in again. Each user can disconnect their own OAuth account without removing the shared server or disconnecting anyone else. When Assistant proposes to use an MCP tool during a conversation, the configured approval policy determines whether the tool runs automatically or asks you to approve or reject the action first. Change review can use the tools of **Everybody** servers when it reviews a pull request from the enrolled repository. It never uses **Just me** servers or reviews a pull request from a fork with MCP tools. Nobody approves tool calls during a review, so a tool that would ask for approval doesn’t run. ## Configure an OAuth client Use the advanced settings when an MCP server needs specific OAuth scopes or an OAuth client registered in advance. The server owner configures these settings once; each user still authorizes their own account. 1. In the server’s **Settings** tab, expand **Advanced OAuth settings** and select **Customize OAuth settings**. 2. Choose **Dynamic registration** if the server supports it, or **Pre-registered client** if you registered a client with the server’s OAuth provider. 3. For a pre-registered client, copy the displayed **Redirect URL** and register that exact callback URL with the provider. Enter the **Client ID** and, if the provider requires it, the **Client secret**. Public clients can leave the secret empty. 4. If the provider requires specific scopes, enter them in **Scopes**, separated by spaces. Leave the field empty to use the server defaults. 5. Save the server settings, then connect your account when prompted. OAuth settings control client registration when the server requests OAuth. You can also configure HTTP headers for requests to the MCP server. A personal OAuth bearer token replaces a configured `Authorization` header for that user’s connection; other configured headers remain in use. ## Connect or disconnect your account Use the server card in **Settings > Integrations > MCP servers** to manage your own OAuth connection. - Click **Connect** to sign in or reauthorize if your connection has expired. A new server can show **Connect my account** in its **Tools** tab. - Click **Disconnect** to remove your connection. This doesn’t delete the server or affect other users’ connections. - Click **Test connection** to check your access and refresh the server’s tool list. If authentication is incomplete, connect your account and try again. You can disconnect your account from an **Everybody** server even if you can’t edit its settings. When a server is disabled, its tools aren’t available for conversations until an editor enables it again. ## GitHub App authentication For **Everybody** scope GitHub servers, you can authenticate using a GitHub App installed on your organization. This is the recommended approach for org-wide GitHub access because: - Tokens aren’t tied to any individual user, so access doesn’t break when someone leaves the organization. - Tokens are short-lived (approximately one hour) and refreshed automatically. - Permissions are scoped to whatever the organization admin granted when installing the app. - You can limit which repositories the Assistant can access by installing the app on specific repositories rather than the entire organization. GitHub App authentication works with both `https://api.githubcopilot.com/mcp` (standard GitHub) and `https://.ghe.com/mcp` (GitHub Enterprise) MCP server URLs. ### Create and install a GitHub App 1. In your GitHub organization, go to **Settings > Developer settings > GitHub Apps** and click **New GitHub App**. 2. Give the app a name (for example, “Grafana Assistant”) and set the required permissions. At minimum, grant read access to the repositories and resources you want the assistant to access. 3. Generate a private key: on the app’s settings page, scroll to **Private keys** and click **Generate a private key**. This downloads a `.pem` file — store it securely. 4. Install the app on your organization: go to the app’s settings page and click **Install App**, then choose your organization. You can grant access to **All repositories** or select **Only select repositories** to limit which repositories the Assistant can interact with. ### Find the required credentials You need three values to configure the integration: Expand table | Credential | Where to find it | |---------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **App ID** | On the GitHub App’s settings page (**Settings > Developer settings > GitHub Apps > Your App**), the App ID is displayed near the top of the **General** section. | | **Installation ID** | After installing the app on your organization, go to **Settings > Developer settings > GitHub Apps > Your App > Install App**. Click the gear icon next to your organization’s installation. The installation ID is the number at the end of the URL, for example, `https://github.com/organizations/YOUR_ORG/settings/installations/12345678` — the installation ID is `12345678`. | | **Private key** | The `.pem` file you downloaded when generating the private key. If you’ve lost it, you can generate a new one from the app’s settings page. | ### Configure the GitHub App integration 1. In the MCP server configuration, add the GitHub server and set the scope to **Everybody**. 2. Under **Authentication method**, select **GitHub App**. 3. Enter the **App ID** and **Installation ID**. 4. Click **Upload .pem file** and select the private key file you downloaded. 5. Click **Save** to validate the connection. The assistant mints short-lived installation tokens using these credentials. The private key is encrypted at rest and never exposed through the API. ## Troubleshoot MCP servers Troubleshoot and resolve common MCP servers issues. ### Verify authentication Authentication errors (401/403) typically indicate problems with tokens or OAuth flows. Verify that your auth header matches the server’s requirements, check that tokens haven’t expired, and ensure popups aren’t blocked for OAuth flows. For an **Everybody** server, check whether it uses shared headers, GitHub App authentication, or each user’s OAuth connection. If it uses personal OAuth, connect or reauthorize your own account. For OAuth integrations, the Assistant now provides enhanced diagnostics during the connection process. If the OAuth flow fails, check the error message for specific details about the failure stage (initialization, callback, or token exchange). ### Check server diagnostics When connection issues occur, use the built-in diagnostics to identify the root cause. The server configuration page displays detailed status information, including: - **Connection status**: Whether the server is reachable. - **Authentication details**: Initialization, callback, and token exchange information. - **Error details**: Specific error messages returned by the server or network stack. If Assistant can’t reach the MCP server, confirm the endpoint URL is correct and accessible from your network. Check that firewalls and gateways allow outbound connections to the server’s domain. ### Validate tool discovery If validation finds zero tools or schema discovery fails, verify the URL is correct and your authentication token has permissions to list tools. Confirm the endpoint implements the MCP protocol correctly. ### Review permissions For permission errors, refer to [Manage Assistant access with RBAC](/docs/grafana-cloud/platform/grafana-assistant/privacy-and-security/rbac) for required roles. For GitHub, install the [GitHub App](https://github.com/apps/grafana-assistant/installations/select_target) to access private repositories in your organization. ### Optimize performance Slow responses or rate limiting can be improved by filtering down to essential tools. The external provider enforces rate limits per authentication token. Consider narrowing your tool set to reduce API calls. Assistant allows an MCP tool call to run for up to 5 minutes. If a tool regularly reaches this limit, configure the server or tool to return a narrower result, split long-running actions into smaller tool calls, or disable tools that aren’t needed. Assistant truncates very large MCP tool responses. If a result is incomplete, retry with more specific filters, smaller page sizes, or a smaller set of fields. ### Resolve data access If search results are empty or tools fail to run, verify your API token has access to the resources you’re searching and that your token has permissions to run the specific tool. ## Next steps - [Navigate Grafana resources](/docs/grafana-cloud/platform/grafana-assistant/guides/navigation) - [Assistant Investigations](/docs/grafana-cloud/platform/grafana-assistant/platform/investigation)