How do I use observability-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@observability-mcp show error logs from the last hour" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

observability-mcp

by ThainaJardim

Overview Schema Source Related Servers Discussions Admin

Python

observability-mcp

MCP (Model Context Protocol) servers that let AI assistants query your observability stack — Grafana/Loki for logs and Thanos/Prometheus for metrics — directly from Cursor, Claude Desktop, or any MCP-compatible client.

Packages

Package	Entry-point	What it does
`grafana_mcp`	`grafana-mcp`	Query Loki logs via Grafana datasource proxy
`thanos_mcp`	`thanos-mcp`	Query Prometheus/Thanos metrics (PromQL)
`observability_mcp`	`observability-mcp`	Combined server — all tools in one connection

Related MCP server: mcp-server-logs-sieve

Requirements

Python 3.10+
Access to a running Grafana instance (for grafana_mcp)
Access to a Thanos or Prometheus instance (for thanos_mcp)

Installation

From GitHub (recommended)

Install directly from the repo without cloning:

pip install "observability-mcp @ git+https://github.com/ThainaJardim/observability-mcp.git"

# With browser-cookie support for Grafana SSO:
pip install "observability-mcp[browser-cookie] @ git+https://github.com/ThainaJardim/observability-mcp.git"

After installation, the grafana-mcp, thanos-mcp, and observability-mcp commands are available.

From source (local clone)

git clone https://github.com/ThainaJardim/observability-mcp.git
cd observability-mcp

pip install .

# For automatic Grafana SSO login via browser cookies (macOS/Linux):
pip install ".[browser-cookie]"

Quick start

Grafana / Loki

export GRAFANA_URL=https://grafana.example.com
export LOKI_DATASOURCE_ID=1          # numeric datasource ID in Grafana
export OIDC_ISSUER=https://keycloak.example.com/auth/realms/myrealm

grafana-mcp

Thanos / Prometheus

export THANOS_URL=https://thanos.example.com
export OIDC_ISSUER=https://keycloak.example.com/auth/realms/myrealm

thanos-mcp

Combined (both in one server)

# Set all env vars from above, then:
observability-mcp

Authentication

Grafana MCP

Auth mode is auto-detected from environment variables (or forced with GRAFANA_AUTH_MODE):

Mode	How it works	Variables needed
`browser-cookie` (default)	Reads Keycloak SSO cookies from Chrome, follows the Grafana OAuth flow automatically, caches `grafana_session` locally	`OIDC_ISSUER`, `GRAFANA_URL`
`token`	Grafana service-account token	`GRAFANA_BEARER_TOKEN`
`cookie`	Static `grafana_session` cookie	`GRAFANA_SESSION_COOKIE`
`kubeconfig`	OIDC id-token from kubectl kubeconfig	`OIDC_ISSUER`

browser-cookie mode requires browser-cookie3 (pip install ".[browser-cookie]"). On first use it reads Chrome's cookie store — you may be prompted to allow macOS Keychain access. You must be logged into Grafana in Chrome at least once.

Thanos MCP

Auth mode is auto-detected (or forced with THANOS_AUTH_MODE):

Mode	How it works	Variables needed
`kubeconfig` (default)	OIDC id-token from kubectl kubeconfig, auto-refreshed	`OIDC_ISSUER`, `kubectl` on PATH
`token`	Static Bearer token	`THANOS_ACCESS_TOKEN`
`cookie`	oauth2-proxy session cookie	`THANOS_SESSION_COOKIE`

Cursor MCP configuration

Create or edit .cursor/mcp.json in your project:

