AI and machine learning

Grafana Assistant

Manage MCP servers

Troubleshoot MCP servers

Grafana Cloud

Troubleshoot MCP servers

Resolve common issues when connecting, configuring, and using MCP servers with Assistant. This guide covers authentication, connectivity, tool discovery, permissions, performance, and data access problems.

What you’ll achieve

Use this guide to diagnose and fix common problems when working with MCP servers.

Fix authentication failures including OAuth popups, unauthorized errors, and invalid headers.
Resolve connectivity issues preventing Assistant from reaching MCP servers.
Address tool discovery problems and configuration errors.
Improve performance by reducing tool counts and managing rate limits.

Resolve authentication issues

Authentication problems prevent Assistant from accessing MCP server tools and typically appear as 401 or 403 errors.

OAuth popup blocked:

Allow popups in your browser to complete authentication. Check your browser’s popup blocker settings and add an exception for your Grafana domain.

Unauthorized (401/403) errors:

Verify the Authorization header format matches the server’s requirements, for example, Authorization: Bearer YOUR_TOKEN. Check that your API token hasn’t expired or been revoked and verify the token has read permissions for the resources you’re accessing.

Invalid auth header:

Verify the header key matches what the server expects (case-sensitive) and confirm the header value format is correct. Common formats include Bearer TOKEN, Basic BASE64, or just the token value.

OAuth errors:

Ensure the provider allows redirects back to Grafana and check the browser console for blocked popups or CORS errors. Some corporate firewalls block OAuth redirects to localhost or specific domains.

Resolve connectivity issues

Connectivity problems prevent Assistant from reaching MCP servers and typically appear as timeout or unreachable errors.

Server unreachable:

Confirm the endpoint URL is correct and accessible from your network. Test the URL in a browser or with curl from a machine in the same network as Grafana. Ensure the gateway allowlists the domain and no firewall rules block the connection.

Gateway blocked:

Ensure the endpoint domain is allowlisted by your gateway or firewall. Check network policies that might block outbound connections from your Grafana instance.

Connection timeout:

Increase timeout settings if the server is slow to respond. Check if the server is behind a VPN or requires special routing.

Resolve tool discovery issues

Tool discovery problems prevent Assistant from finding available MCP tools and typically appear during server configuration.

Validation found zero tools:

Check the URL is correct with no trailing slashes or additional paths. Verify your authentication token has permissions to list available tools.

Schema discovery failure:

Confirm the endpoint implements the MCP protocol correctly. The server must respond to tool discovery requests with valid JSON. Verify the endpoint is reachable from Grafana by testing the URL in a browser or with curl.

Stale or incorrect tools:

Some MCP servers cache tool definitions. Wait a few minutes and try refreshing the configuration. Remove and re-add the server if tools remain incorrect.

Resolve permission issues

Permission problems prevent you from managing MCP servers or accessing resources and require administrative action.

Permission denied: Refer to Manage Assistant access with RBAC - Understand available roles for the roles required to manage personal or tenant MCP servers. If you still can’t access MCP server management, contact your Grafana administrator.

Missing organization access (GitHub):

Install the GitHub App into your organization. Without installation, you can only access public repositories.

404 on private repos (GitHub):

Confirm the GitHub App is installed into the organization and verify the app has access to the repository. Grant access to the specific repositories you need in your GitHub App configuration.

Resolve performance issues

Performance problems cause slow responses or high costs and can be improved by reducing the number of active tools.

Slow or noisy responses:

Filter down to essential tools to reduce latency and improve relevance. Remove tools for features you don’t use and monitor which tools Assistant uses.

Rate limited:

Wait for the rate limit to reset or reduce request volume. The external provider enforces rate limits per authentication token. Consider narrowing your tool set to reduce the number of API calls.

Too many tools:

Filter to the fewest necessary tools to reduce latency and confusion. Start with one to five tools for optimal performance. More than 16 tools significantly impacts response time and accuracy.

Multiple servers conflict:

If you have multiple servers with similar tools, Assistant may choose unpredictably. Use clear naming and filter tools carefully to avoid overlap.

Resolve data access issues

Data access problems prevent Assistant from finding or retrieving expected information from external systems.

Empty search results:

Verify your API token has access to the team, project, workspace, or repository you’re searching. Check that resources exist matching your search criteria and try broadening search terms or removing filters.

Stale data:

Provider API responses may be cached. If you don’t see recent issues or PRs, wait a few minutes and try again.

Tool execution failures:

Review the tool’s input schema and ensure Assistant is sending correctly formatted parameters. Verify your authentication token has permissions to execute the specific tool.

Resolve scope and configuration issues

Scope and configuration problems affect who can use integrations and how they behave. Tenant-level MCP servers must use a custom auth header, not OAuth. For GitHub tenant-level servers, provide a service token through a header. Personal servers use OAuth when available (GitHub) or personal API tokens (Linear).