assistant-mcp

Grafana Cloud MCP Server Setup

The Grafana MCP server exposes Grafana Cloud capabilities as tools that AI agents can call via the Model Context Protocol. Once connected, agents can query metrics, search dashboards, manage alerts, investigate incidents, and interact with Fleet Management - all without leaving their coding environment.

Available transports:

• stdio - agent spawns the server as a subprocess (simplest, works everywhere)
• SSE - server runs independently, agent connects via HTTP

---

Step 1: Get your Grafana Cloud credentials

You need a Service Account token with appropriate scopes.

1. Go to your Grafana Cloud instance > Administration > Service Accounts
2. Create a service account with the Viewer role (add Editor if you need write operations)
3. Generate a token for that service account
4. Note your Grafana URL (e.g. https://myorg.grafana.net) and the token

For Grafana Cloud Prometheus/Loki/Tempo access you may also need:

• Metrics username and API key (from Cloud Portal > Stack > Details)
• Or a single Cloud Access Policy token with the required scopes

---

Step 2: Install the Grafana MCP server

# Via Go (recommended - always gets latest)
go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest

# Verify
mcp-grafana --version

Alternatively, download a pre-built binary from the releases page.

---

Step 3: Configure Claude Code

Add the server to Claude Code's MCP configuration. The config file is at:

• macOS/Linux: ~/.claude/settings.json or the project's .claude/settings.json

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}

Read-only mode (safer for exploration - disables all write tools):

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": ["--disable-write"],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}

Restart Claude Code after editing settings. Run /mcp in Claude Code to verify the server appears and its tools are listed.

---

Step 4: Configure Cursor

In Cursor: Settings > Features > MCP Servers (or edit ~/.cursor/mcp.json):

{
  "mcpServers": {
    "grafana": {
      "command": "mcp-grafana",
      "args": [],
      "env": {
        "GRAFANA_URL": "https://myorg.grafana.net",
        "GRAFANA_API_KEY": "glsa_xxxx"
      }
    }
  }
}

---

Step 5: Run as SSE server (for team sharing or VS Code)

Run the server as a long-lived SSE process instead of per-session stdio:

GRAFANA_URL=https://myorg.grafana.net \
GRAFANA_API_KEY=glsa_xxxx \
mcp-grafana --transport sse --port 3001

Then point agents at http://localhost:3001/sse.

VS Code MCP extension config (settings.json):

{
  "mcp.servers": {
    "grafana": {
      "type": "sse",
      "url": "http://localhost:3001/sse"
    }
  }
}

---

Step 6: Available tools and what they do

Once connected, the agent can call:

Query tools:

• query_prometheus - run PromQL queries against Grafana Cloud Metrics
• query_loki - run LogQL queries against Grafana Cloud Logs
• query_tempo - run TraceQL queries against Grafana Cloud Traces
• list_datasources - enumerate configured data sources

Dashboard tools:

• search_dashboards - find dashboards by name, tag, or folder
• get_dashboard - retrieve full dashboard JSON
• create_dashboard - create or update a dashboard (requires Editor role)

Alerting and incident tools:

• list_alert_rules - list firing and pending alerts
• get_alert_rule - get details of a specific alert rule
• list_incidents - list active incidents (requires IRM)

Fleet Management tools (if collector-app is installed):

• list_collectors - list Alloy collectors and their health status
• list_pipelines - list remote configuration pipelines
• get_pipeline - get pipeline YAML content

Annotation tools:

• list_annotations - search dashboard annotations by time range
• create_annotation - add an annotation to a dashboard

---

Step 7: Verify the connection

In Claude Code, ask the agent to use a Grafana tool:

What data sources are configured in my Grafana instance?

Or:

Show me dashboards tagged with "kubernetes" in my Grafana.

If the tool call fails:

• Check GRAFANA_URL has no trailing slash
• Confirm the API key has not expired
• Try mcp-grafana --debug to see raw request/response logs

---

Step 8: Use with the Grafana Skills

If you have the grafana-core skills installed, the agent already knows:

• PromQL query patterns (from grafana-core/promql)
• Dashboard structure (from grafana-core/dashboarding)
• Fleet Management concepts (from grafana-cloud/fleet-management)

Combined with the MCP tools, the agent can answer questions like:

• "What is the p95 latency of the payments service over the last hour?"
• "Create a dashboard showing CPU and memory usage for the production cluster"
• "Which collectors are unhealthy and what errors do they have?"
• "Show me all alert rules that fired in the last 24 hours"

---

Grafana Assistant A2A (Agent-to-Agent)

The Grafana Assistant supports the A2A protocol for agent-to-agent communication. External agents can discover available Grafana agents at:

GET https://<GRAFANA_ASSISTANT_HOST>/.well-known/agent.json

This returns an Agent Card describing the supervisor agent's capabilities. Use this for programmatic integration when building agents that need to delegate observability reasoning to the Grafana Assistant.

---

Security considerations

• Store API keys in environment variables or a secrets manager - never in committed files
• Use read-only mode (--disable-write) for shared or CI environments
• Scope service account permissions to the minimum required (Viewer is sufficient for queries)
• Rotate tokens periodically via Administration > Service Accounts

---

References

• Grafana MCP server (github.com/grafana/mcp-grafana)
• Model Context Protocol specification
• Grafana Cloud API documentation
• Grafana Assistant documentation