Merge Unified's Grafana integration Merge Agent Handler's Grafana MCP server

Connect your AI Agents to Grafana in minutes

Merge lets you securely connect your agents to Grafana and thousands of tools instantly

Start building for free

Read docs

Grafana

Learn more about Merge Agent Handler

Available tools

list_alert_rules

List all Grafana alert rules. Returns rule UIDs, titles, conditions, and folder assignments.

get_alert_rule

Get a Grafana alert rule by UID. Returns the full rule configuration. Use listalertrules to find valid UIDs.

create_alert_rule

Create a Grafana alert rule. Requires title, condition, data queries, folderuid, and rulegroup. Use listdatasources for data source UIDs and listfolders for folder UIDs.

update_alert_rule

Update a Grafana alert rule by UID. Requires all fields (title, condition, data, folderuid, rulegroup). Use getalertrule to fetch current values.

delete_alert_rule

Delete a Grafana alert rule by UID. This action is permanent. Use listalertrules to find valid UIDs.

list_contact_points

List all Grafana alerting contact points. Returns names, types (email, slack, webhook, etc.), and UIDs.

create_contact_point

Create a Grafana alerting contact point. Types: 'email', 'slack', 'webhook', 'pagerduty', 'teams'. Settings vary by type.

update_contact_point

Update a Grafana alerting contact point by UID. Use listcontactpoints to find valid UIDs.

delete_contact_point

Delete a Grafana alerting contact point by UID. This action is permanent. Use listcontactpoints to find valid UIDs.

list_alert_instances

List Grafana alert instances that are currently firing, silenced, or inhibited, with their labels, annotations, and start times. This is live alert state; narrow it with filter, receiver, or limit. Use listalertrules for rule definitions and listalertrule_states for per-rule state and health.

list_alert_rule_states

List Grafana alert rules with their current evaluation state and health, grouped by rule group. Filter by state ('firing', 'pending', 'normal'), health ('ok', 'error', 'nodata'), folderuid, or dashboarduid. Use listalertrules for full rule definitions. Page with groupnexttoken.

list_alert_history

Get state-change history for Grafana alert rules over a time range: when a rule moved to firing, normal, or error, and why. Use listalertrules or listalertrule_states to find rule UIDs. Times are Unix timestamps in seconds. Returns a data frame: 'schema' names the columns, 'data' holds one value array per column.

list_annotations

List Grafana annotations filtered by time range, tags, or dashboard. Returns annotation text, tags, and timestamps. Time values are epoch milliseconds.

create_annotation

Create a Grafana annotation. Annotations mark events on dashboards. Provide text and optionally attach to a dashboard/panel with tags.

update_annotation

Update a Grafana annotation by ID. Supports partial updates (only changed fields needed). Use list_annotations to find valid IDs.

delete_annotation

Delete a Grafana annotation by ID. This action is permanent. Use list_annotations to find valid IDs.

search_dashboards

Search Grafana dashboards by query, tags, or folder. Returns paginated results. Use page from page_info for next page.

get_dashboard

Get a Grafana dashboard by UID. Returns the full dashboard model with panels, variables, and metadata. Use search_dashboards to find valid UIDs.

create_dashboard

Create a new Grafana dashboard. Provide a dashboard object with 'title' and 'id' set to null. Optionally specify a folderuid. Use listfolders to find valid folder UIDs.

update_dashboard

Update an existing Grafana dashboard. The dashboard object must include 'uid' and 'title'. Include 'version' for conflict detection. Use get_dashboard to fetch the current version.

delete_dashboard

Delete a Grafana dashboard by UID. This action is permanent. Use search_dashboards to find valid UIDs.

list_datasources

List all Grafana data sources. Returns names, types, UIDs, and connection details. No pagination (returns all).

get_datasource

Get a Grafana data source by UID. Returns full configuration details. Use list_datasources to find valid UIDs.

create_datasource

Create a new Grafana data source. Common types: 'prometheus', 'loki', 'elasticsearch', 'influxdb', 'graphite', 'mysql', 'postgres'. Requires name, type, and usually url.

update_datasource

Update an existing Grafana data source by numeric ID. Use list_datasources to find the ID. Requires name and type.

delete_datasource

Delete a Grafana data source by UID. This action is permanent. Use list_datasources to find valid UIDs.

list_folders

List all Grafana folders. Folders organize dashboards. Returns folder UIDs, titles, and URLs.

get_folder

Get a Grafana folder by UID. Returns folder details including version. Use list_folders to find valid UIDs.

create_folder

Create a new Grafana folder for organizing dashboards. Optionally specify a custom UID.

