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.
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 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 three authentication methods:
- OAuth: The server implements the MCP OAuth specification including dynamic client registration. Assistant initiates the OAuth flow automatically when you save the server configuration.
- Authorization header: The server accepts a custom Authorization header (for example,
Bearer <TOKEN>or<API_KEY>). This is the most common method for authenticated MCP servers. - 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
- Project management: Linear, Asana, Notion
- Deployment and infrastructure: Netlify, Vercel, Polar Signals
For authentication requirements and API token setup, refer to the documentation for each service. To access private GitHub repositories in an organization, install the GitHub App.
Configure an MCP server
Add and configure any MCP server (pre-configured or custom):
- Open the Assistant Settings and click Integrations.
- Under MCP Servers:
- For pre-configured servers: Click Add for the preset you want to use.
- For custom servers: Click Add Custom Server.
- Enter a Name to identify the server.
- Optionally disable Enabled if you want to configure the server without activating it immediately.
- Choose a Scope:
- Just me: The server is visible only to you.
- Everybody: The server is visible to all users in your tenant.
- 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.
- Optionally enter an Authorization Header if the server requires authentication, for example,
Bearer <TOKEN>or<API_KEY>.- Leave empty for unauthenticated servers.
- For OAuth-enabled servers, the OAuth flow initiates automatically after you save.
- 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.
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 your Authorization header format matches the server’s requirements, check that tokens haven’t expired, and ensure popups aren’t blocked for OAuth flows.
Check connectivity
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 for required roles. For GitHub, install the GitHub App 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.
