Connect Grafana to Codex

Search dashboards, query Prometheus and Loki datasources, and read alerts. Add Toolspoke to Codex once and it can use 11 Grafana actions. Your Grafana credential stays in Toolspoke, and you choose which actions Codex may call.

Set it up in Codex

Three steps, the first one once for every toolkit you will ever add.

  1. Add Toolspoke to Codex

    ~/.codex/config.toml

    [mcp_servers.toolspoke] url = "https://toolspoke.com/mcp"

    Codex signs in to Toolspoke on its own the first time it connects, so there is no key to paste.

  2. Install Grafana and connect it

    Add Grafana to a project in your Toolspoke workspace.

    Service account token. You provide it once, when you install the connector. Toolspoke encrypts it at rest and decrypts it only for the length of a single call, and the gateway attaches it to the outbound request itself, so it is never part of the arguments an agent sends.

    Service account token
    Grafana → Administration → Users and access → Service accounts → add a service account, then Add service account token. A Viewer role covers every read here; annotation writing needs Editor.
    Grafana URL
    Your Grafana Cloud stack URL or the base URL of your self-hosted Grafana. It has to be publicly reachable, a private-network address is refused.
  3. Choose what Codex may do

    All 11 actions start on. Switch off the one action that changes something in Grafana, and Codex gets a refusal if it tries.

What you can ask Codex for

A few of the Grafana actions that only read, so they are safe to try first.

  • Search dashboards and folders by title or tag
  • Fetch one dashboard by UID, including every panel and the datasource queries behind it
  • List the datasources configured in this Grafana with their UIDs and types
  • Run a LogQL query over a time window through Grafana's datasource proxy and return the matching log lines

What Codex can do in Grafana

10 actions read and one writes.

Reads

  • Search dashboards

    Search dashboards and folders by title or tag. This is the entry point for everything dashboard-shaped: it returns the UIDs that get_dashboard and the annotation actions need. Defaults to dashboards only; pass type dash-folder to list folders instead, or use list_folders.

  • Get dashboard

    Fetch one dashboard by UID, including every panel and the datasource queries behind it. Read this before writing your own PromQL: the panels record the queries a team already trusts for a service, and query_prometheus_range can re-run one directly. Call search_dashboards first for the UID. Panel trees are depth-limited to keep the response readable.

  • List datasources

    List the datasources configured in this Grafana with their UIDs and types. Call this first for every query action: query_prometheus, query_prometheus_range and query_loki all address a datasource by UID, and the type field is what tells you which of them applies (prometheus, loki, mimir, influxdb, …).

  • Query prometheus

    Run a PromQL query at a single instant through Grafana's datasource proxy and return the current value per series. Use this for "what is it right now", error rate, replica count, queue depth. Use query_prometheus_range when you need a shape over time. The datasource UID comes from list_datasources and must be of type prometheus or mimir.

  • Query prometheus range

    Run a PromQL query over a time window through Grafana's datasource proxy and return one series of points per label set. Use this to see whether something is climbing, and to line a metric up against a deploy. Keep step large enough that the window divides into a few hundred points or Prometheus refuses the query outright.

  • Query loki

    Run a LogQL query over a time window through Grafana's datasource proxy and return the matching log lines. Every LogQL query needs at least one stream selector in braces, e.g. {app="checkout"} |= "timeout". A metric-shaped LogQL query such as sum(rate({app="checkout"} |= "error" [5m])) returns series instead of lines. The datasource UID comes from list_datasources and must be of type loki.

  • List alert rules

    List the Grafana-managed alert rules that are configured, with their queries, evaluation intervals and labels. This says what could fire; list_active_alerts says what is firing now. Use it to find out why an alert exists and which datasource it watches.

  • List active alerts

    List the alerts currently held by Grafana's built-in Alertmanager, what is firing right now, with each alert's labels, annotations and when it started. Start here when asked "is anything on fire", then use list_alert_rules to understand a rule the answer names.

  • List folders

    List the dashboard folders the token can see, with their UIDs and titles. Use it to map a team name onto the folder UID that search_dashboards filters on.

  • List annotations

    List annotations, the timestamped markers drawn on dashboard graphs, including the ones Grafana writes itself when an alert changes state. Use it to find out what a team recorded as happening at the moment a metric moved. Filter by dashboard UID or by tag; times are epoch milliseconds.

Writes

  • Create annotation

    Record an annotation so it appears as a marker on dashboard graphs, a deploy, a config change, a manual intervention. Pass a dashboard UID and panel id to pin it to one panel, or neither to make it organization-wide. Give time and timeEnd for a region rather than an instant. Needs an Editor-role token.

Grafana in Codex: questions

Does Codex see my Grafana credential?

No. The credential is stored encrypted in Toolspoke, and the gateway adds it to each call. Codex only ever talks to Toolspoke, and the dashboard shows the last four characters of the credential and nothing more.

Can I stop Codex from changing things in Grafana?

Yes. Each of the 11 actions can be switched off for a project. Turn off the one that changes something and Codex can only read.

Will 11 actions crowd Codex's context?

No. Toolspoke shows Codex five bridge tools, plus a guide where a toolkit has one, and Codex searches for the Grafana action it needs when it needs it. Adding more toolkits does not add more tools to its list.

Does the same work in ChatGPT?

ChatGPT and Codex share one OpenAI account. In ChatGPT, add a custom MCP connector in its settings and paste the same address.

What does it cost?

Tool calls are free on every plan, and a Grafana call does not run in a sandbox, so it bills nothing.

Try Grafana in Codex

Free to start, and tool calls cost nothing on any plan.