update_folder

Update a Grafana folder's title. Include version for conflict detection. Use get_folder to find the current version.

delete_folder

Delete a Grafana folder and all its dashboards. This action is permanent. Use list_folders to find valid UIDs.

get_org

Get the current Grafana organization info. Returns organization name and ID.

list_org_users

List all users in the current Grafana organization. Returns user IDs, logins, emails, and roles (Admin, Editor, Viewer).

get_current_user

Get the currently authenticated Grafana user. Returns user ID, login, email, name, and admin status.

query_datasource

Query a Grafana data source for the actual metric, log, or SQL data behind dashboards. Call listdatasources first for the UID and type, then pass the field that type expects: 'expr' for Prometheus and Loki, 'rawSql' for SQL sources (read-only statements only). Use calldatasource_resource to discover metric names. Time range takes 'now-1h'/'now' or epoch ms.

call_datasource_resource

Discover what a Grafana data source can be queried for: metric names, label names, and label values. Prometheus: 'api/v1/label/name/values', 'api/v1/labels', 'api/v1/label/{label}/values'. Loki: 'loki/api/v1/labels'. Use listdatasources for the UID, then feed the names into querydatasource.

check_datasource_health

Check whether a Grafana data source is reachable and its stored credentials work. Returns status ('OK' or 'ERROR') and a message naming the failure. Run this first when querydatasource returns an error. Use listdatasources to find valid UIDs.

search_teams

Search Grafana teams by name or query. Returns paginated results with member counts. Use page from page_info for next page.

get_team

Get a Grafana team by ID. Returns team name, email, and member count. Use search_teams to find valid IDs.

create_team

Create a new Grafana team. Optionally set a team email. Use addteammember to add members after creation.

update_team

Update a Grafana team's name or email. Use search_teams to find valid IDs.

delete_team

Delete a Grafana team by ID. This action is permanent. Use search_teams to find valid IDs.

list_team_members

List members of a Grafana team. Returns user IDs, logins, emails, and names. Use search_teams to find valid team IDs.

add_team_member

Add a user to a Grafana team. Use listorgusers to find valid user IDs and search_teams for team IDs.

remove_team_member

Remove a user from a Grafana team. Use listteammembers to find valid user IDs for the team.

validate_credential

Validate Grafana credentials by fetching the current organization. Returns success status and message.

View all tools by creating a free account See more tools

How to set up Merge Agent Handler

In an mcp.json file, add the configuration below, and restart Cursor.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "url": "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
5      "headers": {
6        "Authorization": "Bearer yMt*****"
7      }
8    }
9  }
10}
11

Copy Code

Open your Claude Desktop configuration file and add the server configuration below. You'll also need to restart the application for the changes to take effect.

Make sure Claude is using the Node v20+.

Learn more in the official documentation ↗

1{
2  "mcpServers": {
3    "agent-handler": {
4      "command": "npx",
5      "args": [
6        "-y",
7        "mcp-remote@latest",
8        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
9        "--header",
10        "Authorization: Bearer ${AUTH_TOKEN}"
11      ],
12      "env": {
13        "AUTH_TOKEN": "yMt*****"
14      }
15    }
16  }
17}

Copy Code

Open your Windsurf MCP configuration file and add the server configuration below.
Click on the refresh button in the top right of the Manage MCP server page or in the top right of the chat box in the box icon.

Learn more in the official documentation ↗

1{
2    "mcpServers": {
3      "agent-handler": {
4        "command": "npx",
5        "args": [
6          "-y",
7          "mcp-remote@latest",
8          "https://ah-api.merge.dev/api/v1/tool-packs/<tool-pack-id>/registered-users/<registered-user-id>/mcp",
9          "--header",
10          "Authorization: Bearer ${AUTH_TOKEN}"
11        ],
12        "env": {
13          "AUTH_TOKEN": "<ah-production-access-key>"
14        }
15      }
16    }
17  }

Copy Code

In Command Palette (Cmd+Shift+P on macOS, Ctrl+Shift+P on Windows), run "MCP: Open User Configuration".

You can then add the configuration below and press "start" right under servers. Enter the auth token when prompted.

Learn more in the official documentation ↗

1{
2  "inputs": [
3    {
4      "type": "promptString",
5      "id": "agent-handler-auth",
6      "description": "Agent Handler AUTH_TOKEN", // "yMt*****" when prompt
7      "password": true
8    }
9  ],
10  "servers": {
11    "agent-handler": {
12      "type": "stdio",
13      "command": "npx",
14      "args": [
15        "-y",
16        "mcp-remote@latest",
17        "https://ah-api-develop.merge.dev/api/v1/tool-packs/{TOOL_PACK_ID}/registered-users/{REGISTERED_USER_ID}/mcp",
18        "--header",
19        "Authorization: Bearer ${input:agent-handler-auth}"
20      ]
21    }
22  }
23}

