Tools

This page lists the tools provided by the Perses MCP Server. The tools are grouped by resource: use the setting resources to only register some of them.

Whatever the tools registered, they can only do what the identity configured in the MCP server is allowed to do in Perses (see Permissions).

Projects#

Resource: project

ToolDescriptionRequired parametersOptional parameters
perses_list_projectsList all projects--
perses_get_project_by_nameGet a project by namename-
perses_create_projectCreate a new projectprojectdisplayName, description
perses_update_projectUpdate an existing projectnamedisplayName, description
perses_delete_projectDelete a projectname-

Dashboards#

Resource: dashboard

ToolDescriptionRequired parameters
perses_list_dashboardsList all dashboards of a projectproject
perses_get_dashboard_by_nameGet an outline by default; use summary: false for complete JSON before read-modify-write, or panels: [keys] for those full panels regardless of summary; unknown keys are listed in missing with the available keysproject, name
perses_create_dashboardCreate a dashboard in a projectproject, dashboard
perses_update_dashboardUpdate an existing dashboard of a projectproject, dashboard
perses_delete_dashboardDelete a dashboard from a projectproject, name
perses_set_dashboard_panelsAdd, replace or remove panels (with their layout items); new panels are appended to a panel groupproject, name; at least one entry in panels or remove
perses_set_dashboard_variablesAdd, replace or remove variables by nameproject, name; at least one entry in variables or remove
perses_set_dashboard_layoutDefine, replace or remove a panel groupproject, name, title

The parameter dashboard is a dashboard in the Perses format. Create and update take the dashboard as a JSON object; the Perses server validates it when saving it, and a validation failure is a tool error with the error of the Perses client, unchanged. Create fails if a dashboard with the same name exists; use perses_update_dashboard to change it. Writes return a compact summary; set include_dashboard: true to include the saved dashboard, or with dry_run: true (validate without saving) the dashboard that would be saved.

The incremental tools fetch the current dashboard, apply the requested changes and save it; Perses validates it when saving, and dry_run: true validates it without saving. In perses_set_dashboard_panels and perses_set_dashboard_variables, remove is applied before additions in the same write and must not name a key that is also being set. Invalid edits do not persist any changes. The edits made through one MCP server, including perses_update_dashboard, are serialized, so parallel tool calls do not lose each other's changes. expected_version checks the version before editing to detect intervening changes by other writers; it is not an atomic server-side lock, so a concurrent write after the check can still race. Decoding errors name the element they come from (panels."<key>": or variables[<index>]: ), followed by the message of the Perses model.

Grid layouts are edited as panel groups, like the Perses Go SDK (AddPanelGroup) and CUE DaC utils build them. Every panel of a group has the same size, width = 24 / panels_per_line (rounded down) and panel_height rows of 30px (at most 48, already taller than most screens), and the panels are laid out in order: panel i is at x = width * (i % panels_per_line), y = panel_height * (i / panels_per_line). For example, 4 panels with panels_per_line: 3 and panel_height: 6 are placed at (0,0), (8,0), (16,0) and (0,6).

  • perses_set_dashboard_layout defines or replaces the Grid group with the given title (an exact match, else ignoring case; several groups matching the same way are an error) from an ordered list of existing panels. A replaced group keeps its title. panels_per_line, panel_height and collapsed default to those of the replaced group, else 2 panels per line, height 8, not collapsible. Listed panels move out of other Grid groups, and those laid out with the formula above are laid out again. Panels left out are reported as no longer displayed, and listed panels that a tab also displays are reported too. remove: true deletes the group and keeps its panels, reported as no longer displayed; it takes no other option.
  • perses_set_dashboard_panels keeps the layout item of a replaced panel. New panels are appended, in key order, to the Grid group titled group (the last group by default, created if missing; without group and without any Grid group, a group titled Panel Group is created), with the size of its first panel. When the items of the group are where the formula above puts them, the group is laid out again with its panels per line (24 / width) and height. Otherwise the group was arranged by hand: its items keep their positions and the new panels fill rows below its lowest item. Removed panels lose their layout items, and the groups that were laid out with the formula are laid out again to close the gaps; groups arranged by hand keep their positions.

Tabs layouts are left untouched. Custom positions need perses_update_dashboard.

perses_update_dashboard reads the dashboard first only for expected_version or dry_run, so a plain update needs only the update permission.

perses_validate_dashboard checks the JSON against installed plugin CUE schemas without saving it. perses_get_plugin_schema provides plugin field definitions.

Ephemeral dashboards#

Resource: ephemeraldashboard

Ephemeral dashboards are temporary dashboards with a time-to-live (TTL): Perses deletes them automatically once expired. They are handy to let the LLM build a dashboard to answer a question, without cluttering the project.

