--- 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/machine-learning/assistant/guides/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/machine-learning/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. MCP servers support these authentication methods: - **OAuth**: The server implements the MCP OAuth specification including dynamic client registration. OAuth is available for **Just me** servers. Assistant initiates the OAuth flow automatically when you save the server configuration. - **Auth header**: The server accepts a custom HTTP auth header. The header name and value depend on the server, for example, `Authorization: Bearer ` or `X-API-Key: `. **Everybody** servers require an auth header (unless using GitHub App authentication). Use a shared service account token instead of a user token. - **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 (Repositories, Issues, Pull Requests) - **Project management**: Linear, Asana, Notion - **Deployment**: Netlify, Vercel - **Observability**: Polar Signals, Honeycomb, New Relic, Embrace 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. GitHub provides three separate MCP servers for repositories, issues, and pull requests. 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. This scope requires an auth header or, for GitHub, 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. Enter an auth header if the server requires header-based authentication. - In the UI, use **Authorization Header** to provide the header required by the server. - The header doesn’t have to be named `Authorization`. - **Everybody** servers always require an auth header. - Use a shared service account or integration token for **Everybody** servers. - Leave empty only for unauthenticated servers or **Just me** servers that use OAuth. - For OAuth-enabled **Just me** servers, the OAuth flow initiates automatically after you save. 8. Click **Save** to validate connectivity and discover available tools. 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. You can enable or disable a server, edit the server name or tool filters, or remove the server permanently. You can’t change the URL or authentication method without removing and recreating the server. When Assistant proposes to use an MCP tool during a conversation, you review and approve the tool call before it runs. You can approve to proceed or reject to continue without that action. ## 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. ### 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. If the server scope is **Everybody**, confirm that you configured an auth header. Shared servers don’t use OAuth on behalf of each user. 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/machine-learning/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. ### 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/machine-learning/assistant/guides/navigation) - [Run investigations](/docs/grafana-cloud/machine-learning/assistant/guides/investigation)