{
  "mcpServers": {
    "grafana": {
      "command": "python",
      "args": ["-m", "grafana_mcp.server"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "LOKI_DATASOURCE_ID": "1",
        "OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    },
    "thanos": {
      "command": "python",
      "args": ["-m", "thanos_mcp.server"],
      "env": {
        "THANOS_URL": "https://thanos.example.com",
        "OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Tip: Use an absolute Python interpreter path (e.g. /usr/local/bin/python3) if Cursor cannot find python in its PATH.

Combined server (one entry)

{
  "mcpServers": {
    "observability": {
      "command": "python",
      "args": ["-m", "observability_mcp.server"],
      "env": {
        "GRAFANA_URL": "https://grafana.example.com",
        "LOKI_DATASOURCE_ID": "1",
        "THANOS_URL": "https://thanos.example.com",
        "OIDC_ISSUER": "https://keycloak.example.com/auth/realms/myrealm",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

Available MCP tools

Grafana/Loki tools (`grafana_mcp`)

Tool	Description
`query_loki_logs`	Run a LogQL range query and return matching log streams
`query_loki_instant`	Run a LogQL instant query
`list_loki_labels`	List all available Loki label names
`list_loki_label_values`	List values for a specific Loki label

Thanos/Prometheus tools (`thanos_mcp`)

Tool	Description
`query_metrics`	Run an instant PromQL query
`query_metrics_range`	Run a PromQL range query
`list_labels`	List all metric label names
`list_series`	List time-series matching a selector

Development

# Install in editable mode with dev extras
pip install -e ".[dev,browser-cookie]"

# Run tests
pytest

# Run a specific server locally
python -m grafana_mcp.server
python -m thanos_mcp.server
python -m observability_mcp.server

Environment variable reference

Variable	Default	Description
`GRAFANA_URL`	(required)	Grafana base URL
`LOKI_DATASOURCE_ID`	(required)	Numeric Loki datasource ID in Grafana
`GRAFANA_AUTH_MODE`	auto	Force Grafana auth mode
`GRAFANA_BEARER_TOKEN`	—	Grafana service-account token
`GRAFANA_SESSION_COOKIE`	—	grafana_session cookie value
`GRAFANA_SESSION_CACHE`	`~/.cache/grafana-mcp/session.json`	Path to session cache file
`THANOS_URL`	(required)	Thanos/Prometheus base URL
`THANOS_AUTH_MODE`	auto	Force Thanos auth mode
`THANOS_ACCESS_TOKEN`	—	Static Bearer token
`THANOS_SESSION_COOKIE`	—	oauth2-proxy cookie value
`OIDC_ISSUER`	—	OIDC issuer URL (Keycloak realm URL)
`REQUEST_TIMEOUT_SECONDS`	`30`	HTTP timeout for all requests
`LOG_LEVEL`	`INFO`	Logging level

License

MIT

Available Tools

8 tools

list_labelsA

List all metric label names available in Thanos.

Args: start: Optional start of the time range for label filtering. end: Optional end of the time range for label filtering.

Returns: JSON array of label name strings.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No
`start`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is responsible for all behavioral disclosure. It only states the return format (JSON array) and parameter roles, but lacks details on potential volume, side effects, read-only nature, or any rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: one line for purpose, a list of two parameters, and a return type. No superfluous information, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (2 optional parameters, no required, output schema exists), the description covers the essential functionality. It could mention that omitting both parameters returns all labels or clarify the time range semantics, but it is generally complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds meaning to both parameters with brief explanations ('Optional start of the time range for label filtering.') that go beyond the schema which only provides names and types. However, it does not specify expected formats (e.g., RFC3339) or behavior when omitted.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The first sentence 'List all metric label names available in Thanos' clearly states the verb (list), resource (metric label names), and scope (Thanos), distinguishing it from sibling tools like list_loki_labels which deal with Loki log labels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives (e.g., list_loki_labels, list_series). There is no mention of when not to use it or what the prerequisites are.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_loki_labelsA

List available Loki label names from the configured datasource.

Args: start: Optional start of the time range for filtering. end: Optional end of the time range for filtering.

Returns: JSON array of label name strings.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No
`start`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.6/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses the tool is read-only (listing labels) and that optional time range filtering is available. However, it does not mention any potential performance implications, authentication requirements, or other behavioral traits beyond the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise: a single sentence for purpose, followed by a brief Args and Returns section. No unnecessary information, and the key purpose is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (listing label names with optional time filters) and the presence of an output schema, the description covers the essential inputs, output format, and behavior. It lacks only minor details like pagination or rate limits, but is largely complete for a straightforward listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the start and end parameters as optional time range filters, but omits details like expected format (e.g., RFC3339 string, Unix timestamp) or how they affect the results. This provides basic meaning but not complete clarity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists available Loki label names from the configured datasource. This distinguishes it from the sibling tool list_loki_label_values, which lists values for a specific label, by specifying the resource (label names) and the action (list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives. There is no mention of prerequisites, typical scenarios, or cases where other tools like query_loki_logs or list_loki_label_values might be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_loki_label_valuesA

List available values for a given Loki label.

Args: label: Label name, e.g. "app" or "namespace". start: Optional start of the time range for filtering. end: Optional end of the time range for filtering.

Returns: JSON array of label value strings.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No
`label`	Yes
`start`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It explains parameters and return type but does not disclose potential behaviors like handling of missing labels, time range filtering details, or performance characteristics.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise with a clear structure: a one-sentence purpose followed by formatted parameter and return explanations. No unnecessary content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has an output schema (not shown), the description adequately covers parameters and return type. It misses potential edge cases or limitations, but overall is sufficient for a straightforward listing tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds significant value by explaining each parameter with examples and clarifying optional time range usage. This compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists available values for a given Loki label, using a specific verb and resource. It distinguishes from siblings like list_loki_labels which lists label names, not values.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for fetching values of a specific label but does not explicitly state when to use it versus alternatives like list_loki_labels or list_labels. No when-not or recommendation is given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_seriesA

List time-series matching a PromQL selector.

Args: match: One or more comma-separated series selectors, e.g. {job="prometheus"} or up,{job="api"}. Each comma-separated value is sent as a separate match[] parameter. start: Optional start timestamp for the look-up window. end: Optional end timestamp for the look-up window.

Returns: JSON array of label-set objects describing each matching series.

ParametersJSON Schema

Name	Required	Description	Default
`end`	No
`match`	Yes
`start`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.7/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must cover behavioral traits. It mentions read operation implicitly but does not state non-destructiveness, auth needs, or rate limits. Return format is covered but not behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with a clear one-liner followed by param details. No wasted words, but could be slightly more concise. Front-loaded effectively.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With output schema present, return format is covered. The description explains purpose and parameters adequately but lacks usage guidelines and behavioral transparency, leaving gaps for an agent to fully understand context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds detailed semantics for all parameters: match explanation with examples, start/end as optional timestamps, and the important detail that comma-separated values become separate match[] parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool lists time-series matching a PromQL selector, with a specific verb and resource. It distinguishes from siblings like list_labels which list labels.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing series but provides no explicit when-to-use vs alternatives like query_metrics or list_labels. No exclusions or guidance are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_loki_instantA

Run a Loki instant query through Grafana datasource proxy.

Args: query: LogQL expression. limit: Maximum number of log lines to return (1–5000, default 100). at: Evaluation timestamp. RFC 3339 or Unix nanosecond string. Defaults to now when omitted.

Returns: JSON payload from Loki with matching log entries.

ParametersJSON Schema

Name	Required	Description	Default
`at`	No
`limit`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.3/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided. The description does not disclose behavioral traits such as idempotency, side effects, or read-only nature. It only states it returns a JSON payload. For a tool with no annotations, this is adequate but lacks explicit safety context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, uses a clear docstring format with Args and Returns sections, and front-loads the main purpose. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a three-parameter tool with no output schema beyond 'JSON payload', the description covers inputs and return value adequately. It could briefly explain the concept of an 'instant' query or mention limitations like paging, but overall it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully explains all three parameters: query (LogQL expression), limit (range and default), and at (timestamp format and default). This adds significant value beyond the schema's typed definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool runs a Loki instant query through Grafana datasource proxy using LogQL. The purpose is specific: return matching log entries from an instant query. It distinguishes from siblings like list_loki_labels and query_loki_logs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for point-in-time queries via 'instant' and default timestamp 'now'. However, no explicit guidance on when to prefer this over query_loki_logs (range) or query_metrics is given, leaving some ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_loki_logsA

Run a Loki range query through Grafana datasource proxy.

Args: query: LogQL expression, e.g. {app="myservice"} |= "error". limit: Maximum number of log lines to return (1–5000, default 100). direction: "backward" (newest first, default) or "forward". start: Start of the time range. RFC 3339 or Unix nanosecond string. end: End of the time range. RFC 3339 or Unix nanosecond string.

Returns: JSON payload from Loki with streams and log entries.

ParametersJSON Schema

Name	Required	Default
`end`	No
`limit`	No
`query`	Yes
`start`	No
`direction`	No	backward

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full behavioral disclosure. It explains the tool goes through a proxy, returns a JSON payload with logs, and documents all parameters. It doesn't mention authentication requirements or rate limits, but overall it is transparent for a read-only query tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise: a one-sentence summary followed by a bullet list of args and return value. No extraneous information, every line adds value. It is well-structured and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given five parameters and an output schema, the description covers all inputs and the return type. It omits potential limitations (e.g., max time range) and authentication context, but provides enough for an agent to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Despite 0% schema description coverage, the description provides comprehensive parameter details: query syntax example, limit range (1-5000), direction options with defaults, and start/end format (RFC 3339 or Unix nanosecond). This fully compensates for the lack of schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool performs a range query on Loki logs via the Grafana datasource proxy, distinguishing it from siblings like query_loki_instant (for instant queries) and list_loki_labels (for metadata). The verb 'Run' and specific resource 'Loki range query' provide precise purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implicitly differentiates from siblings by specifying 'range query' versus instant queries, and the parameter details for start/end make the usage context clear. However, it lacks explicit guidance on when to use this tool versus alternatives like query_loki_instant.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_metricsA

Run an instant PromQL query against Thanos.

Args: query: PromQL expression, e.g. rate(http_requests_total[5m]). time: Optional evaluation timestamp. Accepts RFC 3339 strings (2024-01-01T00:00:00Z) or Unix timestamps as strings. Defaults to now when omitted.

Returns: JSON payload from Thanos containing resultType and result.

ParametersJSON Schema

Name	Required	Description	Default
`time`	No
`query`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. It discloses return value structure ('JSON payload with resultType and result') and default behavior for time ('now when omitted'). It does not mention side effects or error conditions, but the read-only nature is implied. For a simple query tool, this is sufficient but not exhaustive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is very concise, with a clear one-line summary followed by structured parameter explanations and return value description. Every sentence adds value, and the key information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (2 parameters, no nested objects) and the presence of an output schema (though not detailed), the description covers core functionality. It explains the return JSON structure and parameter semantics. Minor omissions like error handling or rate limits are acceptable for a straightforward query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description fully explains both parameters: query with a concrete PromQL example, time with explicit format options (RFC 3339 and Unix timestamps) and default behavior. This compensates completely for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run an instant PromQL query against Thanos.' It specifies the verb (Run), the resource (PromQL query), and the scope (instant, as opposed to range queries). The differentiation from siblings like query_metrics_range and the Loki tools is implicit through the naming and context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides examples for both parameters (query and time) and explains optional timestamp formats. However, it does not explicitly state when to use this tool versus siblings like query_metrics_range or Loki tools. The guidance is adequate for parameter usage but could be improved with direct alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_metrics_rangeA

Run a PromQL range query against Thanos.

Args: query: PromQL expression. start: Start of the time range. RFC 3339 or Unix timestamp string. end: End of the time range. RFC 3339 or Unix timestamp string. step: Query resolution step width. Duration string (60s, 5m) or float seconds.

Returns: JSON payload with resultType: "matrix" and the time-series data.

ParametersJSON Schema

Name	Required	Description	Default
`end`	Yes
`step`	Yes
`query`	Yes
`start`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

A3.9/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It declares a read operation (query) but does not disclose potential side effects, idempotency, rate limits, or authorization needs. The return type is described, but deeper behavioral traits are missing.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is structured with Args and Returns sections, no redundant sentences. Every sentence adds value, and the format is easily scannable.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema, the description covers inputs and outputs well. It could briefly contrast with query_metrics for clarity, but overall it is sufficient for a straightforward query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains each parameter in detail (e.g., start/end as RFC 3339 or Unix timestamp, step as duration string or float seconds). The schema lacks descriptions, so the description adds critical meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Run a PromQL range query against Thanos.' It specifies the resource (Thanos), action (range query), and distinguishes from sibling tools like query_metrics which likely perform instant queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for range queries vs. instant queries, but does not explicitly state when to use this tool over alternatives like query_metrics or Loki-based tools. No guidance on prerequisites or exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

8 tool updatesv0.1.0Jul 28, 2026
- First observedlist_labels
- First observedlist_loki_label_values
- First observedlist_loki_labels
- First observedlist_series
- First observedquery_loki_instant
- First observedquery_loki_logs
- First observedquery_metrics
- First observedquery_metrics_range

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-07-28 04:50 across 8 tools

Disambiguation5/5

Each tool targets a distinct operation and data source (Loki vs. Thanos), with clear naming and descriptions that prevent confusion. Even similar tasks like label listing are differentiated by the datasource prefix.

Naming Consistency5/5

All tools follow a consistent verb_noun pattern in snake_case, e.g., 'query_loki_instant', 'list_labels'. The naming clearly indicates the action and the target, making it predictable and easy to understand.

Tool Count5/5

With 8 tools covering essential operations for two datasources (metrics and logs), the count is well-scoped. There are no redundant tools, and each tool serves a clear purpose without overwhelming the agent.

Completeness5/5

The tool set covers the core query and metadata exploration for both Loki and Thanos, including instant/range queries, label discovery, and series listing. No obvious gaps exist for standard observability workflows.

Maintenance

ActivityInactive

ResponsivenessNo issues

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

Foam Observability
io.github.foam-ai
Query application logs, traces, and metrics from your AI coding assistant via Foam's MCP server.
Observability Monitoring Developer Tools
2
Artificial Wit AIOAuth
com.artificialwit
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
ERP Systems CRM Knowledge & Memory
2
QuallaaOAuth
com.quallaa
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
AI & Machine Learning Communication
2
anotherai
dev.anotherai
MCP server for building and testing AI agents with multi-model experimentation and insights.
Agent Orchestration Autonomous Agents Testing & QA Tools
2

Related MCP Servers

Grafana MCP Server
Observability Monitoring
DrDroidLab
A
license
A
quality
D
maintenance
A server that enables AI assistants to access and query Grafana dashboards, metrics, logs, and configurations through an MCP protocol interface.
Updated a year ago (2025-07-24 16:55 UTC)
10
6
MIT
mcp-server-logs-sieve
Monitoring Observability Search
Oluwatunmise-olat
A
license
Not graded
quality
C
maintenance
An MCP server that connects Claude (or any MCP compatible client) to your existing log infrastructure. Query, summarize, and trace logs in plain English across GCP Cloud Logging, AWS CloudWatch, Azure Log Analytics, Grafana Loki, and Elasticsearch without writing filter expressions or leaving your editor.
Updated 5 months ago (2026-04-22 13:13 UTC)
12 npm
3
MIT
loki-mcp-server
Observability Monitoring
mo-silent
F
license
Not graded
quality
F
maintenance
An MCP server that enables AI assistants to query and analyze logs from Grafana Loki using LogQL, supporting label discovery and keyword search.
Updated a year ago (2025-09-15 07:43 UTC)
4
-
OpenObserve MCP Server
Observability Monitoring
mdfranz
A
license
Not graded
quality
B
maintenance
An MCP server that enables AI assistants to query and explore your OpenObserve observability data. Provides read-only access to logs, metrics, and traces for analysis and troubleshooting.
Updated a month ago (2026-08-20 15:44 UTC)
5
MIT

observability-mcp

Packages

Requirements

Installation

From GitHub (recommended)

From source (local clone)

Quick start

Grafana / Loki

Thanos / Prometheus

Combined (both in one server)

Authentication

Grafana MCP

Thanos MCP

Cursor MCP configuration

Combined server (one entry)

Available MCP tools

Grafana/Loki tools (grafana_mcp)

Thanos/Prometheus tools (thanos_mcp)

Development

Environment variable reference

License

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Grafana/Loki tools (`grafana_mcp`)

Thanos/Prometheus tools (`thanos_mcp`)