ToolDescriptionRequired parameters
perses_list_ephemeral_dashboardsList all ephemeral dashboards of a projectproject
perses_get_ephemeral_dashboard_by_nameGet an ephemeral dashboard by nameproject, name
perses_create_ephemeral_dashboardCreate an ephemeral dashboard in a projectproject, dashboard
perses_update_ephemeral_dashboardUpdate an existing ephemeral dashboard of a projectproject, dashboard
perses_delete_ephemeral_dashboardDelete an ephemeral dashboard from a projectproject, name

The parameter dashboard is an ephemeral dashboard in the Perses format.

To check an ephemeral dashboard without saving it, pass perses_validate_dashboard a copy with kind Dashboard and spec.ttl omitted (TTL is not validated). perses_get_plugin_schema provides plugin field definitions.

Datasources#

Resources: globaldatasource for the tools *_global_datasource*, datasource for the tools *_project_datasource*.

ToolDescriptionRequired parametersOptional parameters
perses_list_global_datasourcesList all global datasources--
perses_get_global_datasource_by_nameGet a global datasource by namename-
perses_query_global_datasourceSend an HTTP request to a global datasource through Persesdatasource_namemethod, path, query_params, body, headers
perses_create_global_datasourceCreate a new global datasourcename, type, urldisplay_name, proxy_type
perses_update_global_datasourceUpdate an existing global datasourcename, type, urldisplay_name, proxy_type
perses_delete_global_datasourceDelete a global datasourcename-
perses_list_project_datasourcesList all datasources of a projectproject-
perses_get_project_datasource_by_nameGet a project datasource by nameproject, name-
perses_query_project_datasourceSend an HTTP request to a project datasource through Persesproject, datasource_namemethod, path, query_params, body, headers
perses_create_project_datasourceCreate a new datasource in a projectproject, datasource-
perses_update_project_datasourceUpdate an existing datasource of a projectproject, datasource-
perses_delete_project_datasourceDelete a datasource from a projectproject, name-

The parameter datasource is a datasource in the Perses format.

Querying datasources#

The tools perses_query_global_datasource and perses_query_project_datasource forward an HTTP request to the backend of a datasource (Prometheus, Loki, Tempo...) through the Perses proxy. This means:

  • The credentials are injected by Perses. The secrets configured on the datasource in Perses are applied on the server side: they are never exposed to the LLM.
  • The allowed endpoints are enforced. Only the endpoints allowed by the allowedEndpoints of the datasource can be reached.

The parameters are:

  • method: the HTTP method, GET (default) or POST.
  • path: the path of the endpoint, relative to the datasource. For example /api/v1/query_range for Prometheus, or /loki/api/v1/query_range for Loki.
  • query_params: the query string parameters, as an object of key/value strings.
  • body: the raw body of the request (JSON or application/x-www-form-urlencoded). The Content-Type is application/json by default when a body is provided.
  • headers: additional HTTP headers. The header Authorization is always ignored: the authentication to the datasource is configured in Perses.

On success (HTTP 2xx), the tool returns the response body of the datasource unchanged, like the other tools return the answer of Perses: for example the JSON document {"status":"success","data":{...}} of the Prometheus API. The response headers are not returned. On an HTTP error status, the tool returns an error (isError: true) that contains the HTTP status and the response body.

The response body is truncated to 1 MiB, to avoid exceeding the context of the LLM. When the body is truncated, the marker [response truncated: exceeded 1 MiB limit] is appended on a new line, so that the truncation is visible.

Example of an instant query on a global Prometheus datasource:

{
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query",
  "query_params": {
    "query": "up",
    "time": "2024-01-01T00:00:00Z"
  }
}

Example of a range query on a Prometheus datasource of a project:

{
  "project": "my-project",
  "datasource_name": "my-prometheus",
  "method": "POST",
  "path": "/api/v1/query_range",
  "query_params": {
    "query": "rate(http_requests_total[5m])",
    "start": "2024-01-01T00:00:00Z",
    "end": "2024-01-01T01:00:00Z",
    "step": "60"
  }
}

Prometheus#

Resource: prometheus

These read-only tools discover and query the metrics of the Prometheus datasources of Perses. They call the Prometheus HTTP API through the Perses proxy, like perses_query_*_datasource (credentials injected by Perses, allowedEndpoints enforced), but return compact JSON instead of the raw response: a range query over 6 hours returning 61 series is about 3 KB with perses_query_prometheus (top 20 series, statistics) and 240 KB with perses_query_global_datasource (raw points).

