Skip to content
Scalekit Docs
Talk to an Engineer Dashboard

Connect AI agents to the Grafana Cloud MCP server

Vendor MCP
Open markdown

The Grafana Cloud MCP connector routes your AI agent's tool calls to Grafana Cloud's own MCP server through Scalekit. Each user signs in to Grafana Cloud once, and Scalekit stores and refreshes their tokens, so your agent never handles credentials. It comes with 138 tools.

Tools
138
What they doRead · write · destructive
106 · 11 · 21106 read11 write21 destructive
Users sign in with
OAuth app
Your own Grafana Cloud MCP server app

Setup

  1. Install the SDK

    Terminal window
    npm install @scalekit-sdk/node dotenv

  2. Set your credentials

    Add your Scalekit credentials to your .env file. Find values in app.scalekit.com > Developers > API Credentials.

    .env
    SCALEKIT_ENVIRONMENT_URL=<your-environment-url>
    SCALEKIT_CLIENT_ID=<your-client-id>
    SCALEKIT_CLIENT_SECRET=<your-client-secret>

  3. Create the Grafana Cloud MCP connection

    In AgentKit > Connections, create a Grafana Cloud MCP connection and copy its redirect URI. The name you give it is the connection_name your code passes. See Configure connections.

  4. Register an OAuth app

    Grafana Cloud MCP server connections use your own OAuth app. Register one with Grafana Cloud MCP server and add the redirect URI you copied.

    Then enter the app's Client ID and Client Secret on the Grafana Cloud MCP connection.

  5. Authorize a user and make your first call

    quickstart.mts
    import { ScalekitClient } from '@scalekit-sdk/node'
    import 'dotenv/config'
    import { createInterface } from 'node:readline/promises'
    

    const scalekit = new ScalekitClient(
      process.env.SCALEKIT_ENVIRONMENT_URL,
      process.env.SCALEKIT_CLIENT_ID,
      process.env.SCALEKIT_CLIENT_SECRET,
    )
    const actions = scalekit.actions
    

    const connector = 'grafanacloudmcp'
    const identifier = 'user_123'
    

    // Generate an authorization link for the user
    const { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })
    console.log('Authorize Grafana Cloud MCP:', link)
    const rl = createInterface({ input: process.stdin, output: process.stdout })
    await rl.question('Press Enter after authorizing...')
    rl.close()
    

    // Make your first call
    const result = await actions.executeTool({
      connector,
      identifier,
      toolName: 'grafanacloudmcp_user_info',
      toolInput: {},
    })
    console.log(result)
    Terminal window
    npx tsx quickstart.mts

    Each user signs in once. See Authorize a user for the full flow and statuses.

Tools