Copy Code

FAQs on using Merge's Grafana MCP server

What is a Grafana MCP?

A Grafana MCP is a server that exposes Grafana data and functionality to your agents through callable tools. Your agents can use those tools to query dashboards, manage alert rules, create annotations, search data sources, and more.

Grafana offers an official MCP server, but you can also use one from a third-party platform, like Merge Agent Handler.

How can I use the Grafana MCP server?

The use cases naturally depend on the agent you've built, but here are a few common ones:

Incident context retrieval: When a new incident is opened in PagerDuty or Jira, an agent can search Grafana for the relevant dashboard and pull recent annotations, giving on-call engineers immediate visual context without leaving their terminal

Automated post-incident annotation: After an incident is marked resolved in your incident management tool, an agent can create a Grafana annotation on the affected dashboard at the exact timestamp, so the event is permanently visible in the metrics timeline

Alert rule auditing: An agent can pull all active alert rules across a Grafana organization, flag ones that haven't fired in over 90 days or have misconfigured contact points, and post a weekly hygiene report to a Slack channel

On-call morning briefing: At the start of each shift, an agent can compile all firing alert rules, recent annotations, and data source health into a structured summary and deliver it to the on-call engineer via their preferred channel

What are popular tools for Grafana's MCP server?

Here are some of the most commonly used tools:

list_alert_rules: retrieves all alert rules configured in a Grafana organization, including state, severity, and assigned contact points. Useful for agents that audit alert coverage or check firing conditions before escalating an incident

search_dashboards: searches across all Grafana dashboards by keyword, folder, or tag. Call this when an agent needs to locate the right dashboard to pull context for an active alert or incident

get_dashboard: fetches the full configuration and panel metadata for a specific dashboard. Good for workflows that need to surface dashboard details or validate panel structure programmatically

create_annotation: adds a timestamped annotation to a dashboard, which agents can use to mark deployments, incidents, or configuration changes directly on the metrics timeline

create_alert_rule: creates a new alert rule with defined thresholds, evaluation intervals, and contact points. Use this when an agent needs to provision monitoring for a new service or environment automatically

list_datasources: returns all data sources connected to a Grafana instance, including type and connection status. Helpful when an agent needs to verify data source availability before running a query or building a dashboard

What makes Merge Agent Handler's Grafana MCP server better than alternative Grafana MCP servers?

Here's why teams choose Merge Agent Handler's Grafana MCP server over building their own or using another:

Enterprise-grade security and DLP: Merge Agent Handler includes built-in data loss prevention controls that let you block or redact sensitive fields before they reach an agent. For Grafana, this means you can prevent alert thresholds, on-call contact details, and infrastructure topology from being surfaced to an agent that only needs read access to dashboards

Managed authentication and credentials: Merge stores and refreshes Grafana credentials on your behalf. You never pass raw API keys into an agent or deal with key rotation breaking an on-call workflow at 2am

Real-time observability and audit trail: Every tool call made against Grafana is logged with timestamp, tool name, input parameters, and response metadata. You can see exactly which dashboards an agent searched, which alert rules it read, and which annotations it created, without adding any instrumentation

Tool Packs and controlled access: Tool Packs let you scope exactly which Grafana tools an agent can reach. A read-only incident context agent gets dashboard search and annotation listing. A provisioning agent gets alert rule creation. Neither gets access to the other's tools

How can I start using Merge Agent Handler's Grafana MCP server?

You can take the following steps:

1. Create or log into your Merge Agent Handler account.

2. Install the Merge CLI by running pipx install merge-api, then run merge configure to link the CLI to your Merge account and merge login to authenticate your session.

3. Register the Agent Handler MCP server with Claude Code by running claude mcp add --transport http agent-handler https://ah-api.merge.dev/mcp, then open Claude Code and run /mcp to confirm agent-handler appears with a connected status.

4. Select agent-handler from the MCP list. This opens a browser window where you select which integrations to authenticate. Choose Grafana and complete the auth flow. Merge stores and manages the credentials going forward.

5. Open a Claude Code session and start querying Grafana data directly. The first time you use a Grafana tool, a Magic Link may appear to complete connector authentication.

If you want to connect Merge Agent Handler's Grafana MCP with internal or customer-facing agentic products, you can follow the steps in our docs.