ToolDescriptionRequired parametersOptional parameters
perses_list_prometheus_metric_namesList metric names-datasource, match, search, time_range, limit, include_metadata
perses_list_prometheus_label_namesList label names-datasource, match, time_range, limit
perses_list_prometheus_label_valuesList the values of a labellabeldatasource, match, search, time_range, limit
perses_get_prometheus_metric_metadataGet the type, help and unit of 1 to 20 metricsmetricsdatasource
perses_query_prometheusRun a PromQL query and get a compact resultquerydatasource, type, time, time_range, step, limit, time_zone

The parameters are:

  • datasource: {name} for a global datasource, {name, project} for a project datasource. It is optional: see Default datasource.
  • match: a series selector, or a list of series selectors OR-ed together, e.g. "{job=\"prometheus\"}".
  • search: a case-insensitive substring filter, applied by the MCP server to the list returned by Prometheus. It doesn't make Prometheus return less: to narrow a large list, use match, e.g. {__name__=~".*memory.*"}.
  • time_range: {past_duration} (e.g. "6h", "7d"), or {start, end} in RFC 3339 (end defaults to now). The past hour by default. Prometheus applies it approximately (by storage block): the lists may include series without samples in it, e.g. series that stopped a few hours ago.
  • limit: the maximum number of returned items. Defaults: 200 metric names (50 with include_metadata, also its max), 200 label names, 100 label values (max 1000), 20 series (max 100).

The list tools return {datasource, total, returned, truncated, ...}. A list over 1 MiB is an error that asks to narrow it with match or time_range. With include_metadata: true, each metric name comes with its type and help, shortened to 80 characters. The metadata of all the metrics is fetched in one request; when it is over 1 MiB, the metadata of the returned metrics is looked up one by one instead. When it is unavailable, the metrics are returned without it, with a warning.

perses_get_prometheus_metric_metadata looks up each metric under its own name, then under the name of its family when the family has series with this suffix, as Prometheus matches them: _total of counters, _bucket, _count and _sum of histograms, _bucket, _count, _sum, _gcount and _gsum of gauge histograms, _count and _sum of summaries, _info of info metrics (e.g. http_requests_total of the counter http_requests). A _created series isn't matched, as it holds a timestamp, and neither is x_total_total with the family x_total.

perses_query_prometheus runs an instant query (type: "instant", default) at time (default now), or a range query (type: "range") over time_range with step (default about 500 points, at least the scrape interval of the datasource; see Datasource settings). It returns:

  • for an instant query, the value of each series, highest first: {resultType: "vector", time, seriesCount, returned, commonLabels, series: [{labels, value}]};
  • for a range query, never the raw points but the statistics of each series, highest max first: {resultType: "matrix", timeRange, step, seriesCount, returned, commonLabels, series: [{labels, min, max, avg, last, minAt, maxAt, nonFinite}]}. min, max and avg leave out the NaN and infinite samples, counted in nonFinite; last is the last sample. A series that only has NaN or infinite samples is not returned, with a warning. minAt and maxAt are in RFC 3339 with the offset of time_zone (default UTC).

The labels shared by all returned series are returned once in commonLabels. The values keep 4 significant digits, and all the digits of their integer part, so that timestamps and large counters are not rounded (e.g. 12.35, 123457, 1767355200); NaN and infinities are returned as strings. Native histograms are not summarized: the tool returns an error that asks to use histogram_quantile(), histogram_count() or histogram_sum(), without _bucket or le, e.g. histogram_quantile(0.99, sum(rate(x[5m]))). The warnings and infos of Prometheus are passed through. The errors of Prometheus are returned unchanged as tool errors, e.g. bad_data: invalid parameter "query": 1:9: parse error: ...; the other HTTP errors, e.g. of Perses, with their status and message. A response over 1 MiB is an error that asks to aggregate the query. time applies to instant queries only, time_range and step to range queries only: the other combinations are errors.

Use perses_query_*_datasource for the other endpoints of Prometheus and for the other kinds of datasources.

Default datasource#

The parameter datasource of the Prometheus tools is resolved as follows:

  • {name}: the global datasource name; {name, project}: the datasource name of the project. It must be a PrometheusDatasource.
  • {project}: the Prometheus datasource of the project marked as default (spec.default: true), else the global one.
  • omitted: the global Prometheus datasource marked as default.

When no Prometheus datasource is marked as default but there is exactly one that the Perses proxy can query, it is used. Otherwise the tool returns an error that lists the available Prometheus datasources. The resolved datasources are cached for 30 seconds.

The tools query the datasources through the Perses proxy: a datasource with a directUrl, which only the browser can reach, is an error, also when it is the default one.

Datasource settings#