Pass the exact name to execute_tool
Try in PlaygroundRequest a tool
  • grafanacloudmcp_agento11y_manage_agentsRead the agent catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): which agents send telemetry, what their system prompts and tools are, how their prompt versions evolved, and how each version scored.Read-only

    Manage Agent Observability agents

    Read the agent catalog of Grafana Agent Observability (the grafana-agento11y-app plugin): which agents send telemetry, what their system prompts and tools are, how their prompt versions evolved, and how each version scored. The catalog is derived from ingested telemetry, not from a registration step: an agent exists here once its generations have been seen. It answers "what is this agent", not "what did it do". Operations: - 'list': agents in this tenant, newest activity first. Each row carries the latest effective version, first and latest seen times, generation and version counts, tool count, a system prompt prefix, and token_estimate. Paginated via limit and cursor - 'get': one agent version in full: the complete system prompt, every tool with its JSON schema, and the models it ran on. Returns the latest version unless 'version' is set - 'list_versions': the version history of one agent, one row per effective version with its seen window, generation count, tool count, and token_estimate. Paginated - 'list_version_scores': evaluation score aggregates per version, with per-evaluator score_key, pass and fail counts, and mean_score. Use it to compare how versions scored Versions: an effective version is always 'sha256:<64 lowercase hex>', and only that form is accepted by 'get'; a declared version such as '1.4.2' is reported in the declared_version fields but cannot be looked up. The plugin derives the effective version from the first of these the telemetry carries: the version the SDK reported, a hash of the declared version, a hash of the system prompt. Adding, removing, or editing a tool never mints a new version. Editing the prompt mints one only for an agent that reports neither its own effective version nor a declared version, so an agent that declares '1.4.2' keeps one effective version across prompt edits. Response size: 'get' returns the whole system prompt plus every tool schema, which can be tens of thousands of tokens. Check token_estimate.total from 'list' or 'list_versions' before fetching, and prefer the system_prompt_prefix in those rows when a prefix is enough. Cross-referencing: an agent name from 'list' is the value of the agent = "<name>" filter in conversation search. Pagination: when a response carries next_cursor, call the same operation again with cursor set to it. For 'list', also repeat the same name_prefix, start_time, and end_time using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d re-resolves and is rejected. Permissions: every operation is a read and needs grafana-agento11y-app.data:read (Agento11y Editor or Admin). This tool performs no writes. When to use: - Discovering which agent names exist before filtering conversations or generations by agent - Reading the system prompt or tool inventory an agent ran with, or how they changed between versions - Checking whether a new prompt version scores worse than the previous one When NOT to use: - Reading individual conversations, generations, or their scores - Inspecting evaluators or the rules that schedule them

    Inputs

    operationstringrequired
    The operation to perform: 'list' for the agent catalog, 'get' for one agent version in full (system prompt, tools, models), 'list_versions' for the version history of one agent, 'list_version_scores' for evaluation score aggregates per versionone of listgetlist_versionslist_version_scores
    agent_namestring
    Agent name from 'list'. Required for 'get', 'list_versions', and 'list_version_scores'. An explicitly empty string selects the unnamed agent (telemetry with no agent name), which 'get' and 'list_versions' accept and 'list_version_scores' rejects.
    cursorstring
    Pagination cursor from a previous response's next_cursor, echoed back exactly (for 'list' and 'list_versions'). For 'list' also resend the same name_prefix, start_time, and end_time as the first call using absolute RFC3339 times; the cursor is bound to those filters and a relative value such as now-7d or 7d drifts between calls and is rejected.
    end_timestring
    End of the time range in RFC3339 or relative format (e.g. now). For 'list' it keeps agents last seen at or before this time and defaults to no upper bound. For 'list_version_scores' it ends the score window; passing it without start_time gives a 90-day window ending here.
    limitinteger
    Maximum number of results per page (default 50, capped at 200 by the API) (for 'list' and 'list_versions')
    name_prefixstring
    Agent name filter (for 'list'). Despite the parameter name, the API matches it case-insensitively anywhere in the name, so 'agent' also returns 'my-agent'.
    start_timestring
    Start of the time range in RFC3339 or relative format (e.g. now-7d). For 'list' it keeps agents last seen at or after this time and defaults to no lower bound. For 'list_version_scores' it starts the score window; omitting it does not mean no lower bound, because the API then either scopes to the agent's 50 most recent versions or falls back to a 90-day window.
    versionstring
    Effective version 'sha256:<64 lowercase hex>' from 'list' or 'list_versions', accepted only by 'get'. Omit it for the latest version. Declared versions such as '1.4.2' are not accepted here; they are reported in the declared_version fields.
  • grafanacloudmcp_agento11y_manage_conversationsList, search, and fetch LLM conversations from Grafana Agent Observability (the grafana-agento11y-app plugin).Read-only

    Manage Agent Observability conversations

    List, search, and fetch LLM conversations from Grafana Agent Observability (the grafana-agento11y-app plugin). Operations: - 'list': recent conversations (lightweight; id, title, generation count, timestamps), paginated via limit and cursor - 'search': search conversations by filter expression and time range; results include models, agents, error counts, rating and eval summaries, and trace IDs - 'get': one conversation by ID with all its generations, including full prompts and outputs (can be large) Filter syntax for 'search': key operator value, with the value in double quotes; multiple filters are separated by spaces and combined with AND. Filter keys (trace): model, provider, agent, agent.version, status, error.type, error.category, duration, tool.name, operation, namespace, cluster, service Filter keys (metadata): generation_count, eval.passed, eval.evaluator_id, eval.score_key, eval.score Operators: =, !=, >, <, >=, <=, =~ (regex) Example: status = "error" agent = "claude-code" Pagination: when a response has next_cursor, fetch the next page by calling the same operation again with cursor set to next_cursor. For 'search', also repeat the same filters, start_time, and end_time as the first call, using absolute RFC3339 times; relative ranges like now-24h shift between calls and the cursor will be rejected. When to use: - Debugging an AI application: find failing or low-rated conversations, then inspect their generations - Reviewing evaluation results and user ratings across conversations When NOT to use: - Fetching a single generation or its evaluation scores

    Inputs

    operationstringrequired
    The operation to perform: 'list' for recent conversations, 'search' to filter conversations by expression and time range, 'get' to fetch one conversation with all its generations by IDone of listsearchget
    conversation_idstring
    The conversation ID (required for 'get' operation)
    cursorstring
    Pagination cursor from a previous response (for 'list' and 'search' operations). To fetch the next page set this to next_cursor. For 'search' also resend the same filters and start_time/end_time from the first call and use absolute RFC3339 times; relative ranges like now-24h invalidate the cursor.
    end_timestring
    End of the search time range in RFC3339 or relative format (e.g. now). Defaults to now (for 'search' operation)
    filtersstring
    Filter expression (for 'search' operation). Format: key operator value with the value in double quotes, multiple filters separated by spaces. See the tool description for keys and operators.
    limitinteger
    Maximum number of results per page (default 50) (for 'list' and 'search' operations)
    start_timestring
    Start of the search time range in RFC3339 or relative format (e.g. now-6h). Defaults to now-24h (for 'search' operation)
  • grafanacloudmcp_agento11y_manage_generationsFetch a single LLM generation and its evaluation scores from Grafana Agent Observability (the grafana-agento11y-app plugin).Read-only

    Manage Agent Observability generations

    Fetch a single LLM generation and its evaluation scores from Grafana Agent Observability (the grafana-agento11y-app plugin). Operations: - 'get': full generation detail by ID, including prompt, output, model, and usage (can be large) - 'scores': evaluation scores for a generation (evaluator, score key, score type, value, passed, explanation) When to use: - Drilling into one generation of a conversation - Checking why an evaluation passed or failed for a specific generation When NOT to use: - Searching or listing conversations

    Inputs

    generation_idstringrequired
    The generation ID
    operationstringrequired
    The operation to perform: 'get' for the full generation detail, 'scores' for the evaluation scores of the generationone of getscores
    cursorstring
    Pagination cursor from a previous response (for 'scores' operation)
    limitinteger
    Maximum number of scores per page (default 50) (for 'scores' operation)
  • grafanacloudmcp_alerting_manage_routingManage Grafana alerting routing configuration, including notification policies, contact points and time intervals.Read-only

    Manage alerting routing

    Manage Grafana alerting routing configuration, including notification policies, contact points and time intervals. Notification policies define how alerts are grouped, routed, and which contact points receive them. Time intervals define active/mute periods for alert notifications. When to use: - Understanding how alerts are routed to contact points/receivers - Debugging why an alert went to a specific receiver - Checking grouping, timing, or mute interval settings Does not show alert rule configuration or state.

    Inputs

    operationstringrequired
    The operation to perform: 'get_notification_policies' to retrieve the notification policy tree, 'get_contact_points' to list all contact points, 'get_contact_point' to get a specific contact point by name, 'get_time_intervals' to list all time intervals, 'get_time_interval' to get a specific time interval by nameone of get_notification_policiesget_contact_pointsget_contact_pointget_time_intervalsget_time_interval
    contact_point_titlestring
    Title of the contact point to retrieve (required for get_contact_point operation)
    datasource_uidstring
    Optional: UID of an Alertmanager-compatible datasource to query for receivers. If omitted, returns Grafana-managed contact points. Only used with get_contact_points.
    limitinteger
    The maximum number of results to return. Default is 100. Only used with get_contact_points.
    namestring
    Filter contact points by name (exact match). Only used with get_contact_points.
    time_interval_namestring
    Name of the time interval to retrieve (required for get_time_interval operation)
  • grafanacloudmcp_alerting_rules_readList and inspect Grafana alert rules with filtering capabilities.Read-only

    Read alert rules

    List and inspect Grafana alert rules with filtering capabilities. When to use: - Understanding why an alert is or isn't firing - Auditing alert rule configuration (queries, conditions, labels, notification settings) - Finding alert rules by state, folder, group, or name - Comparing rule versions to see what changed Read-only: does not create, update, or delete rules, and does not show notification routing.

    Inputs

    operationstringrequired
    The operation to perform: 'list' to search/filter rules, 'get' to retrieve full rule details (state + configuration) by UID, or 'versions' to get the version history of a ruleone of listgetversions
    datasource_uidstring
    Optional: UID of a Prometheus or Loki datasource to query for datasource-managed alert rules. If omitted, returns Grafana-managed rules.
    folder_uidstring
    Filter by exact folder UID (for 'list' operation). Mutually exclusive with search_folder.
    label_selectorsarray
    Prometheus-style selectors to filter alert rules by labels. Each string is a selector e.g. '{severity="critical", team=~"backend.*"}'. All selectors must match (AND).
    limit_alertsinteger
    Limit alert instances per rule. For list: 0 omits alerts. For get: <=0 defaults to 200. Max 200.
    matchersarray
    Label matchers to filter alert instances. Each string is a Prometheus-style matcher e.g. 'severity="critical"', 'env!="dev"', 'team=~"backend.*"'. Requires Grafana 12.4+.
    rule_groupstring
    Filter by exact rule group name (for 'list' operation)
    rule_limitinteger
    Maximum number of rules to return (default 200, max 200). Requires Grafana 12.4+ (for 'list' operation)default 200
    rule_typestring
    Filter by rule type (for 'list' operation)one of alertingrecording
    rule_uidstring
    The UID of the alert rule (required for 'get' and 'versions' operations)
    search_folderstring
    Search folders by path using partial matching (for 'list' operation). Requires Grafana 12.4+. Mutually exclusive with folder_uid.
    search_rule_namestring
    Search alert rule names/titles using partial matching. Requires Grafana 12.4+ (for 'list' operation)
    statesarray
    Filter by alert state: firing, pending, normal, recovering, nodata, error (for 'list' operation)
  • grafanacloudmcp_alerting_silences_readList and inspect Grafana alerting silences.Read-only

    Read alerting silences

    List and inspect Grafana alerting silences. A silence temporarily suppresses notifications for alerts whose labels match a set of matchers. Operations: - 'list': list existing silences. Optionally filter by rule_uid (matches the __alert_rule_uid__ label) or by matchers. - 'get': retrieve a single silence by silence_id. When to use: - Inspecting which alerts are currently silenced and why Read-only: does not create, update, or delete silences, and does not show alert rules or notification routing.

    Inputs

    operationstringrequired
    The operation to perform: 'list' to list silences, 'get' to retrieve a silence by idone of listget
    matchersarray
    Optional label matchers used to filter listed silences. Only used with 'list'.
    rule_uidstring
    Optional: filter listed silences to those scoped to this alert rule UID (matches the __alert_rule_uid__ label). Only used with 'list'.
    silence_idstring
    The silence id (required for 'get')
  • grafanacloudmcp_analyze_loki_labelsAudits a Loki label strategy and optionally diagnoses query performance.Read-only

    Analyze Loki label strategy

    Audits a Loki label strategy and optionally diagnoses query performance. Returns per-label verdicts, missing base labels, normalisation issues, and a recommended set. Pass datasourceUid for live cardinality or labels for static scoring; both may be combined.

    Inputs

    datasourceUidstring
    Datasource UID (live mode).
    endRfc3339string
    No description.
    expectedBaseLabelsarray
    No description.
    labelsarray
    Caller-supplied labels (static mode).
    maxLabelsinteger
    No description.
    perfMetricsobject
    Runtime metrics; presence triggers perf diagnosis.
    selectorstring
    Optional LogQL selector for stats / perf diagnosis.
    startRfc3339string
    No description.
  • grafanacloudmcp_app_observability_handlerInspect Application Observability services on this Grafana stack.Read-only

    Application Observability services

    Inspect Application Observability services on this Grafana stack. Commands: list finds services across Knowledge Graph scopes; get reports one service's RED metrics and topology; operations lists one service's native operations; dependencies reports its upstream callers or downstream services; quality reports instrumentation checks; runtime reports JVM or Node.js runtime metrics. Service inventory, identity, topology, quality, and runtime metadata require an active Knowledge Graph and Application Observability integration. Native operation metrics come from the configured Prometheus datasource and do not require Knowledge Graph. The optional namespace for native operations is a Prometheus job prefix, which may differ from a Knowledge Graph namespace. Results include links into the app.

    Inputs

    commandstringrequired
    list (every service) | get (RED KPIs for one service) | operations (RED KPIs per operation under one service) | dependencies (services upstream/downstream of one service) | quality (Knowledge Graph instrumentation-quality report for one service) | runtime (JVM/Node.js runtime metrics for one service)one of listgetoperationsdependenciesqualityruntime
    datasourceUidstring
    Pin the Prometheus datasource holding the App O11y metrics, when the tool reports several candidates
    directionstring
    For dependencies: upstream (callers of the service) or downstream (services it calls). Defaults to downstream.one of upstreamdownstream
    envstring
    Knowledge Graph environment scope for list, get, dependencies, quality, or runtime. For runtime it selects service metadata but does not filter native metrics.
    limitinteger
    For list, operations, and dependencies: cap rows after sorting, up to 50.
    namespacestring
    For list, get, dependencies, quality, and runtime: Knowledge Graph Service namespace scope, which need not equal the Kubernetes namespace, OTel service.namespace, or native job prefix. For operations: prefix of the native Prometheus job label (<namespace>/<service>).
    servicestring
    Service name (required for get, operations, dependencies, quality, runtime; from the list command)
    sitestring
    Knowledge Graph site scope for list, get, dependencies, quality, or runtime. For runtime it selects service metadata but does not filter native metrics.
    sortBystring
    For list, operations, and dependencies: sort rows by request rate, error ratio, p95 latency, or name. Unset preserves the default order.one of rateerrorsp95name
    sortDirectionstring
    Sort direction for sortBy. Defaults to desc for RED metrics and asc for name.one of ascdesc
All 30 in Monitoring