Like the Perses UI, the tools apply two settings of the Prometheus datasource, which the Perses proxy doesn't:

  • queryParams are added to every request, unless the request sets the same parameter, e.g. dedup or partial_response for Thanos. A value with a dashboard variable ($) can't be resolved: it is sent as is, with a warning.
  • scrapeInterval (default 1m) is the minimum default step of range queries. An explicit step isn't raised to the scrape interval, but like the default one it is raised if needed to stay under the Prometheus limit of 11000 points per series. Before, the minimum default step was 15s: range statistics are now computed over fewer points unless step is set.

Variables#

Resources: globalvariable for the tools *_global_variable*, variable for the tools *_project_variable*.

ToolDescriptionRequired parameters
perses_list_global_variablesList all global variables-
perses_get_global_variable_by_nameGet a global variable by namename
perses_create_global_variableCreate a new global variablename, value
perses_update_global_variableUpdate an existing global variablename, value
perses_delete_global_variableDelete a global variablename
perses_list_project_variablesList all variables of a projectproject
perses_get_project_variable_by_nameGet a project variable by nameproject, name
perses_create_project_variableCreate a variable in a projectproject, name
perses_update_project_variableUpdate an existing project variableproject, name, value
perses_delete_project_variableDelete a variable from a projectproject, name

Roles and role bindings#

Resources: globalrole, globalrolebinding, role and rolebinding.

See Authorization for the meaning of the roles, the role bindings, their actions, scopes and subjects.

ToolDescriptionRequired parameters
perses_list_global_rolesList all global roles-
perses_get_global_role_by_nameGet a global role by namename
perses_create_global_roleCreate a new global rolename, actions, scopes
perses_update_global_roleUpdate an existing global rolename, actions, scopes
perses_delete_global_roleDelete a global rolename
perses_list_global_role_bindingsList all global role bindings-
perses_get_global_role_binding_by_nameGet a global role binding by namename
perses_create_global_role_bindingCreate a new global role bindingname, role, subjects
perses_update_global_role_bindingUpdate an existing global role bindingname, role, subjects
perses_delete_global_role_bindingDelete a global role bindingname
perses_list_project_rolesList all roles of a projectproject
perses_get_project_role_by_nameGet a project role by nameproject, name
perses_create_project_roleCreate a new role in a projectproject, name, actions, scopes
perses_update_project_roleUpdate an existing project roleproject, name, actions, scopes
perses_delete_project_roleDelete a role from a projectproject, name
perses_list_project_role_bindingsList all role bindings of a projectproject
perses_get_project_role_binding_by_nameGet a project role binding by nameproject, name
perses_create_project_role_bindingCreate a new role binding in a projectproject, name, role, subjects
perses_update_project_role_bindingUpdate an existing project role bindingproject, name, role, subjects
perses_delete_project_role_bindingDelete a role binding from a projectproject, name

Plugins#

Resource: plugin

ToolDescriptionRequired parameters
perses_list_pluginsList all the plugins installed in Perses-

Schemas#

Resource: schema

These read-only tools return raw CUE source from Perses v0.55 or later.

ToolDescriptionRequired parameters
perses_list_plugin_schemasGet all installed plugin schemas-
perses_get_plugin_schemaGet the latest installed schema of one plugin kindkind

Prefer the single-plugin tool when working on one panel, query, variable, annotation or datasource.

Validation#

Resource: validate

These tools validate resources without creating or modifying anything, and stay available in read-only mode. They take resources as JSON objects and return {valid: true}, or {valid: false, error} when the resource is invalid: error is the message of the Perses model when the resource cannot be decoded, or the message of the Perses server when it rejects the resource (HTTP 400). When the resource could not be validated, e.g. because Perses is unreachable or returns a server error, the tool returns the error of the Perses client unchanged as a tool error.

ToolDescriptionRequired parameters
perses_validate_dashboardValidate a dashboarddashboard
perses_validate_variableValidate a project or global variablevariable

kind is required on a variable and tells whether it is a project or a global one: Variable or GlobalVariable (case-insensitive). Any other or missing kind returns {valid: false, error} without calling Perses.

Grafana dashboards migration#

Resource: migrate

ToolDescriptionRequired parametersOptional parameters
perses_migrate_dashboardConvert a Grafana dashboard into a Perses dashboardgrafanaDashboardinput
  • grafanaDashboard: the JSON of the Grafana dashboard, as a string.
  • input: the values of the __inputs placeholders of the Grafana dashboard, for example {"DS_PROMETHEUS": "my-datasource"}.

The tool uses the migration API of Perses. The migrated dashboard is returned to the LLM but not saved: use the tool perses_create_dashboard to save it.

When the LLM host supports elicitation, the MCP server asks the user how to handle the datasources of the panels:

  • keep the datasource references of the Grafana dashboard,
  • or replace them with the default datasource of Perses.

The LLM can't make this choice on behalf of the user. When the LLM host doesn't support elicitation, the datasource references of the Grafana dashboard are kept.