Skip to content
Back to search

signoz-mcp-server

MCP Server for SigNoz

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/SigNoz/signoz-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/SigNoz/signoz-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/signoz--signoz-mcp-server/badge.svg)](/listings/signoz--signoz-mcp-server)

HTML

<a href="/listings/signoz--signoz-mcp-server"><img src="/api/listings/signoz--signoz-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download Binary (Recommended)

Download the latest binary from [GitHub Releases](https://github.com/SigNoz/signoz-mcp-server/releases):

# macOS (Apple Silicon)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_arm64.tar.gz | tar xz

# macOS (Intel)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_amd64.tar.gz | tar xz

# Linux (amd64)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_amd64.tar.gz | tar xz

This extracts a `signoz-mcp-server` binary in the current directory. Move it somewhere on your PATH or note the absolute path for the config below.

Go Install

go install github.com/SigNoz/signoz-mcp-server/cmd/server@latest

The binary is installed as `server` to `$GOPATH/bin/` (default: `$HOME/go/bin/server`). You may want to rename it:

mv "$(go env GOPATH)/bin/server" "$(go env GOPATH)/bin/signoz-mcp-server"

Docker

Docker images are available on [Docker Hub](https://hub.docker.com/r/signoz/signoz-mcp-server/tags):

docker pull signoz/signoz-mcp-server:latest

Run in HTTP mode:

docker run -p 8000:8000 \
  -e TRANSPORT_MODE=http \
  -e MCP_SERVER_PORT=8000 \
  -e SIGNOZ_URL=https://your-signoz-instance.com \
  -e SIGNOZ_API_KEY=your-api-key \
  signoz/signoz-mcp-server:latest

Use a specific version tag (e.g. `v0.1.0`) instead of `latest` for pinned deployments.

Build from Source

git clone https://github.com/SigNoz/signoz-mcp-server.git
cd signoz-mcp-server
make build

The binary is at `./bin/signoz-mcp-server`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,261 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # SigNoz MCP Server
  2. [![Go Version](https://img.shields.io/badge/Go-1.26.11+-blue.svg)](https://golang.org)
  3. [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
  4. [![MCP Protocol](https://img.shields.io/badge/MCP-2025--11--25_%7C_2026--07--28-orange.svg)](https://modelcontextprotocol.io)
  5. A Model Context Protocol (MCP) server that provides seamless access to SigNoz observability data through AI assistants and LLMs. Query metrics, traces, logs, alerts, dashboards, and services using natural language.
  6. **[📖 Full Documentation](https://signoz.io/docs/ai/signoz-mcp-server/)**
  7. ## Table of Contents
  8. - [Connect to SigNoz Cloud](#connect-to-signoz-cloud)
  9. - [Self-Hosted Installation](#self-hosted-installation)
  10. - [Connect to Self-Hosted SigNoz](#connect-to-self-hosted-signoz)
  11. - [MCP Protocol Compatibility](#mcp-protocol-compatibility)
  12. - [What Can You Do With It?](#what-can-you-do-with-it)
  13. - [Available Tools](#available-tools)
  14. - [Environment Variables](#environment-variables)
  15. - [Claude Desktop Extension](#claude-desktop-extension)
  16. - [End-to-End Tests](#end-to-end-tests)
  17. - [Architecture](#architecture)
  18. - [Contributing](#contributing)
  19. ## Connect to SigNoz Cloud
  20. Connect your AI tool to SigNoz Cloud's hosted MCP server. No installation is required; just add the hosted MCP URL and authenticate.
  21. ```text
  22. https://mcp.<region>.signoz.cloud/mcp
  23. ```
  24. > Make sure you select the correct region that matches your SigNoz Cloud account. Using the wrong region will result in authentication failures.
  25. >
  26. > Find your region under **Settings → Ingestion** in SigNoz, or see the [SigNoz Cloud region reference](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint).
  27. ### One-Click Install Links
  28. GitHub does not reliably make custom-protocol links like `cursor://` and `vscode:` clickable in README rendering.
  29. Use the documentation page for one-click install buttons:
  30. - [Open one-click install links for Cursor](https://signoz.io/docs/ai/signoz-mcp-server/#install-in-one-click)
  31. - [Open one-click install links for VS Code](https://signoz.io/docs/ai/signoz-mcp-server/#install-in-one-click-1)
  32. If you prefer, use the manual configuration examples below in this README.
  33. ### Cursor
  34. #### Manual Configuration
  35. Add this configuration to `.cursor/mcp.json`:
  36. ```json
  37. {
  38. "mcpServers": {
  39. "signoz": {
  40. "url": "https://mcp.<region>.signoz.cloud/mcp"
  41. }
  42. }
  43. }
  44. ```
  45. Need help? See the [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol).
  46. ### VS Code / GitHub Copilot
  47. #### Manual Configuration
  48. Add this configuration to `.vscode/mcp.json`:
  49. ```json
  50. {
  51. "servers": {
  52. "signoz": {
  53. "type": "http",
  54. "url": "https://mcp.<region>.signoz.cloud/mcp"
  55. }
  56. }
  57. }
  58. ```
  59. Need help? See the [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers).
  60. ### Claude Desktop
  61. Add SigNoz Cloud as a custom connector in Claude Desktop:
  62. 1. Open Claude Desktop.
  63. 2. Go to **Settings → Developer** (or **Features**, depending on your version).
  64. 3. Click **Add Custom Connector** or **Add Remote MCP Server**.
  65. 4. Enter your SigNoz MCP URL: `https://mcp.<region>.signoz.cloud/mcp`
  66. When prompted, complete the authentication flow.
  67. ### Claude Code
  68. Run this command to add the hosted SigNoz MCP server:
  69. ```bash
  70. claude mcp add --scope user --transport http signoz https://mcp.<region>.signoz.cloud/mcp
  71. ```
  72. After configuring the MCP server, authenticate in a terminal:
  73. ```bash
  74. claude /mcp
  75. ```
  76. Select the `signoz` server and complete the authentication flow.
  77. ### OpenAI Codex
  78. Run this command to add the hosted SigNoz MCP server:
  79. ```bash
  80. codex mcp add signoz --url https://mcp.<region>.signoz.cloud/mcp
  81. ```
  82. Or add this configuration to `config.toml`:
  83. ```toml
  84. [mcp_servers.signoz]
  85. url = "https://mcp.<region>.signoz.cloud/mcp"
  86. ```
  87. After adding the server, authenticate:
  88. ```bash
  89. codex mcp login signoz
  90. ```
  91. Then run `/mcp` inside Codex to verify the connection.
  92. ### Grok Build
  93. Run this command to add the hosted SigNoz MCP server:
  94. ```bash
  95. grok mcp add -t http signoz https://mcp.<region>.signoz.cloud/mcp
  96. ```
  97. Or add this configuration to `~/.grok/config.toml`:
  98. ```toml
  99. [mcp_servers.signoz]
  100. url = "https://mcp.<region>.signoz.cloud/mcp"
  101. enabled = true
  102. ```
  103. Adding the server does not authenticate it. Start Grok Build, run `/mcps`, select the `signoz` server, and complete the OAuth flow in your browser:
  104. ```bash
  105. grok
  106. ```
  107. ```
  108. /mcps
  109. ```
  110. No API key is stored in the config file; credentials are saved separately once the OAuth flow completes.
  111. Use `-s project` on the `add` command to write to `./.grok/config.toml` instead, so the server is shared with everyone working in that directory.
  112. Verify the connection with:
  113. ```bash
  114. grok mcp list
  115. grok mcp doctor
  116. ```
  117. ### SigNoz Cloud Authentication
  118. When you add the hosted MCP URL to your client, the client initiates an authentication flow. You will be prompted to enter:
  119. 1. Your SigNoz instance URL (for example, `your-instance.signoz.cloud`). Protocol-less URLs are accepted; paths, query parameters, and fragments are ignored.
  120. 2. Your API key
  121. Create an API key in **Settings → API Keys** in SigNoz. Only **Admin** users can create API keys.
  122. ## Self-Hosted Installation
  123. ### Download Binary (Recommended)
  124. Download the latest binary from [GitHub Releases](https://github.com/SigNoz/signoz-mcp-server/releases):
  125. ```bash
  126. # macOS (Apple Silicon)
  127. curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_arm64.tar.gz | tar xz
  128. # macOS (Intel)
  129. curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_amd64.tar.gz | tar xz
  130. # Linux (amd64)
  131. curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_amd64.tar.gz | tar xz
  132. ```
  133. This extracts a `signoz-mcp-server` binary in the current directory. Move it somewhere on your PATH or note the absolute path for the config below.
  134. ### Go Install
  135. ```bash
  136. go install github.com/SigNoz/signoz-mcp-server/cmd/server@latest
  137. ```
  138. The binary is installed as `server` to `$GOPATH/bin/` (default: `$HOME/go/bin/server`). You may want to rename it:
  139. ```bash
  140. mv "$(go env GOPATH)/bin/server" "$(go env GOPATH)/bin/signoz-mcp-server"
  141. ```
  142. ### Docker
  143. Docker images are available on [Docker Hub](https://hub.docker.com/r/signoz/signoz-mcp-server/tags):
  144. ```bash
  145. docker pull signoz/signoz-mcp-server:latest
  146. ```
  147. Run in HTTP mode:
  148. ```bash
  149. docker run -p 8000:8000 \
  150. -e TRANSPORT_MODE=http \
  151. -e MCP_SERVER_PORT=8000 \
  152. -e SIGNOZ_URL=https://your-signoz-instance.com \
  153. -e SIGNOZ_API_KEY=your-api-key \
  154. signoz/signoz-mcp-server:latest
  155. ```
  156. Use a specific version tag (e.g. `v0.1.0`) instead of `latest` for pinned deployments.
  157. ### Build from Source
  158. ```bash
  159. git clone https://github.com/SigNoz/signoz-mcp-server.git
  160. cd signoz-mcp-server
  161. make build
  162. ```
  163. The binary is at `./bin/signoz-mcp-server`.
  164. To check which build you have, run `./bin/signoz-mcp-server --version`.
  165. ## Connect to Self-Hosted SigNoz
  166. ### Prerequisites
  167. - A running [SigNoz](https://signoz.io) instance on the latest release. Each server release targets the latest SigNoz release and is not tested against older versions; see [CHANGELOG.md](CHANGELOG.md) for breaking changes.
  168. - A SigNoz API key (Settings → API Keys in the SigNoz UI)
  169. - The `signoz-mcp-server` binary (see [Self-Hosted Installation](#self-hosted-installation))
  170. ### Stdio Mode (Claude Desktop / Cursor / Any MCP Client)
  171. Add this to your MCP client config (`claude_desktop_config.json`, `.cursor/mcp.json`, etc.). Replace the `command` path with the absolute path to your `signoz-mcp-server` binary:
  172. ```json
  173. {
  174. "mcpServers": {
  175. "signoz": {
  176. "command": "/absolute/path/to/signoz-mcp-server",
  177. "args": [],
  178. "env": {
  179. "SIGNOZ_URL": "https://your-signoz-instance.com",
  180. "SIGNOZ_API_KEY": "your-api-key-here",
  181. "LOG_LEVEL": "info"
  182. }
  183. }
  184. }
  185. }
  186. ```
  187. ### HTTP Mode
  188. HTTP mode listens on all interfaces by default. Set `MCP_SERVER_HOST=127.0.0.1` when the server should accept loopback connections only.
  189. #### Memory footprint
  190. The server keeps the SigNoz docs search index in memory. With stemming on titles and headings and a single standard-analyzed body field, the embedded 746-page index used 28 to 36 MiB of resident heap across eight local Go 1.26 whole-package test runs. Build peaks ranged from 97 to 134 MiB above the pre-build heap baseline, using 64-page batches. These are index measurements, not whole-process RSS or container memory guarantees; request handling and refresh work add memory.
  191. | Moment | Index memory behavior |
  192. | --- | --- |
  193. | Startup build from the embedded corpus (746 pages) | Up to 134 MiB above the pre-build heap baseline in the measured runs |
  194. | Scheduled full rebuild | Builds a new index while the old index is still serving; combined peak has not been re-measured with this configuration |
  195. | Scheduled refresh that changes a few pages | Applies changed pages in one atomic batch to the live index; peak depends on the changed content and has not been re-measured with this configuration |
  196. | Scheduled refresh that finds no changed pages | no index work; pages are revalidated with `If-None-Match` and unchanged ones cost a 304 |
  197. A scheduled refresh (default every `6h`) first compares the live sitemap with the served one and stops there when it is unchanged. Otherwise it revalidates every page with `If-None-Match` and touches the index only when at least one page's content changed. A change set covering up to a quarter of the pages is applied to the live index in place; a larger one, the 25th in-place update on the same index, and any forced refresh (default every `24h`) that finds changed content rebuild the index from scratch, which also compacts the segments that in-place updates leave behind. Full rebuilds use 64-page batches. In-place updates use one atomic batch bounded by the quarter-of-pages threshold, not the full-build batch size.
  198. Recommendations for containerized HTTP deployments:
  199. - Set the memory limit to at least `512Mi`, and monitor memory during refreshes and concurrent requests. The highest measured index-only build peak is 134 MiB above baseline and the resident index is 28 to 36 MiB; rebuilds also retain the serving index. Setting Go's `GOMEMLIMIT` is optional: it can reclaim garbage earlier but cannot shrink live data inside an index batch.
  200. - Set both `SIGNOZ_DOCS_REFRESH_INTERVAL=0` and `SIGNOZ_DOCS_FULL_REFRESH_INTERVAL=0` when you would rather serve the docs snapshot that shipped with the release than pay any refresh. New docs pages then arrive with the next server upgrade. Setting only the first keeps the daily forced refresh.
  201. - Every refresh logs `docs refresh starting` and ends with a completion or failure line, for example `docs refresh no-op; sitemap unchanged`, `docs refresh found no page changes; index kept`, `docs refresh applied delta`, `docs refresh rebuilt index`, or a `docs refresh failed` / `docs full refresh failed` warning. A refresh normally finishes within a few minutes. A container whose last docs line is `docs refresh starting`, `docs refresh fetching pages`, or `docs refresh rebuilding index` and that then restarted most likely died mid-refresh.
  202. #### With OAuth (Multi-Tenant / Cloud)
  203. Start the server:
  204. ```bash
  205. TRANSPORT_MODE=http \
  206. MCP_SERVER_PORT=8000 \
  207. OAUTH_ENABLED=true \
  208. OAUTH_TOKEN_SECRET=$(openssl rand -base64 32) \
  209. OAUTH_ISSUER_URL=https://your-public-mcp-url.com \
  210. ./signoz-mcp-server
  211. ```
  212. Client config needs just the URL, no keys:
  213. ```json
  214. {
  215. "mcpServers": {
  216. "signoz": {
  217. "url": "https://your-public-mcp-url.com/mcp"
  218. }
  219. }
  220. }
  221. ```
  222. The client discovers OAuth endpoints automatically, opens a browser, and handles token exchange. In the browser, users either sign in to their SigNoz instance with their own account (password or SSO), so the client acts as them, or paste a service-account API key. Revoking a token at `/oauth/revoke` ends the SigNoz session behind it.
  223. SSO sign-in needs the MCP server's origin (`OAUTH_ISSUER_URL`) to pass the SigNoz instance's `global.allowed_origins` when that list is set. Each signed-in client holds an ordinary SigNoz session, which counts toward SigNoz's per-user session limit.
  224. #### Without OAuth (Simple Setup)
  225. The API key and SigNoz URL only need to be provided in **one** place: the server or the client.
  226. **Option A — Credentials on the server** (simpler client config). The server-held key is sent only to `SIGNOZ_URL`. A request that names another instance in `X-SigNoz-URL` must carry its own `SIGNOZ-API-KEY` or `Authorization` header, or it is refused with HTTP 401.
  227. ```bash
  228. SIGNOZ_URL=https://your-signoz-instance.com \
  229. SIGNOZ_API_KEY=your-api-key \
  230. TRANSPORT_MODE=http \
  231. MCP_SERVER_PORT=8000 \
  232. ./signoz-mcp-server
  233. ```
  234. ```json
  235. {
  236. "mcpServers": {
  237. "signoz": {
  238. "url": "http://localhost:8000/mcp"
  239. }
  240. }
  241. }
  242. ```
  243. **Option B — API key on the client** (server holds the URL, client sends the key):
  244. ```bash
  245. SIGNOZ_URL=https://your-signoz-instance.com \
  246. TRANSPORT_MODE=http \
  247. MCP_SERVER_PORT=8000 \
  248. ./signoz-mcp-server
  249. ```
  250. ```json
  251. {
  252. "mcpServers": {
  253. "signoz": {
  254. "url": "http://localhost:8000/mcp",
  255. "headers": {
  256. "SIGNOZ-API-KEY": "your-api-key-here"
  257. }
  258. }
  259. }
  260. }
  261. ```
  262. ## MCP Protocol Compatibility
  263. SigNoz uses the official MCP Go SDK v1.8.0 and supports both current lifecycle
  264. models over HTTP and stdio:
  265. | Protocol era | Lifecycle |
  266. |---|---|
  267. | `2025-11-25` | Legacy clients use `initialize`, then `notifications/initialized`, before ordinary requests. |
  268. | `2026-07-28` | Clients may call `server/discover`, then send direct requests carrying protocol and client capabilities in per-request `_meta`; no initialize handshake is required. |
  269. The HTTP `/mcp` endpoint is stateless and sessionless. MCP messages use JSON
  270. `POST` requests and successful responses use `application/json`; the server does
  271. not issue or require `Mcp-Session-Id`. `GET /mcp` and `DELETE /mcp` return
  272. `405 Method Not Allowed`, so deployments need neither sticky routing nor the old
  273. GET listener/heartbeat. Existing client configuration does not change.
  274. Stdio input has a 16 MiB frame limit. Split larger requests into smaller calls.
  275. `MCP_MAX_REQUEST_BYTES` controls HTTP request bodies only.
  276. The server intentionally does not advertise the deprecated logging capability.
  277. Discovery ordering is not a compatibility guarantee. Unknown tools, resources,
  278. and prompts use the official SDK's standard invalid-params behavior rather than
  279. legacy implementation-specific wording or error codes.
  280. ### HTTP Probe Endpoints
  281. HTTP mode exposes unauthenticated probe endpoints. New Kubernetes deployments should use `/livez` for `livenessProbe` and `/readyz` for `readinessProbe`.
  282. | Endpoint | Purpose |
  283. |----------|---------|
  284. | `/livez` | Shallow liveness probe. Returns `200 OK` when the server process can answer HTTP requests. It does not check dependencies. |
  285. | `/readyz` | Readiness probe. Returns `200 OK` only after the pod is ready to receive traffic; currently this requires the docs index to be ready. Otherwise returns `503`. |
  286. | `/healthz` | Legacy/generic health check kept for backward compatibility. It follows the same strict status as `/readyz`; use `/livez` for shallow liveness. |
  287. ## What Can You Do With It?
  288. ```
  289. "Show me all available metrics"
  290. "What's the p99 latency for http_request_duration_seconds?"
  291. "List all active alerts"
  292. "Show me error logs for the paymentservice from the last hour"
  293. "How many errors per service in the last hour?"
  294. "Search traces for the checkout service from the last hour"
  295. "Get details for trace ID abc123"
  296. "Create a dashboard with CPU and memory widgets"
  297. "How do I send Docker logs to SigNoz?"
  298. ```
  299. ## Available Tools
  300. > **Tool metadata:** every tool accepts `searchContext`. Copy the user's entire original request verbatim, including preflight or confirmation context; it is used for MCP observability and is not forwarded to SigNoz APIs.
  301. > **Input validation:** calls are never rejected for schema mismatches. Arguments are validated against each tool's advertised schema; a mismatched call still runs best-effort, and the successful result carries a deterministic appended `Input validation notice:` naming the affected top-level parameter when it can be derived safely from the advertised schema. Complex root-only mismatches use a generic fallback. Mismatches are also counted in the `mcp.tool.validation.mismatches` metric. Arguments a tool's schema does not declare are not rejected either: a successful result carries an appended `Input validation notice:` naming the ones the tool ignored. Short identifier-like names are listed and any other name is only counted. An argument the handler takes on purpose draws no notice: a legacy alias it reads (`ruleId`, `viewId`, `filterExpression` on `signoz_get_alert_history`, `query` on `signoz_search_docs`); a field `signoz_create_alert`, `signoz_update_alert`, `signoz_create_dashboard`, or `signoz_create_view` sends to SigNoz in the resource body, where SigNoz decides what it means; and a read-only field of a fetched dashboard sent back to `signoz_update_dashboard`, which strips those fields before the update. That tool reports `locked: true`, because it can't lock a dashboard. A few tools reject undeclared arguments with a coded error instead, such as the retired log `query` alias or an unknown notification-channel field. Every undeclared argument is also logged at WARN with its name and counted in the same metric under path `<undeclared>` and constraint `undeclared_argument`.
  302. > **Upstream errors:** upstream SigNoz 401 and 403 tool failures carry a stable structured `code` (`UNAUTHORIZED` or `PERMISSION_DENIED`) and numeric `status`. Recognized SigNoz error envelopes may also include bounded `upstreamURL`, `upstreamSuggestions`, `upstreamDetails` (`[{message, suggestions}]`), and `upstreamRetry` (`{delay}` in nanoseconds); the same recovery guidance appears in agent-readable text. Unrecognized bodies use the local status-derived coded fallback instead of raw passthrough, and authorization failures still name the failed tool and immediate recovery action. This error-only addition does not change tool names, schemas or descriptions, success payloads, resources or templates, or prompts.
  303. | Tool | Description |
  304. |------|-------------|
  305. | `signoz_get_org_overview` | Get the current status and overall posture of the SigNoz deployment, with typed projections plus `sourceStats` containing every reported stats field |
  306. | `signoz_list_metrics` | Discover active metric names and catalog metadata |
  307. | `signoz_query_metrics` | Query known metrics for values, trends, breakdowns, or formulas |
  308. | `signoz_get_top_metrics` | Return top 100 metrics ranked by ingested sample volume with pre-computed percentages for cost and volume analysis |
  309. | `signoz_check_metric_usage` | Given a list of metric names (up to 50 per call), return which dashboards and alerts reference each one |
  310. | `signoz_check_metric_cardinality` | Return label/attribute keys for a single metric with cardinality counts and sample values, sorted highest-cardinality first |
  311. | `signoz_get_field_keys` | Discover available field keys for metrics, traces, or logs, including AI trace fields |
  312. | `signoz_get_field_values` | Get possible values for a field key |
  313. | `signoz_list_alerts` | List firing/silenced/inhibited Alertmanager alert *instances* (not rule definitions) |
  314. | `signoz_list_alert_rules` | List configured alert-rule summaries, including inactive/OK and disabled rules |
  315. | `signoz_get_alert` | Get one alert rule's full definition by `id` |
  316. | `signoz_get_alert_history` | Get one rule's firing or state-transition history |
  317. | `signoz_create_alert` | Create a v2alpha1 threshold, PromQL, or anomaly alert with direct or policy routing |
  318. | `signoz_update_alert` | Fully replace an existing alert rule by `id` |
  319. | `signoz_delete_alert` | Permanently delete a confirmed alert rule by UUIDv7 `id` |
  320. | `signoz_list_dashboards` | List tenant-dashboard summaries and discover UUIDs |
  321. | `signoz_get_dashboard` | Get one dashboard's full layout, variables, panels, and queries |
  322. | `signoz_create_dashboard` | Create a custom multi-panel dashboard |
  323. | `signoz_update_dashboard` | Fully replace a fetched dashboard while preserving unrequested fields |
  324. | `signoz_patch_dashboard` | Apply a partial RFC 6902 JSON Patch without resending the whole dashboard |
  325. | `signoz_delete_dashboard` | Permanently delete a confirmed dashboard by `id` |
  326. | `signoz_import_dashboard` | Create a dashboard from a known curated template path |
  327. | `signoz_list_dashboard_templates` | Search curated templates and discover an import path |
  328. | `signoz_list_services` | List APM services with trace activity in a time range |
  329. | `signoz_get_service_top_operations` | Get ranked operations for one traced service |
  330. | `signoz_list_views` | List saved Explorer views for traces/logs/metrics/Cost Meter and discover UUIDs |
  331. | `signoz_get_view` | Get one saved Explorer view's complete definition by `id` |
  332. | `signoz_search_docs` | Find ranked official-doc matches when no exact page is selected |
  333. | `signoz_fetch_doc` | Fetch one known official-doc page or heading as Markdown |
  334. | `signoz_create_view` | Save one reusable Explorer query spec |
  335. | `signoz_update_view` | Fully replace a fetched saved view while preserving unrequested fields |
  336. | `signoz_delete_view` | Permanently delete a confirmed saved view by `id` |
  337. | `signoz_aggregate_logs` | Aggregate log statistics and grouped or top-N breakdowns |
  338. | `signoz_search_logs` | Return individual log records matching filters |
  339. | `signoz_aggregate_traces` | Aggregate span or per-AI-trace statistics and grouped or top-N breakdowns |
  340. | `signoz_search_traces` | Return span rows or one row per trace (including AI traces), or discover trace IDs |
  341. | `signoz_get_trace_details` | Get one known trace with all spans and hierarchy |
  342. | `signoz_get_ai_pricing` | List AI model prices, or models seen in the last hour with no price |
  343. | `signoz_list_ai_attribute_mappings` | List the mapping groups that turn vendor AI span attributes into `gen_ai.*` keys |
  344. | `signoz_test_ai_attribute_mapping` | Run sample spans through the AI attribute mappings without saving anything |
  345. | `signoz_execute_builder_query` | Query Builder v5 requests the dedicated tools cannot express |
  346. | `signoz_list_notification_channels` | List channel IDs, names, and display names without provider settings |
  347. | `signoz_get_notification_channel` | Get all provider-specific settings for one channel by ID |
  348. | `signoz_create_notification_channel` | Create a notification channel |
  349. | `signoz_update_notification_channel` | Fully replace a fetched channel's config |
  350. | `signoz_delete_notification_channel` | Permanently delete a confirmed channel by ID |
  351. | `signoz_submit_feedback` | Send feedback to the SigNoz team: a problem with this MCP server, or the user's feedback about SigNoz |
  352. For detailed usage and examples, see the [full documentation](https://signoz.io/docs/ai/signoz-mcp-server/).
  353. > **Resource deep links:** the resource read tools (`signoz_list_dashboards`, `signoz_get_dashboard`, `signoz_list_alerts`, `signoz_list_alert_rules`, `signoz_get_alert`, `signoz_list_services`, `signoz_search_traces`, `signoz_get_trace_details`) and the dashboard write tools (`signoz_create_dashboard`, `signoz_update_dashboard`, `signoz_patch_dashboard`, `signoz_import_dashboard`) include a `webUrl` field when the request carries a SigNoz instance URL: an absolute deep link to the resource in the SigNoz web UI (per result row for `signoz_search_traces`). The MCP server discovers the browser base from each SigNoz backend's `global.external_url`. API requests keep using the request's backend URL. See [Browser links for self-hosted SigNoz](#browser-links-for-self-hosted-signoz).
  354. ### Agent Routing Guidance
  355. Use `signoz_search_docs` for topical discovery when no exact documentation page is selected, then `signoz_fetch_doc` for the chosen page or heading. Use live data tools for tenant telemetry, alert state, dashboards, saved views, and notification channels.
  356. Docs tools use the same authentication path as other MCP tools.
  357. ### Available Resources
  358. | Resource | Read when you need |
  359. |---|---|
  360. | `signoz://alert/instructions` | Alert schemas, fields, thresholds, evaluation, and notification workflow |
  361. | `signoz://alert/examples` | Alert payloads from the SigNoz OpenAPI spec (threshold, formula, PromQL, anomaly, tiered routing, notification settings) plus a Cost Meter budget example |
  362. | `signoz://dashboard/instructions` | Dashboard fields, variables, chaining, and layout |
  363. | `signoz://dashboard/widgets-instructions` | Panel choices and query-specific guides |
  364. | `signoz://dashboard/widgets-examples` | Panel examples and validation patterns |
  365. | `signoz://dashboard/list-filter-guide` | `signoz_list_dashboards` filter DSL: grammar, per-key operators, and examples |
  366. | `signoz://dashboard/patch-instructions` | `signoz_patch_dashboard` JSON Patch recipes and exact paths (add/edit/move/remove a panel, query, variable) |
  367. | `signoz://dashboard/examples` | Dashboard payloads from the SigNoz OpenAPI spec: create bodies, a full replacement, and JSON Patch arrays |
  368. | `signoz://dashboard/query-builder-example` | Dashboard Query Builder aggregations, filters, legends, and functions |
  369. | `signoz://promql/instructions` | PromQL widgets or alerts, especially dotted OTel metric names |
  370. | `signoz://dashboard/clickhouse-schema-for-logs` | Bundled logs schema snapshot for dashboard SQL |
  371. | `signoz://dashboard/clickhouse-logs-example` | Raw ClickHouse logs widget patterns |
  372. | `signoz://dashboard/clickhouse-schema-for-metrics` | Bundled metrics schema snapshot for dashboard SQL |
  373. | `signoz://dashboard/clickhouse-metrics-example` | Raw ClickHouse metrics widget patterns |
  374. | `signoz://dashboard/clickhouse-schema-for-traces` | Bundled traces schema snapshot for dashboard SQL |
  375. | `signoz://dashboard/clickhouse-traces-example` | Raw ClickHouse traces widget patterns |
  376. | `signoz://logs/query-builder-guide` | Logs Query Builder v5 JSON or unfamiliar log fields |
  377. | `signoz://traces/query-builder-guide` | Traces Query Builder v5 JSON or unfamiliar trace fields |
  378. | `signoz://ai/query-builder-guide` | AI agent and LLM queries: when to set `queryType: builder_ai_query`, per-trace cost, token, and call-count keys, caveats, and examples |
  379. | `signoz://metrics-aggregation-guide` | Metric aggregations, formulas, grouping, limits, and Cost Meter queries |
  380. | `signoz://query-builder/examples` | `query_range` requests from the SigNoz OpenAPI spec, per query type and request type for `signoz_execute_builder_query` |
  381. | `signoz://notification-channel/examples` | Every notification channel kind, its `config.spec` fields, and a worked payload per kind |
  382. | `signoz://view/instructions` | Saved view fields, the v2 typed spec, and read-before-replace workflow |
  383. | `signoz://view/examples` | Saved-view payloads from the SigNoz OpenAPI spec for logs, traces, metrics, and Cost Meter, plus a replacement body |
  384. | `signoz://docs/sitemap` | Indexed official-doc catalog and page URLs |
  385. ### Resource Template Migration
  386. The live `signoz://dashboard/{id}/summary` and `signoz://alert/{id}/summary`
  387. resource templates are retired. `resources/templates/list` now returns an empty
  388. catalog. Use `signoz_get_dashboard` for a dashboard definition. For the former
  389. alert summary, call `signoz_get_alert`, then `signoz_get_alert_history`; omit the
  390. time range for the same six-hour window and set `limit: 10` and `order: "desc"`
  391. for the closest history result.
  392. <details>
  393. <summary><strong>Parameter Reference</strong></summary>
  394. #### `signoz_get_org_overview`
  395. Get the current status and overall posture of the SigNoz deployment before drilling into exact resources. `data.sourceStats` is the authoritative complete flat bag containing every key and value reported by the deployment stats endpoint, including current and future fields. Typed convenience projections cover telemetry freshness and volume, infrastructure presence, dashboards, alert rules and runtime, notification channels, saved views, log pipelines, cloud integrations, users, authentication, service accounts, roles, licensing, and configuration.
  396. - **Parameters**: no task parameters; like every tool, it accepts non-required `searchContext` for MCP observability.
  397. - **Authoritative source**: `sourceStats` preserves every successfully decoded entry from the upstream `data` object under its original dotted key. Use the grouped fields for convenient interpretation and `sourceStats` when exact backend coverage or a newly introduced field matters. Counts are deployment aggregates; use `signoz_list_dashboards`, `signoz_list_alert_rules`, `signoz_list_notification_channels`, or `signoz_list_views` for exact inventories; `signoz_list_metrics` for metric names; `signoz_list_alerts` for current alert instances; and `signoz_search_logs`, `signoz_search_traces`, or `signoz_query_metrics` for time-windowed or per-service data.
  398. - **Missing fields**: a key absent from `sourceStats` was not reported by the upstream collector and must not be interpreted as zero. The endpoint can return a partial HTTP 200 when an individual collector fails. In typed projections, a missing group total produces `available: false`; a reported zero produces `available: true`. Expected missing or invalid projection fields set `metadata.projectionPartial` and add an `incompleteGroups` entry with affected output paths, reason, next action, and exact fallback tools where available. An invalid projection value is still retained unchanged in `sourceStats` and named in `invalidProjectionFields`.
  399. - **Cloud-integration completeness**: `cloudIntegrations.sourceAvailability` reports whether both current AWS/Azure provider counts were reported. Each provider has its own `dataAvailable`; an absent provider count is never converted to zero. If neither provider is reported, source availability is `unavailable` without setting overall `metadata.projectionPartial`; this can mean cloud integrations are unsupported/edition-gated **or** both provider queries failed, so do not interpret it as “no cloud integrations configured.” If exactly one is reported, source availability is `partial` and the missing provider receives non-recursive recovery guidance. `connectedAccounts` means a non-removed account with an account ID and at least one agent report, not a recent check-in or proof that an integration service is enabled.
  400. - **Feature flags**: `featureFlags.flags` lists every flag from `GET /api/v2/features` with its `name`, `kind`, `stage`, `description`, and the `resolvedValue` in effect for this org, sorted by name. Some flags change how data is stored or queried, such as `use_json_body` for JSON log bodies. If SigNoz does not report them, `featureFlags.available` is `false` and `metadata.incompleteGroups` has a `featureFlags` entry; treat every flag as unknown, not off.
  401. - **Projection metadata**: `reportedStatCount` is the number of authoritative entries in `sourceStats`; `projectedStatCount` counts entries also represented in typed groups; and `unprojectedStatCount` counts entries available only in `sourceStats`, including future fields. `projectionPartial`, `incompleteGroups`, and `invalidProjectionFields` describe only typed-projection gaps; they do not indicate data was removed from `sourceStats` or claim endpoint-wide completeness.
  402. #### `signoz_list_metrics`
  403. Discover metric names and catalog metadata such as type, temporality, unit, and monotonicity. Use `signoz_query_metrics` for values or trends. This list has a limit but no offset pagination.
  404. - **Parameters**:
  405. - `searchText` (optional) - Filter metrics by name substring. Names separate words with dots or underscores (`system.cpu.time`, `http_server_duration`), so search one word, such as `cpu` or `memory`
  406. - `limit` (optional) - Maximum number of metrics to return (default: 50)
  407. - `timeRange` (optional) - Relative range: 30m, 1h, 6h, 24h, 7d (default: 1h; ignored when both `start` and `end` are provided)
  408. - `start`/`end` (optional) - Unix ms timestamps. When both are provided, they override `timeRange`.
  409. - `source` (optional) - Data-source filter. Use `"meter"` to list Cost Meter metrics, the usage/billing metrics SigNoz meters on (currently telemetry ingestion volume); omit for the default metrics store
  410. - **Completeness note**: the response appends a note reporting `hasMore` (inferred from `returnedRows == limit`) so a `limit`-truncated list is never mistaken for the full set; narrow with `searchText` for more specificity
  411. #### `signoz_query_metrics`
  412. Query a known metric for values, trends, breakdowns, or formulas. The tool applies metric-aware defaults and auto-fetches omitted metadata; call it directly when `metricName` is known. Use `signoz_list_metrics` only to discover a name or inspect catalog metadata.
  413. - **Parameters**:
  414. - `metricName` (required) - Metric name to query
  415. - `metricType` (optional) - gauge, sum, histogram, exponential_histogram, summary (auto-fetched if absent)
  416. - `isMonotonic` (optional) - Boolean (or the strings `"true"`/`"false"`); auto-fetched if absent. An invalid value is rejected rather than silently treated as false
  417. - `temporality` (optional) - cumulative, delta, unspecified (auto-fetched if absent)
  418. - `timeAggregation` (optional) - Aggregation within each series per time bucket (defaulted by type when omitted; SigNoz validates the combination)
  419. - `spaceAggregation` (optional) - Aggregation across series (defaulted by type when omitted; percentiles are histogram-only). Summary metrics need both aggregations set
  420. - `groupBy` (optional) - Label names to group by, as an array or a comma-separated string. Metric labels hold resource and data-point attributes in one set, so names need no context prefix. An array item that is not a string is rejected with a coded error
  421. - `filter` (optional) - Filter expression. Pass the expression text, not `{"expression": ...}`, which is rejected with a coded error. Regex matches use `REGEXP`, not PromQL's `=~`; a `=~` or `!~` that SigNoz rejects comes back with that hint. The former `query` alias is rejected with a coded error that names `filter`
  422. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '7d'; default: '1h'; ignored when both `start` and `end` are provided)
  423. - `start`/`end` (optional) - Unix ms timestamps. When both are provided, they override `timeRange`.
  424. - `stepInterval` (optional) - Step in seconds (auto-calculated if omitted)
  425. - `requestType` (optional) - Response format. Enum: `time_series` (default), `scalar`. Unknown values are rejected.
  426. - `reduceTo` (required when `requestType` is `scalar`) - How to reduce each series to one value: `last`, `max`, `min`, `avg`, `sum`, `count`, `median`. It has no default; SigNoz rejects a scalar request without it. For a total count use `timeAggregation: increase` with `reduceTo: sum`
  427. - `formula` (optional) - Expression over named queries (e.g., "A / B * 100")
  428. - `formulaQueries` (optional) - Array of additional named metric queries for `formula`, or a JSON-encoded string of that array. The item schema is typed: `name` and `metricName` are required; `metricType`, `isMonotonic`, `temporality`, `timeAggregation`, `spaceAggregation`, `reduceTo`, `groupBy` (array or comma-separated string), and `filter` mirror the top-level parameters and are auto-fetched or defaulted the same way.
  429. - `limit` (optional) - Maximum number of groups (series) in the result (default: 100, max: 10000; higher values are clamped). With a formula, limit applies to the formula result; formula inputs are not limited
  430. - `orderBy` (optional) - Result order as `<key> <direction>`, where the key is `__result` or a `groupBy` field (e.g. `__result asc`; default: `__result desc`)
  431. - `having` (optional) - Condition on the primary query's aggregated values, applied after grouping (e.g. `__result > 0.5`). With a formula it filters query A's series before the formula runs; SigNoz ignores a `having` on the formula result itself, so the tool never sends one there. SigNoz validates it
  432. - `functions` (optional) - Post-query transforms applied in order to each series, as an array of `{name, args}` objects (or a JSON-encoded string); each arg is `{"value": <number>}`. `timeShift` reads the window that many seconds earlier and returns its points on the current window's timestamps; `604800` gives the same window last week. To compare two windows, call once without `timeShift` and once with it. For `A - B` or `A / B` in one result, use `signoz_execute_builder_query` with two builder queries, the second with `timeShift`, and a `builder_formula`. `cutOffMin` and `cutOffMax` drop points below or above a threshold; `clampMin` and `clampMax` set them to it. `runningDiff` gives the change from the point before; `cumulativeSum` gives a running total. `ewma3`, `ewma5`, `ewma7`, `median3`, `median5`, and `median7` smooth a series; `fillZero` adds 0 at steps with no data; `absolute`, `log2`, and `log10` transform each value. SigNoz validates names and args. On a `scalar` request the functions run on each series before `reduceTo`. `formulaQueries` items take no functions
  433. - `source` (optional) - Data-source filter. Use `"meter"` to query Cost Meter data; omit for the default metrics store
  434. - **Result bounds**: standalone generated metric queries and formula results use `limit: 100` with `__result desc` unless `limit` or `orderBy` says otherwise. Queries feeding a formula get no limit, because SigNoz applies input limits before formula evaluation and would drop groups from the result. The response decisions note reports the effective bounds.
  435. - **Key-not-found errors**: a filter referencing a key absent from this workspace's metrics metadata fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  436. #### `signoz_get_top_metrics`
  437. Return top 100 metrics ranked by ingested sample volume with pre-computed percentages. Use this to identify which metrics are driving the most ingestion volume and cost. Wraps `POST /api/v2/metrics/treemap`. Response fields: `metricName`, `percentage` (share of total sample volume), `totalValue` (absolute sample count).
  438. - **Parameters**:
  439. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '1h', '24h', '3d', '7d', '30d'; default: '7d'; ignored when both `start` and `end` are provided). Start with 7d; if the query times out, retry with 3d, then 24h
  440. - `start`/`end` (optional) - Unix ms timestamps. When both are provided, they override `timeRange`
  441. - **Completeness note**: returns a fixed top 100 by ingested sample volume; the response appends a note flagging whether the list was truncated at that cap (`hasMore`)
  442. #### `signoz_check_metric_usage`
  443. Given a list of metric names, return which dashboards and alerts reference each one. Wraps `/api/v3/metrics/dashboards?metricName=...` and `/api/v2/metrics/alerts?metricName=...` per metric.
  444. - **Parameters**:
  445. - `metricNames` (required) - Array of metric name strings to check (max 50 per call). Example: `["system.disk.io", "k8s.node.condition"]`. For larger lists, split into batches of 50 and merge results.
  446. - **Response**: per metric, `dashboards` (list of dashboard names that reference the metric), `alerts` (list of alert names that reference the metric), `error` (non-empty when the lookup failed; do not treat the metric as unused in that case)
  447. - **Limits**: Maximum 50 metrics per call; 30-second overall timeout (partial results returned on expiry)
  448. #### `signoz_check_metric_cardinality`
  449. Return label/attribute keys for one metric with cardinality counts and sample values, sorted highest first. Samples help distinguish unbounded values such as UUIDs from bounded dimensions such as status codes. This tool does not show whether the metric is used; call `signoz_check_metric_usage` before recommending a drop.
  450. - **Parameters**:
  451. - `metricName` (required) - Metric name to inspect. Example: `k8s.container.memory_limit`
  452. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '24h', '3d', '7d'; default: '7d'; ignored when both `start` and `end` are provided)
  453. - `start`/`end` (optional) - Unix ms timestamps. When both are provided, they override `timeRange`
  454. #### `signoz_list_alerts`
  455. Lists currently firing/silenced/inhibited alert *instances* from Alertmanager, **not** rule definitions. Use `signoz_list_alert_rules` for configured rules, `signoz_get_alert` with an `id` for one full rule definition, or `signoz_get_alert_history` for the state timeline.
  456. - **Parameters**:
  457. - `limit` (optional) - Maximum number of alerts per page (default: 50)
  458. - `offset` (optional) - Number of results to skip for pagination (default: 0)
  459. - `active` / `silenced` / `inhibited` (optional) - Tri-state filters. Boolean (or the strings `"true"`/`"false"`). Omit to defer to the backend default (all states included). An invalid value is rejected rather than silently dropped
  460. - `filter` (optional) - Comma-separated alert-label comparisons using `=`, `!=`, `=~` (regex), or `!~` (negative regex), e.g. `alertname="HighCPU",severity="critical"`
  461. - `receiver` (optional) - Regex to filter alerts by receiver name
  462. #### `signoz_list_alert_rules`
  463. Lists configured alert-rule summaries from `GET /api/v3/rules`, including inactive/OK and disabled rules. SigNoz applies `filter` and `states` before paging, so finding rules by name, label, severity, or state doesn't need a walk through every page. Use `signoz_get_alert` for one full definition; use `signoz_list_alerts` for current Alertmanager instances.
  464. - **Parameters**:
  465. - `filter` (optional) - Filter expression, at most 1024 characters. Keys: `name` (the rule title), `severity`, `alert_type`, `rule_type`, `created_by`, `updated_by`, and `created_at` or `updated_at` with RFC 3339 times. Any other key is a rule label, matched case-sensitively (`cluster = 'prod'`); `labels.<key>` matches only the label. A bare word matches the name, description, or labels, ignoring case. Example: `name CONTAINS 'High Response Time' AND severity IN ('critical', 'error')`
  466. - `states` (optional) - Only rules in these states: `firing`, `pending`, `recovering`, `inactive`, `nodata`, or `disabled`, as an array or a comma-separated string
  467. - `sort` (optional) - Field to sort by: `updated_at` (default), `created_at`, `name`, `state`, or `severity`
  468. - `order` (optional) - `asc` or `desc` (default)
  469. - `limit` (optional) - Maximum number of rules to return per page (default: 50, max: 1000; higher values are clamped)
  470. - `offset` (optional) - Number of rules to skip for pagination (default: 0)
  471. #### `signoz_get_alert`
  472. Gets one alert rule's full definition (`GET /api/v2/rules/{id}`). Use `signoz_list_alert_rules` to discover IDs. Before `signoz_update_alert`, call this only when a complete current definition is not already available for the prepared operation; reuse a still-current result and preserve unchanged fields.
  473. - **Parameters**: `id` (required) - Alert rule ID (UUIDv7 on v2-capable servers).
  474. - **Note**: Response shape depends on the SigNoz server version. Post-#10997 servers return the canonical `Rule` type with `createdAt/updatedAt/createdBy/updatedBy`; older servers return `GettableRule` with `createAt/updateAt/createBy/updateBy` (no 'd').
  475. #### `signoz_list_dashboards`
  476. Lists paginated tenant-dashboard summaries (name, UUID, description, tags, timestamps). Use `signoz_get_dashboard` for panel and query definitions, and page by raising `offset` by `limit` until you have covered `total` before concluding a dashboard is absent.
  477. - **Parameters:**
  478. - `limit` (default 50), `offset` (default 0) – offset-based pagination
  479. - `filter` (optional) – server-side filter DSL over dashboard metadata (name, description, tags, creator, timestamps, locked state)
  480. - `sort` (optional) – `updated_at` (default), `created_at`, or `name`
  481. - `order` (optional) – `asc` or `desc` (default `desc`)
  482. Only `source: user` dashboards can be updated, patched, or deleted. `source` is
  483. not a server-side list-filter column; filter returned rows locally across pages
  484. when needed.
  485. The `filter` DSL is a boolean expression of `key operator value` terms and bare free-text words joined with `AND`/`OR`/`NOT` and parentheses (e.g. `name CONTAINS 'overview' AND locked = true`). Read [`signoz://dashboard/list-filter-guide`](#mcp-resources) for the full grammar, the filterable keys with their operators, value formats, and worked examples; the list response also echoes the authoritative reserved-key set in `reservedKeywords`.
  486. #### `signoz_get_dashboard`
  487. Gets one known tenant dashboard's complete layout, variables, panels, and queries. Use `signoz_list_dashboards` to discover the UUID.
  488. - **Parameters**: `id` (required) - Dashboard UUID
  489. #### `signoz_create_dashboard`
  490. Creates a custom multi-panel dashboard. Use `signoz_import_dashboard` when a curated template fits, or `signoz_create_view` to save one Explorer query. Read `signoz://dashboard/instructions`, `signoz://dashboard/widgets-instructions`, and `signoz://dashboard/widgets-examples` before composing the payload.
  491. - **Parameters:**
  492. - `schemaVersion` (required) – Must be `"v6"`
  493. - `name` (DNS-1123 label) or `generateName: true` to derive it from `spec.display.name`
  494. - `tags` (required) – Array of key/value tags (may be empty)
  495. - `spec` (required) – Perses spec: `display`, `variables` (array), `panels` (map keyed by panel id), `layouts` (array)
  496. Static Markdown panels use `signoz/TextPanel` with `queries: []`, plus
  497. `plugin.spec.mode: "markdown"`, `text`, `presentation`, and `headerOptions`.
  498. Include the panel's layout reference. Query-bearing panels still require one
  499. query; Text panels do not need a query dry run. Widget examples and patch
  500. instructions include both kinds. Area charts use `signoz/AreaChartPanel` with
  501. one `time_series` query; `visualization.stack` (`none`, `normal`, or
  502. `percent`) stacks grouped series, and `chartAppearance.fillMode` is `solid` or
  503. `gradient`. Dashboard inputs use canonical `id`; the
  504. legacy `uuid` input is rejected on the changed dashboard tools.
  505. #### `signoz_import_dashboard`
  506. Creates a dashboard from a curated template hosted in the [SigNoz/dashboards](https://github.com/SigNoz/dashboards) repo (`main` branch). The server fetches the template JSON and creates the dashboard in one call.
  507. When the relative template path is unknown, call `signoz_list_dashboard_templates` first. Pass its `path`, not a URL or absolute path.
  508. - **Parameters:**
  509. - `path` (required) – Template path within the SigNoz/dashboards repo, e.g. `hostmetrics/hostmetrics.json`
  510. #### `signoz_list_dashboard_templates`
  511. Searches the bundled catalog of curated SigNoz dashboard templates and returns the matches as `{"templates": [...], "total": N}`, where each entry has id, title, path, description, category, and keywords. It does not list dashboards already created in the tenant; use `signoz_list_dashboards` for those.
  512. - **Parameters:**
  513. - `searchText` (optional) – Words matched case-insensitively against each template's id, title, path, category, description, and keywords; a template must match every word, e.g. `postgres` or `kubernetes pod`. At most 2048 characters. Omit to return the full catalog.
  514. #### `signoz_update_dashboard`
  515. Fully replaces an existing dashboard. Fetch it with `signoz_get_dashboard`, take the `data` object out of that response, merge only the requested changes into it, and send that object's fields at the top level, preserving every other field. The `{status, data}` response envelope is not accepted as input. Use `signoz_update_view` for a saved Explorer query.
  516. - **Parameters:**
  517. - `id` (required) – Dashboard id (the legacy `uuid` key is also accepted)
  518. - `schemaVersion`, `name`, `tags`, `spec` – the complete post-update state (see the tool's JSON Schema)
  519. #### `signoz_patch_dashboard`
  520. Applies an RFC 6902 JSON Patch to a dashboard: a partial update without re-sending the entire dashboard. Prefer this over `signoz_update_dashboard` for targeted edits (rename, add/edit one panel or query, tweak a variable). Read `signoz://dashboard/patch-instructions` for worked recipes and exact paths; notably, adding a panel needs two ops (the panel plus its grid item) or it won't render.
  521. - **Parameters:**
  522. - `id` (required) – Dashboard id (the legacy `uuid` key is also accepted)
  523. - `patch` (required) – Array of `{op, path, value}` operations; paths are JSON Pointers into the dashboard's postable shape, e.g. `/spec/display/name`, `/spec/panels/<panelId>`, `/spec/layouts/0/spec/items/-`, `/tags/-`
  524. #### `signoz_list_services`
  525. Lists APM services with trace activity in a time range, sorted by service name and paginated. Absence means no trace activity in that window, not that the same `service.name` never appears in logs; use `signoz_get_field_values` with `signal="logs"` for log values.
  526. - **Parameters**:
  527. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '7d'; defaults to last 6 hours; ignored when both `start` and `end` are provided)
  528. - `start` (optional) - Start time in unix milliseconds (defaults to 6 hours ago).
  529. - `end` (optional) - End time in unix milliseconds (defaults to now)
  530. - `limit` (optional) - Maximum services per page (default: 50, max: 1000; higher values are clamped)
  531. - `offset` (optional) - Number of results to skip for pagination (default: 0)
  532. #### `signoz_get_service_top_operations`
  533. Gets the built-in operation table for one traced service, ranked by p99 latency with each operation's p50, p95, p99, call count, and error count. Use `signoz_aggregate_traces` for custom aggregation, grouping, time series, cross-service comparison, or arbitrary trace filters.
  534. - **Parameters**:
  535. - `service` (required) - Exact traced service name, typically from `signoz_list_services`
  536. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '7d'; defaults to last 6 hours; ignored when both `start` and `end` are provided)
  537. - `start` (optional) - Start time in unix milliseconds (defaults to 6 hours ago).
  538. - `end` (optional) - End time in unix milliseconds (defaults to now)
  539. - `tags` (optional) - JSON-encoded `TagQueryParam` array passed as a string, for example `[{"key":"http.method","tagType":"SpanAttribute","operator":"In","stringValues":["GET"]}]`; omit for no tag filter
  540. #### `signoz_get_alert_history`
  541. Gets one configured rule's firing or state-transition history. Defaults to the last 6 hours. Use `state` and `filter` to narrow results. For the next page, pass `data.nextCursor` as `cursor` and repeat the original filters, time range, and order.
  542. The response is `{ "status": "success", "data": { "items": [...], "total": <n>, "nextCursor": "<opaque>" } }`; `nextCursor` is omitted on the final page.
  543. - **Parameters**:
  544. - `id` (required) - Alert rule ID from `signoz_list_alert_rules`
  545. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '7d'; defaults to last 6 hours; ignored when both `start` and `end` are provided)
  546. - `start` (optional) - Start timestamp in unix milliseconds (defaults to 6 hours ago).
  547. - `end` (optional) - End timestamp in unix milliseconds (defaults to now)
  548. - `state` (optional) - Filter by alert state: `inactive`, `pending`, `recovering`, `firing`, `nodata`, or `disabled` (omit for all transitions)
  549. - `filter` (optional) - SigNoz query-builder expression over timeline labels. Combine conditions with `AND`, `OR`, and parentheses; quote strings with single quotes. Example: `severity = 'critical' AND (team = 'payments' OR service.name = 'checkout')`. To discover keys, first call without a filter and inspect `data.items[].labels[].key.name`. The backend-shaped `filterExpression` alias remains accepted for compatibility, but `filter` is canonical.
  550. - `cursor` (optional) - Opaque continuation cursor. Repeat the original time range, state, filter, and order when fetching the next page. Omit `cursor` for the first page.
  551. - `limit` (optional) - Rows per page. Default: 20; max: 10000 (higher values are clamped).
  552. - `order` (optional) - Sort order. Enum: `asc`, `desc` (default: 'asc')
  553. - **Legacy `offset`**: no longer supported; use the returned cursor instead.
  554. - **Completeness note**: the response appends a note reporting `hasMore` from `data.nextCursor` and names the cursor for the next page.
  555. #### `signoz_list_views`
  556. List saved Explorer views or discover a view UUID for one Logs, Traces, Metrics, or Cost Meter page. A view stores one reusable Explorer query spec; it is not a multi-panel dashboard. Apply name filters before pagination and follow `pagination.nextOffset` while `pagination.hasMore` is true.
  557. - **Parameters**:
  558. - `source` (optional) - Explorer to filter by, for example `traces`, `logs`, `metrics`, or `meter` (Cost Meter, a distinct Explorer page); SigNoz validates the value. Omit to list views from every Explorer
  559. - `name` (optional) - Partial-match filter on view name (server-side)
  560. - `limit` (optional) - Page size (default: 50, max: 1000; higher values are clamped)
  561. - `offset` (optional) - Number of results to skip (default: 0)
  562. #### `signoz_get_view`
  563. Get one saved Explorer view's complete definition by UUID. Call this before `signoz_update_view`, which fully replaces the view.
  564. - **Parameters**: `id` (required) - Saved view UUID
  565. #### `signoz_search_docs`
  566. Search official SigNoz documentation and return ranked pages with URLs and snippets for product, setup, instrumentation, configuration, API, deployment, or troubleshooting questions. Send 2 to 6 keywords for one topic and keep product and technology names as the user wrote them; split multi-intent questions into separate calls. If the top result is off-topic, retry with fewer or different terms. Do not use for live tenant data; use signoz_fetch_doc for the full content of a selected result or exact docs URL.
  567. - **Parameters**:
  568. - `searchText` (required) - 2 to 6 keywords for one topic, for example "Kubernetes pod logs". Keep product and technology names as the user wrote them.
  569. - `limit` (optional) - Maximum results to return as a string (default: 10, max: 25; a numeric value is also accepted). The 25 ceiling is deliberate: each result hydrates document text out of the in-process docs index, so a larger limit inflates this server's resident memory.
  570. - `section_slug` (optional) - Exact top-level docs section filter, such as `setup`, `logs-management`, `apm-distributed-tracing`, `metrics`, `alerts`, `dashboards`, `signoz-apis`, `querying`, or `collection-agents`. Reuse the `section_slug` from an earlier result when narrowing; an unknown slug returns zero results
  571. - `searchContext` - User's original question
  572. Docs search telemetry counts executed searches in `signoz_docs_searches_total` with
  573. `outcome=ok|error`. Only successful searches have `result_count_bucket` (`0`, `1-4`,
  574. `5-9`, or `10+`). `signoz_docs_search_top_score` records the top hit's raw Bleve score
  575. only for successful non-empty searches. Scores are uncalibrated and depend on query
  576. terms, boosts, and analyzer settings; they are not relevance probabilities or thresholds.
  577. Search spans record `mcp.docs.search_text` (the executed query, truncated to 256 Unicode
  578. runes), `mcp.docs.section_slug`, and `mcp.docs.result_count`. Successful non-empty searches
  579. also record `mcp.docs.top_score`. These span attributes distinguish the client's keyword
  580. query from the user's original request in `mcp.search_context`; query text is not a metric
  581. attribute. If the query is invalid Bleve query-string syntax, search drops that clause,
  582. continues with text matching, and records `mcp.docs.query_string_dropped=true`. Empty or
  583. whitespace-only queries remain validation errors.
  584. #### `signoz_fetch_doc`
  585. Fetch one known official SigNoz docs page's full Markdown or a requested heading. Use `signoz_search_docs` to discover a page first; accepted inputs are `https://signoz.io/docs/...` URLs or `/docs/...` paths.
  586. - **Parameters**:
  587. - `url` (required) - Docs page URL or path. A `signoz://` resource URI is rejected with a hint to read it with `resources/read` instead
  588. - `heading` (optional) - Heading anchor ID or heading text
  589. - `searchContext` - User's original question
  590. #### `signoz_create_view`
  591. Save one reusable Explorer query spec. Use `signoz_create_dashboard` for a multi-panel dashboard. Cost Meter views use `source="meter"` with `signal="metrics"` and builder-spec `source="meter"`.
  592. - **Parameters** (v2 typed shape):
  593. - `name` (optional) - View name (DNS-1123 label). Required unless `generateName` is true
  594. - `generateName` (optional) - When true, the server generates `name` from `spec.displayName` and `name` must be empty
  595. - `source` (required) - Which Explorer this view belongs to, for example `traces`, `logs`, `metrics`, or `meter`; SigNoz validates the value
  596. - `spec` (required) - Typed view content: `displayName`, `panelType`, `requestType`, `queries`, `selectedFields`, `display`
  597. - `schemaVersion` (optional) - Always `v2`; defaults when omitted
  598. - **Required**: Read both MCP resources `signoz://view/instructions` and `signoz://view/examples` before composing any payload.
  599. #### `signoz_update_view`
  600. Fully replace an existing saved Explorer view. Fetch it with `signoz_get_view`, modify its returned `data` object, preserve every unrequested field, and pass that full object as `view`. Upstream keeps `name` immutable on update; the display label lives in `spec.displayName`.
  601. - **Parameters**:
  602. - `id` (required) - UUID of the view to replace
  603. - `view` (required) - Full `source`/`spec` pair (required); drop `name` and server-populated fields
  604. - **Migration**: the retired flat shape (`source` and `spec` beside `id`) returns a coded `VALIDATION_FAILED` error naming the `view` wrapper; pass `{"id": "<uuid>", "view": {"source": ..., "spec": ...}}`.
  605. - **Resource rule**: Read `signoz://view/instructions` and `signoz://view/examples` when changing `source` or `spec`. Skip them for a pass-through of the fetched body. Call `signoz_get_view` first; partial bodies wipe unspecified fields.
  606. #### `signoz_delete_view`
  607. Permanently delete a confirmed saved Explorer view by UUID. Use `signoz_list_views` to discover the ID; use `signoz_delete_dashboard` for a dashboard.
  608. - **Parameters**: `id` (required) - Saved view UUID
  609. #### `signoz_aggregate_logs`
  610. Return aggregate statistics over logs (counts, rates, averages, percentiles, or grouped/top-N breakdowns) rather than individual records. Use `signoz_search_logs` for log rows and message inspection.
  611. - **Parameters**:
  612. - `aggregations` (required) - Aggregation expressions as the Query Builder writes them: `count()`, `count_distinct(user_id)`, `avg(duration)`, `p99(duration)`, `rate()`, or a conditional such as `countIf(severity_text = 'ERROR')`. One expression or an array (e.g. `["count()", "p95(duration)", "p99(duration)"]`); results come back as `__result_0`, `__result_1`, ... in that order. SigNoz validates the expressions. The former `aggregation` and `aggregateOn` inputs return a coded error naming this replacement
  613. - `groupBy` (optional) - Fields to group by, as an array or a comma-separated string (e.g. `["service.name", "severity_text"]`). An array of objects is rejected with a coded error naming both forms. Group by keys `signoz_get_field_keys` returns; an unknown key can come back as one empty group. A body field (`body.<path>`) can be grouped only when `signoz_get_field_keys` (`signal="logs"`, `fieldContext="body"`) lists it, which happens only on workspaces that store JSON log bodies; otherwise SigNoz rejects it with `can be filtered but not selected or grouped` or `field not found`, so filter on it instead
  614. - `having` (optional) - Condition on the aggregation results, applied after grouping (e.g. `count() > 100`). SigNoz validates it
  615. - `filter` (optional) - Filter expression using SigNoz search syntax. Pass the expression text, not `{"expression": ...}`, which is rejected with a coded error. Combine conditions with AND, OR, and parentheses. An unknown key may not fail: SigNoz can match guessed attribute and body spellings and return a `key ... not found in metadata` warning with no rows, so read that warning as an absent key. Ambiguous keys default to resource context. Log keys are workspace-specific; even `service.name` is only present when the log pipeline sets it. See `signoz://logs/query-builder-guide` There is no `key:value`, `STARTS WITH`, or `IS NULL`; use `LIKE 'prefix%'` and `EXISTS` / `NOT EXISTS`.
  616. - `service` (optional) - Shortcut filter for service name (adds `service.name = '<value>'`; when the workspace's logs lack that attribute, the call usually returns no rows with a `key service.name not found in metadata` warning instead of failing)
  617. - `severity` (optional) - `severity_text`, matched in any case and as a prefix, so `WARN` also matches `warning` and `Warning`; pass the short form (`ERR`, `WARN`, `INFO`). DEBUG, INFO, WARN, ERROR, and FATAL are common examples, not an exhaustive enum. Discover values with `signoz_get_field_values(signal="logs", name="severity_text", fieldContext="log")`
  618. - `orderBy` (optional) - Order expression and direction. The expression must be one of the call's aggregations, written exactly as in `aggregations`, or a `groupBy` key (e.g. `'count_distinct(trace_id) desc'` when aggregating `count_distinct(trace_id)`); default: the first aggregation, descending
  619. - `limit` (optional) - Maximum number of groups to return (default: 100, max: 10000; higher values are clamped to bound server memory)
  620. - `functions` (optional) - Post-query transforms applied in order to each series, as an array of `{name, args}` objects (or a JSON-encoded string); each arg is `{"value": <number>}`. `timeShift` reads the window that many seconds earlier and returns its points on the current window's timestamps; `604800` gives the same window last week. To compare two windows, call once without `timeShift` and once with it. For `A - B` or `A / B` in one result, use `signoz_execute_builder_query` with two builder queries, the second with `timeShift`, and a `builder_formula`. `cutOffMin` and `cutOffMax` drop points below or above a threshold; `clampMin` and `clampMax` set them to it. `runningDiff` gives the change from the point before; `cumulativeSum` gives a running total. `ewma3`, `ewma5`, `ewma7`, `median3`, `median5`, and `median7` smooth a series; `fillZero` adds 0 at steps with no data; `absolute`, `log2`, and `log10` transform each value. SigNoz validates names and args. On a `scalar` request SigNoz applies only `timeShift`, and the response notes any other function it skipped
  621. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '24h', '7d'; default: '1h'; ignored when both `start` and `end` are provided)
  622. - `start` / `end` (optional) - Start/end time in unix milliseconds. When both are provided, they override `timeRange`.
  623. - `requestType` (optional) - `scalar` (default; one aggregate value over the whole range) or `time_series` (one value per time bucket). Unknown values are rejected.
  624. - `stepInterval` (optional) - Time bucket size in seconds for `time_series` mode. Accepts a number or numeric string (backend auto-selects when omitted)
  625. - **Time-series ranking note**: the limit selects top groups over the whole requested window, not independently per bucket. Narrow the window or adjust the limit when a short-lived series could otherwise be hidden.
  626. - **Key-not-found errors**: a filter referencing a key absent from this workspace's logs metadata fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  627. #### `signoz_search_logs`
  628. Return individual paginated log records matching text, service, severity, or field filters. Use `signoz_aggregate_logs` for counts, trends, or grouped breakdowns.
  629. Calls using only `searchText`, `service`, `severity`, time, or pagination parameters need no guide read. Read `signoz://logs/query-builder-guide` only before composing `filter` with unfamiliar workspace fields.
  630. - **Parameters**:
  631. - `filter` (optional) - Filter expression using SigNoz search syntax. Pass the expression text, not `{"expression": ...}`, which is rejected with a coded error. Combine conditions with AND, OR, and parentheses (e.g., "(severity_text = 'ERROR' OR body CONTAINS 'panic') AND service.name = 'payment-svc'"). Log keys are workspace-specific; even `service.name` is only present when the log pipeline sets it. See `signoz://logs/query-builder-guide` There is no `key:value`, `STARTS WITH`, or `IS NULL`; use `LIKE 'prefix%'` and `EXISTS` / `NOT EXISTS`.
  632. - `service` (optional) - Service name to filter by (adds `service.name = '<value>'`; when the workspace's logs lack that attribute, the call usually returns no rows with a `key service.name not found in metadata` warning instead of failing)
  633. - `severity` (optional) - `severity_text`, matched in any case and as a prefix, so `WARN` also matches `warning` and `Warning`; pass the short form (`ERR`, `WARN`, `INFO`). DEBUG, INFO, WARN, ERROR, and FATAL are common examples, not an exhaustive enum. Discover values with `signoz_get_field_values(signal="logs", name="severity_text", fieldContext="log")`
  634. - `searchText` (optional) - Literal text to find, escaped automatically; combines with `filter` using AND
  635. - `searchScope` (optional) - Where `searchText` matches: `body` (default, `body CONTAINS`), `attribute` or `resource` (keys and values), or `all` (unscoped `search()`, slow on wide time ranges). Ignored, with a note in the result, when `searchText` is empty; an unknown scope is rejected
  636. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '24h', '7d'; default: '1h'; ignored when both `start` and `end` are provided)
  637. - `start` / `end` (optional) - Start/end time in unix milliseconds. When both are provided, they override `timeRange`.
  638. - `limit` (optional) - Maximum number of logs to return (default: 20, max: 10000; higher values are clamped; paginate with `offset`)
  639. - `offset` (optional) - Offset for pagination (default: 0)
  640. - `orderBy` (optional) - Row order as `<field> <direction>` (e.g. `timestamp asc`, `severity_number desc`; default: `timestamp desc`)
  641. - `selectFields` (optional) - Fields to return on each row instead of the complete record; SigNoz always adds `timestamp` and `id`. An array of names or a comma-separated string, at most 50. Names can be log columns (`body`, `severity_text`), resource attributes (`service.name`, `k8s.pod.name`), or log attributes (`http.route`); a body field (`body.<path>`) can be selected only when `signoz_get_field_keys` (`fieldContext="body"`) lists it, and is otherwise rejected with `can be filtered but not selected or grouped` or `field not found`, so filter on it instead; a `resource.`, `attribute.`, `log.`, or `body.` prefix picks the context. Discover names with `signoz_get_field_keys` (`signal="logs"`)
  642. - **Rows**: with no `selectFields`, each row is the complete log record: every log column plus the `attributes_string`, `attributes_number`, `attributes_bool`, `resources_string`, and `scope_string` maps. With `selectFields`, each named field is a flat row key
  643. - **Ordering**: generated raw log queries use `timestamp desc`, then `id desc`, so offset pagination is deterministic when multiple rows share a timestamp. When `orderBy` names `timestamp`, `id` follows in the same direction.
  644. - **Completeness note**: the response appends a note reporting `hasMore` (inferred from `returnedRows == limit`) and the `nextOffset` to fetch, so a truncated page is never mistaken for the full result set
  645. - **Key-not-found errors**: a filter referencing a key absent from this workspace's logs metadata fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  646. Use `filter: "search('timeout')"` when the field containing a term is unknown.
  647. Use `search('checkout', body)` to scope it, or combine the function with field
  648. predicates using AND/OR/NOT. Scopes are `body`, `attribute`, `resource`, and
  649. `log`. Once the field is known, prefer a field predicate. `searchText` with
  650. `searchScope` builds these predicates for you. Escape backslashes and apostrophes
  651. inside expression literals; explicit filters are passed through, not rewritten.
  652. The same expressions work in log aggregations and saved-query specs.
  653. #### `signoz_get_field_keys`
  654. Discover field names available for filtering or grouping metrics, traces, or logs, including AI trace fields with `queryType: builder_ai_query`. This returns keys, not observed values; use `signoz_get_field_values` after selecting a key. Keys come from all retained metadata; the tool takes no time range. A `data.complete` of `false` means SigNoz cut the key list, and the result then carries a note with next steps: narrow with `searchText` or `fieldContext`, or raise `limit`.
  655. - **Parameters**:
  656. - `signal` (required) - Signal type. Enum: `metrics`, `traces`, `logs`
  657. - `searchText` (optional) - Filter field keys by name substring
  658. - `metricName` (optional) - Filter by metric name (relevant for metrics signal)
  659. - `fieldContext` (optional) - Restrict to a field context. Enum: `resource`, `attribute`, `scope`, `log`/`span`/`metric` (intrinsic columns), `trace` (fields of a whole trace rather than one span, such as values computed over all of its spans; written with the `trace.` prefix), `body` (JSON log body). Use `attribute`, not the legacy Query Builder context `tag`, which SigNoz ignores here.
  660. - `fieldDataType` (optional) - Restrict to a data type: `string`, `bool`, `int64`, `float64`, `number`. An array form like `[]string` is treated as its element type.
  661. - `source` (optional) - For metrics, use `meter` for Cost Meter fields; omit for the default metrics store
  662. - `queryType` (optional) - `builder_query` (default) lists the fields of `signal`. Set `builder_ai_query` for AI observability queries; it also lists the trace-level fields, such as `trace.estimated_total_cost`, and `gen_ai.*` attributes.
  663. - `limit` (optional) - Maximum number of keys to return for each signal, as an integer or string. Omit it for the SigNoz default. Intrinsic and materialized fields come on top of the limit, so the list can be longer.
  664. #### `signoz_get_field_values`
  665. Get observed values for a known field key. Use `signoz_get_field_keys` when the key is unknown, and match `signal` and `fieldContext` to the query that will use the value. Values come from all retained metadata; the tool takes no time range. A `data.complete` of `false` means SigNoz cut the value list, and the result then carries a note with next steps: narrow with `searchText`, or raise `limit`.
  666. - **Parameters**:
  667. - `signal` (required) - Signal type. Enum: `metrics`, `traces`, `logs`
  668. - `name` (required) - Field key name to get values for (e.g., `service.name`, `http.method`)
  669. - `searchText` (optional) - Filter values by substring
  670. - `metricName` (optional) - Filter by metric name (relevant for metrics signal)
  671. - `fieldContext` (optional) - Restrict the lookup to a field context (`resource`, `attribute`, `scope`, `log`/`span`/`metric`, `body`) when the same key name exists in more than one. Use `attribute`, not the legacy Query Builder context `tag`; SigNoz returns no values for `tag`.
  672. - `source` (optional) - For metrics, use `meter` for Cost Meter values; omit for the default metrics store
  673. - `limit` (optional) - Maximum number of values to return, as an integer or string. Omit it for the SigNoz default.
  674. #### `signoz_search_traces`
  675. Return individual paginated span rows matching service, operation, error, duration, or field filters, and use them to discover trace IDs. With `requestType: trace` it returns one row per trace instead. With `queryType: builder_ai_query` it searches AI traces, also filters on per-trace cost, token, and call counts, and its trace rows carry those per-trace values. Use `signoz_aggregate_traces` for statistics or `signoz_get_trace_details` for one known trace.
  676. - **Parameters**:
  677. - `filter` (optional) - Filter expression using SigNoz search syntax. Pass the expression text, not `{"expression": ...}`, which is rejected with a coded error. Combine conditions with AND, OR, and parentheses (e.g., "service.name = 'payment-svc' AND (has_error = true OR attribute.http.response.status_code >= 500)"). The former `query` alias is rejected with a coded error that names `filter`. Every condition needs a key and an operator: there is no full-text search, `key:value`, `STARTS WITH`, or `IS NULL`; use `LIKE 'prefix%'` and `EXISTS` / `NOT EXISTS`. `isRoot = true` and `isEntryPoint = true` select root and service entry spans. See `signoz://traces/query-builder-guide`
  678. - `service` (optional) - Service name to filter by
  679. - `operation` (optional) - Operation/span name to filter by
  680. - `error` (optional) - Filter by error status. Boolean (or the strings `"true"`/`"false"`). An invalid value is rejected rather than silently dropped
  681. - `minDuration` / `maxDuration` (optional) - Min/max span duration as a duration such as `'500ms'` or `'2s'` (units `ns`, `us`, `ms`, `s`, `m`, `h`). A bare number, string or JSON, is nanoseconds. SigNoz rejects any other value
  682. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '24h', '7d'; default: '1h'; ignored when both `start` and `end` are provided)
  683. - `start` / `end` (optional) - Start/end time in unix milliseconds. When both are provided, they override `timeRange`.
  684. - `limit` (optional) - Maximum rows to return (default: 20, max: 10000; higher values are clamped; paginate with `offset`)
  685. - `offset` (optional) - Number of rows to skip (default: 0)
  686. - `selectFields` (optional) - Fields to return on each span row instead of the complete record; SigNoz always adds `timestamp`, `trace_id`, and `span_id`. An array of field names or a comma-separated string, at most 50. Names can be span columns (`name`, `duration_nano`), resource attributes (`service.name`, `k8s.pod.name`), or span attributes (`http.route`); a `resource.`, `attribute.`, or `span.` prefix picks the context. Discover names with `signoz_get_field_keys` (`signal="traces"`)
  687. - **Rows**: with no `selectFields`, each span row is the span's complete record: the span fields plus `attributes` and `resource` maps, `events`, and `links`, the same shape `signoz_get_trace_details` returns. With `selectFields`, each named field is a flat row key
  688. - `orderBy` (optional) - Row order as `'<expression> <direction>'` (e.g. `'duration_nano desc'`; direction defaults to `desc`). Span rows order by span fields and default to `timestamp desc`. `builder_ai_query` trace rows order by a trace-level field or `trace.last_activity_time`, e.g. `'trace.estimated_total_cost desc'`, and default to latest activity first. `builder_query` trace rows always come back slowest first; SigNoz ignores `orderBy` for them
  689. - `queryType` (optional) - `builder_query` (default) searches all traces. Set `builder_ai_query` for AI observability queries: it searches AI traces (traces with an LLM, tool, or agent span), its span rows are only those spans, and `filter` also accepts the trace-level fields `trace.llm_call_count`, `trace.tool_call_count`, `trace.distinct_tool_count`, `trace.input_tokens`, `trace.output_tokens`, `trace.total_tokens`, `trace.estimated_total_cost`, and `trace.max_llm_duration_nano`, e.g. `trace.tool_call_count > 10`. An unknown value runs as `builder_query` with an input validation notice
  690. - `requestType` (optional) - `raw` (default; one row per span) or `trace` (one row per trace). Span-level filters, including `operation`, `error`, `minDuration`, and `maxDuration`, keep the traces with at least one matching span, and `selectFields` does not apply to trace rows. `builder_query` trace rows carry `trace_id`, the root span `name`, `service.name`, `duration_nano`, and `span_count` (the spans matching the filter). `builder_ai_query` trace rows carry the trace-level fields without the `trace.` prefix (such as `llm_call_count`), plus `root_span_name`, `span_count`, `trace_duration_nano`, `error_count`, and the input and output message JSON. An unknown value runs as `raw` with an input validation notice
  691. - **Completeness note**: the response appends a note reporting `hasMore` (inferred from `returnedRows == limit`) and the `nextOffset` to fetch, so a truncated page is never mistaken for the full result set
  692. - **Output note**: raw result row keys follow canonical Query Builder field names (for example `trace_id`, `span_id`, `duration_nano`, `has_error`). Legacy caller-provided filters such as `hasError` still pass through to the backend alias layer, but new response parsers should read the canonical snake_case keys.
  693. - **Key-not-found errors**: a filter referencing a key absent from this workspace's traces metadata fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  694. #### `signoz_aggregate_traces`
  695. Return custom aggregate statistics over spans (counts, rates, latency percentiles, grouped/top-N breakdowns, or time series) rather than individual rows or a full trace hierarchy. For one row per trace, such as the most expensive AI traces, use `signoz_search_traces` with `requestType: trace`. For one traced service's built-in operation table ranked by p99, use `signoz_get_service_top_operations`. Read `signoz://traces/query-builder-guide` before calling this tool. For AI cost, token, or call-count statistics per trace, set `queryType: builder_ai_query` (see `signoz://ai/query-builder-guide`).
  696. - **Parameters**:
  697. - `aggregations` (required) - Aggregation expressions as the Query Builder writes them: `count()`, `count_distinct(name)`, `avg(duration_nano)`, `p99(duration_nano)`, `rate()`, or a conditional such as `countIf(has_error = true)`; `duration_nano` is span latency in nanoseconds. One expression or an array (e.g. `["count()", "p95(duration_nano)", "p99(duration_nano)"]`); results come back as `__result_0`, `__result_1`, ... in that order. SigNoz validates the expressions. The former `aggregation` and `aggregateOn` inputs return a coded error naming this replacement
  698. - `groupBy` (optional) - Fields to group by, as an array or a comma-separated string (e.g. `["service.name", "name"]`). An array of objects is rejected with a coded error naming both forms. For values over time use `requestType: time_series`; grouping by `timestamp` fails
  699. - `having` (optional) - Condition on the aggregation results, applied after grouping (e.g. `p99(duration_nano) > 500000000`). SigNoz validates it
  700. - `filter` (optional) - Filter expression using SigNoz search syntax. Pass the expression text, not `{"expression": ...}`, which is rejected with a coded error. Combine conditions with AND, OR, and parentheses. An unknown key may not fail: SigNoz can match a guessed attribute and return a `key ... not found in metadata` warning with no rows, so read that warning as an absent key. Ambiguous keys default to resource context. Every condition needs a key and an operator: there is no full-text search, `key:value`, `STARTS WITH`, or `IS NULL`; use `LIKE 'prefix%'` and `EXISTS` / `NOT EXISTS`. `isRoot = true` and `isEntryPoint = true` select root and service entry spans. See `signoz://traces/query-builder-guide`
  701. - `service` (optional) - Shortcut filter for service name
  702. - `operation` (optional) - Shortcut filter for span/operation name
  703. - `error` (optional) - Shortcut filter for error spans. Boolean (or the strings `"true"`/`"false"`). An invalid value is rejected rather than silently dropped
  704. - `minDuration` / `maxDuration` (optional) - Min/max span duration as a duration such as `'500ms'` or `'2s'` (units `ns`, `us`, `ms`, `s`, `m`, `h`). A bare number, string or JSON, is nanoseconds. SigNoz rejects any other value
  705. - `orderBy` (optional) - Order expression and direction. The expression must be one of the call's aggregations, written exactly as in `aggregations`, or a `groupBy` key (e.g. `'p99(duration_nano) desc'` when aggregating `p99(duration_nano)`); default: the first aggregation, descending
  706. - `limit` (optional) - Maximum number of groups to return (default: 100, max: 10000; higher values are clamped to bound server memory)
  707. - `functions` (optional) - Post-query transforms applied in order to each series, as an array of `{name, args}` objects (or a JSON-encoded string); each arg is `{"value": <number>}`. `timeShift` reads the window that many seconds earlier and returns its points on the current window's timestamps; `604800` gives the same window last week. To compare two windows, call once without `timeShift` and once with it. For `A - B` or `A / B` in one result, use `signoz_execute_builder_query` with two builder queries, the second with `timeShift`, and a `builder_formula`. `cutOffMin` and `cutOffMax` drop points below or above a threshold; `clampMin` and `clampMax` set them to it. `runningDiff` gives the change from the point before; `cumulativeSum` gives a running total. `ewma3`, `ewma5`, `ewma7`, `median3`, `median5`, and `median7` smooth a series; `fillZero` adds 0 at steps with no data; `absolute`, `log2`, and `log10` transform each value. SigNoz validates names and args. On a `scalar` request SigNoz applies only `timeShift`, and the response notes any other function it skipped
  708. - `timeRange` (optional) - Relative time range `<number><unit>` where unit is `m`/`h`/`d` (e.g. '30m', '1h', '6h', '24h', '7d'; default: '1h'; ignored when both `start` and `end` are provided)
  709. - `start` / `end` (optional) - Start/end time in unix milliseconds. When both are provided, they override `timeRange`.
  710. - `requestType` (optional) - `scalar` (default; one aggregate value over the whole range) or `time_series` (one value per time bucket). Unknown values are rejected.
  711. - `stepInterval` (optional) - Time bucket size in seconds for `time_series` mode. Accepts a number or numeric string (backend auto-selects when omitted)
  712. - `queryType` (optional) - `builder_query` (default) aggregates spans of all traces. Set `builder_ai_query` for AI observability queries: it aggregates spans of AI traces, and `aggregations`, `filter`, and `orderBy` also accept the trace-level fields listed for `signoz_search_traces`, e.g. `avg(trace.estimated_total_cost)`. One call cannot mix trace-level and span-level aggregations. Count AI traces with `count_distinct(trace_id)`. An unknown value runs as `builder_query` with an input validation notice
  713. - **Time-series ranking note**: the limit selects top groups over the whole requested window, not independently per bucket. Narrow the window or adjust the limit when a short-lived series could otherwise be hidden.
  714. - **Key-not-found errors**: a filter referencing a key absent from this workspace's traces metadata fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  715. #### `signoz_get_trace_details`
  716. For a known trace ID, return its spans and hierarchy. Each span comes back as its complete record: the span fields plus `attributes` and `resource` maps, `events`, and `links`. Use `signoz_search_traces` first when the ID is unknown. SigNoz locates the trace by its ID alone, so the tool takes no time window; an ID SigNoz does not know returns no spans.
  717. - **Parameters**:
  718. - `traceId` (required) - Known trace ID, usually discovered with `signoz_search_traces`
  719. - `includeSpans` (optional) - Include detailed span information. Boolean (or the strings `"true"`/`"false"`), default: true
  720. #### `signoz_get_ai_pricing`
  721. Return the AI model prices SigNoz uses to compute span cost, or the models that have no price. SigNoz stamps cost on each span at ingest: spans of a model no rule prices carry no cost, and a price change does not touch spans already stored. Prices are changed on the Model pricing tab of AI Observability in SigNoz.
  722. - **Parameters**:
  723. - `view` (optional) - `rules` (default): pricing rules with provider, model name and match patterns, input, output, and cache prices in USD per million tokens, and `enabled`. `unpriced_models`: models seen in spans during the last hour that no rule matches, with span counts
  724. - `searchText` (optional) - Case-insensitive substring of the model name or provider (`gpt-4o` also matches `gpt-4o-mini`). An empty page with `searchText` means no entry matched; omit it to see whether any entries exist
  725. - `limit` (optional) - Entries per page (default: 50, max: 1000; higher values are clamped)
  726. - `offset` (optional) - Entries to skip; use `pagination.nextOffset` from the previous page (default: 0)
  727. - **Response**: `view`, `data` (SigNoz's pricing rule or unpriced model objects as returned), and `pagination` (`total`, `offset`, `limit`, `hasMore`, `nextOffset`)
  728. #### `signoz_list_ai_attribute_mappings`
  729. List the span attribute mapping groups that map vendor AI span attributes (OpenInference, OpenLLMetry, Vercel AI SDK, and others) to `gen_ai.*` keys at ingest. A group runs on spans whose attribute keys contain one of its condition substrings, and each mapper fills one `gen_ai.*` key from the first source key present, by priority. Mappings apply only to spans ingested afterwards and are changed on the Attribute Mapping tab of AI Observability in SigNoz.
  730. - **Parameters**: none besides `searchContext`
  731. - **Response**: `data` (each group as SigNoz returns it, plus `mappers` with each mapper's sources), `incomplete`, and, when the mappers of some groups could not be read, `failedGroups` (`groupId`, `name`, `code`, `status`, `message`) and `nextAction`. Authentication and permission failures fail the whole call with a coded error
  732. #### `signoz_test_ai_attribute_mapping`
  733. Run sample spans through the mapping groups in a sandbox and return each span as SigNoz would store it. Nothing is saved and no real span changes. A span that gains `gen_ai.request.model` counts as a model call.
  734. - **Parameters**:
  735. - `spans` (required) - 1 to 100 sample spans, each `{attributes, resource}` with key-value maps. Example: `[{"attributes":{"llm.model_name":"gpt-4o","llm.token_count.prompt":120,"llm.token_count.completion":45}}]`
  736. - `groups` (optional) - Mapping groups to test instead of the saved ones, in the shape SigNoz accepts (`name`, `condition`, `enabled`, `mappers`). Omit to test the saved groups; an empty list tests none. A group without `mappers` uses the saved mappers of the group with the same name. SigNoz skips disabled groups, mappers, and condition keys, so set `enabled: true` on each
  737. - **Response**: `groupSource` (`saved` or `provided`), `testedGroups` (names of the enabled groups sent), `spans` (the mapped spans, in input order), and `collectorLogs`. `spans` and `groups` reach SigNoz exactly as sent, so large integers keep their precision; a response without one mapped span per sample is a coded upstream error
  738. #### `signoz_create_alert`
  739. Create a new alert rule in SigNoz via `POST /api/v2/rules`.
  740. - **Parameters**: JSON payload matching the SigNoz alert rule schema.
  741. - **Schema**: every `ruleType` (`threshold_rule`, `promql_rule`, `anomaly_rule`) uses **v2alpha1**: structured `condition.thresholds`, `evaluation`, `notificationSettings`, and `schemaVersion: "v2alpha1"` set explicitly, since SigNoz rejects a rule that omits it. `anomaly_rule` is metrics only, adds `condition.seasonality`, and compares each tier's signed target with the anomaly score (`below` with target `-2` fires on a drop of more than 2 standard deviations; `outside_bounds` with target `2` fires on a move of more than 2 either way).
  742. - **Notification routing**: For direct routing, reuse a fully paginated `signoz_list_notification_channels` result only from the same still-current prepared operation; otherwise call it, refreshing only if state may have changed. V2 needs an exact returned displayName on every tier: SigNoz rejects a tier with no channels or a channel name that does not exist. If none fits, ask the user or offer `signoz_create_notification_channel` with user-provided config; never create automatically. Confirmed v2 policy routing may omit tier channels.
  743. - **Tip**: Reuse alert resources only when already read for the same prepared operation; otherwise read `signoz://alert/instructions` and `signoz://alert/examples`. For PromQL, read `signoz://promql/instructions` when needed.
  744. #### `signoz_update_alert`
  745. Update an existing alert rule via `PUT /api/v2/rules/{id}`. This fully replaces the rule: reuse `signoz_get_alert`, `signoz://alert/instructions`, `signoz://alert/examples`, and fully paginated `signoz_list_notification_channels` results only from the same still-current prepared operation; otherwise read/call them, refreshing only if state may have changed, then preserve unchanged fields. Direct v2 needs an exact listed displayName on every tier; confirmed v2 policy routing may omit them.
  746. - **Parameters**:
  747. - `id` (required) - UUIDv7 of the rule to update (obtain from `signoz_list_alert_rules` / `signoz_get_alert`).
  748. - Plus all fields of the alert rule schema (same shape as `signoz_create_alert`).
  749. #### `signoz_delete_alert`
  750. Delete an alert rule via `DELETE /api/v2/rules/{id}`. Irreversible: discover the ID with `signoz_list_alert_rules` and confirm the exact rule first. When both steps are already complete, call the delete tool directly without repeating list/get preflight.
  751. - **Parameters**:
  752. - `id` (required) - UUIDv7 of the rule to delete. The server rejects non-UUIDv7 values with `invalid_input`.
  753. #### `signoz_delete_dashboard`
  754. Permanently delete a confirmed tenant dashboard by ID. The deletion is irreversible; use `signoz_list_dashboards` to discover the UUID. Use `signoz_delete_view` for a saved Explorer view.
  755. - **Parameters**: `id` (required) - Dashboard UUID to delete
  756. #### `signoz_list_notification_channels`
  757. List paginated v2 channel summaries (`id`, `name`, `displayName`, `kind`, timestamps).
  758. Alert routing uses `displayName`; `name` is the immutable machine identifier.
  759. Results omit provider settings and credentials. Use `signoz_get_notification_channel`
  760. for the complete configuration, and cover every page before declaring a channel absent.
  761. - **Parameters**: `query` searches display names; `kind` filters provider kind;
  762. `sort` is `updated_at`, `created_at`, or `name`; `order` is `asc` or `desc`.
  763. `limit` defaults to 20 and is capped at 200; `offset` defaults to 0.
  764. - **Defaults**: newest update first. The response includes the filtered total
  765. and explicit pagination metadata. Follow `pagination.nextOffset` while
  766. `pagination.hasMore` is true; `pagination.limit` reports the effective cap.
  767. #### `signoz_create_notification_channel`
  768. Create a notification channel from `config: {kind, spec}`. Check existing
  769. display names before creating a channel.
  770. - **Parameters**: `config` is required. Supply a DNS1123 `name`, or use
  771. `generateName: true` with a `displayName`. SigNoz defaults `displayName` from
  772. an explicit `name` when omitted. Both names become immutable after creation.
  773. Alert routing references use `displayName`, not `name`.
  774. - **Provider kinds**: `signoz://notification-channel/examples` lists every
  775. kind the pinned SigNoz release accepts, each kind's `config.spec` fields, and a
  776. worked payload per kind; it is generated from the SigNoz OpenAPI spec by
  777. `make gen`. SigNoz validates the kind and its rejection lists the kinds it
  778. accepts. SigNoz also rejects an unknown or missing `config.spec` field with
  779. the exact requirement, and a duplicate name with `already-exists`.
  780. - **Resolve notifications**: `config.spec.sendResolved` uses the provider's
  781. default when omitted. Get returns its effective value; preserve it on update.
  782. - **Test sends**: `test` defaults to `false`. Set `test: true` only when a test
  783. notification is intended. A failed test does not undo the created channel;
  784. inspect its reported status before retrying. Post-write authorization errors
  785. include `mutationCommitted: true` and the known ID so callers can authenticate
  786. and inspect the existing channel without creating another one.
  787. Example without a test send:
  788. ```json
  789. {
  790. "name": "checkout-oncall",
  791. "displayName": "Checkout on-call",
  792. "config": {
  793. "kind": "webhook",
  794. "spec": {"url": "https://alerts.example.com/signoz", "sendResolved": true}
  795. },
  796. "test": false
  797. }
  798. ```
  799. #### `signoz_update_notification_channel`
  800. Fully replace one channel's `config` using `id` and the complete canonical
  801. `config: {kind, spec}` object. Fetch the channel, copy its `config`, change only
  802. requested fields, then submit the complete object. Names cannot be changed.
  803. Preserve every untouched setting and credential without echoing secrets. A
  804. fetched config is writable as-is; to unset an optional field, omit it, because
  805. SigNoz rejects an empty string for template-backed fields such as titles and
  806. messages.
  807. `test` defaults to `false`; an explicit `true` sends a test after the update.
  808. A test failure does not undo the update. Do not replay an ambiguous write or
  809. an opt-in test automatically.
  810. #### `signoz_get_notification_channel`
  811. Get one channel's canonical `id`, machine `name`, `displayName`, timestamps,
  812. and full `config`. The `config.spec` can contain plaintext credentials; use it
  813. for updates without displaying or logging secrets. **Parameter**: `id`.
  814. #### `signoz_delete_notification_channel`
  815. Permanently delete a confirmed channel by `id`. Resolve and confirm the exact
  816. channel first; call directly when those steps are already complete. The backend
  817. may reject deletion while a routing policy references the channel. Propagate
  818. that dependency error and resolve references before retrying.
  819. #### `signoz_submit_feedback`
  820. Lets the agent send feedback to the SigNoz team in two cases. The agent hit a problem with this MCP server: a tool error it could not explain, a confusing description, schema, or result, a missing capability, or unclear documentation. Or the user has feedback about SigNoz, such as a bug, a request, or praise. The tool description tells the agent to mask personal and sensitive data (names, email addresses, IP addresses, hostnames, IDs, credentials, telemetry values) before sending. See [Agent feedback](#agent-feedback) for what leaves the server and how to turn it off.
  821. - **Parameters**:
  822. - `message` (required) - What the agent tried, expected, and saw, or what the user said about SigNoz. At most 2000 characters (`maxLength` in the schema)
  823. - `category` (optional) - One of `tool_error`, `confusing_output`, `missing_capability`, `documentation`, `user_feedback`, `user_frustration`, `other`
  824. - `toolName` (optional) - Name of the tool the report is about. At most 128 characters (`maxLength` in the schema)
  825. - `model` (optional) - Name or ID of the model the agent runs as, with its effort or thinking level, when it knows them. At most 128 characters (`maxLength` in the schema)
  826. - `searchContext` - User's original question
  827. - **Result**: `Feedback queued for delivery to the SigNoz team.` on success. Delivery is batched after the call returns, so a report can still be lost when the server cannot reach Segment; the server logs that failure. When feedback is turned off, a coded `UNSUPPORTED` error says so and nothing is sent. Invalid arguments return `VALIDATION_FAILED` naming the field.
  828. - **Annotations**: not read-only and not idempotent, because each call sends one report outside the server.
  829. #### `signoz_execute_builder_query`
  830. Runs a SigNoz Query Builder v5 request that the dedicated tools cannot express, including multi-query requests, formulas, PromQL, and ClickHouse SQL. Prefer `signoz_search_logs` / `signoz_search_traces` for rows, `signoz_aggregate_logs` / `signoz_aggregate_traces` for grouped results, and `signoz_query_metrics` for ordinary metrics.
  831. - **Parameters**: `query` (required) - the complete `query_range` request. The input schema describes its top-level fields (`start`, `end`, `requestType`, `compositeQuery`, `variables`, `formatOptions`, `noCache`) with the descriptions from the SigNoz OpenAPI spec; the query envelopes inside `compositeQuery.queries` are open objects the guides and `signoz://query-builder/examples` cover.
  832. - **Query types**: the per-envelope `compositeQuery.queries[i].type` selects the spec shape:
  833. - `builder_query`: signal-specific spec (logs/traces/metrics) with filter, aggregations, groupBy, etc.
  834. - `builder_ai_query`: a traces builder spec run over AI traces, with the per-trace `trace.` keys. See `signoz://ai/query-builder-guide`.
  835. - `builder_formula`: formula expression referencing other query names (e.g. `A / B * 100`).
  836. - `promql`: `{name, query, disabled, step?, legend?}`. PromQL for OTel metrics requires the Prometheus 3.x UTF-8 quoted-selector form `{"metric.name.with.dots"}`; read the `signoz://promql/instructions` resource for details.
  837. - `clickhouse_sql`: `{name, query, disabled, legend?}`.
  838. - **Builder result bounds**: for predictable authored queries, explicitly supply a positive `spec.limit` and non-empty v5 `spec.order` (not dashboard/editor `orderBy`) on every `builder_formula` and on each `builder_query` no formula references. When omitted, null, or zero, standalone limits and formula-result limits default to `100`. A builder query referenced by a formula gets no inserted limit or order, because SigNoz applies base-query limits before formula evaluation and they drop groups from the result. Raw logs order by `timestamp desc, id desc`; raw traces by `timestamp desc`; metric scalar/time-series queries and formulas by `__result desc`; and log/trace scalar/time-series queries by the primary aggregation descending. A `builder_ai_query` gets the same default limit as a `builder_query` of its request type and no default order, because SigNoz orders AI trace rows by last activity. Caller-supplied values are forwarded unchanged. The response appends a decisions note when defaults are inserted.
  839. - **Validation**: apart from inserted bounds, the request reaches SigNoz verbatim and SigNoz validates it. `requestType` has no default (`raw`, `trace`, `time_series`, or `scalar`), and `start` and `end` are required Unix-millisecond timestamps.
  840. - **Guide routing**: read `signoz://logs/query-builder-guide` for logs, `signoz://traces/query-builder-guide` for traces, `signoz://ai/query-builder-guide` for `builder_ai_query`, `signoz://metrics-aggregation-guide` for metrics/formulas, and `signoz://promql/instructions` for PromQL.
  841. - **Time-series ranking caveat**: top-N groups are ranked over the entire requested window. A short-lived spike can be omitted even when it dominates one bucket; narrow the window or adjust the limit when that matters.
  842. - **Backend warnings**: non-fatal warnings the backend returns (e.g. ambiguous-key resolution) stay in the response's `data.warning` block and are WARN-logged, as in the search, aggregate, and query_metrics tools. They are not repeated in a note.
  843. - **Key-not-found errors**: a filter referencing a key absent from the workspace's metadata for the queried signal fails with recovery guidance in the error text plus a machine-readable `missingKeys` array in the structured error content
  844. - **Documentation**: See [SigNoz Query Builder v5 docs](https://signoz.io/docs/userguide/query-builder-v5/)
  845. </details>
  846. ## Environment Variables
  847. | Variable | Description | Required |
  848. | ----------------- | ------------------------------------------------------------------------------ | ----------------------------------- |
  849. | `SIGNOZ_URL` | SigNoz instance URL | Yes (stdio); Optional (http with OAuth) |
  850. | `SIGNOZ_API_KEY` | SigNoz API key (get from Settings → API Keys in the SigNoz UI) | Yes (stdio); Optional (http with OAuth) |
  851. | `LOG_LEVEL` | Logging level: `info`(default), `debug`, `warn`, `error` | No |
  852. | `TRANSPORT_MODE` | MCP transport mode: `stdio`(default) or `http` | No |
  853. | `MCP_SERVER_HOST` | Host/interface for HTTP transport mode (default: empty, which listens on all interfaces). Set to `127.0.0.1` for loopback-only access. | No |
  854. | `MCP_SERVER_PORT` | Port for HTTP transport mode (default: `8000`) | No |
  855. | `MCP_MAX_REQUEST_BYTES` | Max inbound MCP HTTP request body size in bytes (default: `4194304` / 4 MiB). Bounds memory from a single oversized request. | No |
  856. | `CLIENT_CACHE_SIZE` | Maximum cached tenant clients in multi-tenant HTTP mode (default: `256`) | No |
  857. | `CLIENT_CACHE_TTL_MINUTES` | Tenant-client cache lifetime in minutes (default: `30`) | No |
  858. | `SIGNOZ_DOCS_REFRESH_INTERVAL` | Scheduled incremental docs refresh interval (Go duration, default: `6h`). Set to `0` (or `off`) to disable it. To stop every scheduled refresh and serve the embedded docs index unchanged, set `SIGNOZ_DOCS_FULL_REFRESH_INTERVAL=0` as well. See [Memory footprint](#memory-footprint). | No |
  859. | `SIGNOZ_DOCS_FULL_REFRESH_INTERVAL` | Scheduled forced full docs refresh interval (Go duration, default: `24h`). Set to `0` (or `off`) to disable only the forced full refresh. | No |
  860. | `OAUTH_ENABLED` | Enable OAuth 2.1 authentication flow (`true`/`false`) | No (default: `false`) |
  861. | `OAUTH_TOKEN_SECRET` | Encryption key for OAuth tokens (min 32 bytes, e.g. `openssl rand -base64 32`) | Yes when `OAUTH_ENABLED=true` |
  862. | `OAUTH_ISSUER_URL` | Public URL of this MCP server (used in OAuth metadata discovery) | Yes when `OAUTH_ENABLED=true` |
  863. | `OAUTH_ACCESS_TOKEN_TTL_MINUTES` | Access token lifetime in minutes (default: 60) | No |
  864. | `OAUTH_REFRESH_TOKEN_TTL_MINUTES` | Refresh token lifetime in minutes (default: 43200 / 30d) | No |
  865. | `OAUTH_AUTH_CODE_TTL_SECONDS` | Authorization code lifetime in seconds (default: 600 / 10min) | No |
  866. | `SIGNOZ_CUSTOM_HEADERS` | Extra HTTP headers added to every API request, useful when SigNoz is behind a reverse proxy requiring auth (e.g. `CF-Access-Client-Id:id.access,CF-Access-Client-Secret:secret`). Format: `Key1:Value1,Key2:Value2` | No |
  867. | `SIGNOZ_INSTANCE_URL_ALLOWLIST` | Multi-tenant (http) only: comma-separated allowlist of SigNoz backend hosts the server will proxy to. Entries are exact hosts (`signoz.example.com`) or wildcards (`*.us.signoz.cloud`, which matches any subdomain ending in `.us.signoz.cloud`); a scheme/port/path accidentally included in an entry is tolerated and reduced to the bare host. When set, SigNoz instance URLs that do not match are refused at every ingress: the OAuth setup form and `X-SigNoz-URL` header return HTTP 403, the OAuth token endpoint (incl. existing refresh tokens) returns `invalid_grant`, and `/mcp` requests via an OAuth token return 403. All increment a `disallowed_signoz_url`-tagged failure metric for alerting (not logged per-request, to avoid noise from misconfigured/looping clients), and the rejection message points SigNoz Cloud users to their region's MCP URL (`mcp.<region>.signoz.cloud`) with a docs link. Empty/unset allows no host other than `SIGNOZ_URL`, so a server without `SIGNOZ_URL` must set it. The operator's own `SIGNOZ_URL` is always allowed. | No |
  868. | `ANALYTICS_ENABLED` | Enable product analytics (`true`/`false`; default: `false`) | No |
  869. | `SEGMENT_KEY` | Segment write key. Product analytics uses it only when `ANALYTICS_ENABLED` is `true`. [Agent feedback](#agent-feedback) goes to it whenever it is set. | No |
  870. | `FEEDBACK_ENABLED` | `false` turns off `signoz_submit_feedback`, so the server sends no agent feedback (default: `true`). See [Agent feedback](#agent-feedback). | No |
  871. | `OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP gRPC endpoint for the MCP server's own traces and metrics. Internal telemetry export is disabled when no OTLP endpoint/exporter is configured. For plaintext collectors, use an `http://` endpoint such as `http://localhost:4317`. | No |
  872. | `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Trace-specific OTLP gRPC endpoint; overrides `OTEL_EXPORTER_OTLP_ENDPOINT` for traces. | No |
  873. | `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` | Metrics-specific OTLP gRPC endpoint; overrides `OTEL_EXPORTER_OTLP_ENDPOINT` for metrics. | No |
  874. | `OTEL_TRACES_EXPORTER` | Set to `none` to disable internal trace export even when an OTLP endpoint is configured. | No |
  875. | `OTEL_METRICS_EXPORTER` | Set to `none` to disable internal metrics export and runtime metrics even when an OTLP endpoint is configured. | No |
  876. The MCP server does not run an OTLP log exporter; logs are emitted as JSON to stderr. `OTEL_LOGS_EXPORTER` is therefore not used.
  877. ### Agent feedback
  878. Release binaries and Docker images send one thing to SigNoz by default: the reports an agent submits with `signoz_submit_feedback`, about a problem it hit with this server or on behalf of a user who has feedback about SigNoz. A report leaves the server only when the agent calls that tool. Nothing is sent in the background, and no usage events are sent.
  879. Each report carries:
  880. | Property | Description |
  881. |---|---|
  882. | `feedbackMessage` | The report, at most 2000 characters. The tool tells the agent to mask personal and sensitive data first |
  883. | `feedbackCategory`, `feedbackToolName` | The optional category and tool name the agent passed |
  884. | `feedbackModel` | The model, and effort or thinking level, the agent says it runs as, when it passed one. The server cannot check it |
  885. | `clientName`, `clientVersion`, `protocolVersion` | The MCP client that made the call |
  886. | `clientSource` | Whether the call came from a user's MCP client or the SigNoz AI assistant |
  887. | `serverVersion` | This server's version |
  888. | `deployment` | `cloud` when the report is about a SigNoz Cloud instance, otherwise `self_hosted` |
  889. Who a report is attributed to depends on the SigNoz instance the call targets:
  890. - **Self-hosted SigNoz**: an HMAC-SHA256 hash of your SigNoz org ID. The hash is the same for every report from one org and cannot be turned back into the ID. No instance URL, user ID, name, or email address is sent.
  891. - **SigNoz Cloud** (a SigNoz URL under `signoz.cloud`): the identity SigNoz Cloud already holds for the caller, in place of the hash: `orgId`.
  892. No API key, tool arguments, or query results are sent in either case. The server logs one line at startup when feedback is on.
  893. The server also records each report it accepts in its own telemetry, before delivery: an `agent feedback received` log line, and the tool call's trace span when an OTLP endpoint is configured. Both carry `mcp.feedback.message` (the full report), `mcp.feedback.category`, `mcp.feedback.tool_name`, and `mcp.feedback.model`. They go where your logs and traces already go, and a report that could not be delivered is still there.
  894. To turn feedback off, set this before the server starts:
  895. ```bash
  896. FEEDBACK_ENABLED=false
  897. ```
  898. The tool then returns a coded `UNSUPPORTED` error and sends nothing.
  899. ### Browser links for self-hosted SigNoz
  900. > **Note:** Set `global.external_url` on the **SigNoz server** to the URL users open in their browser. The MCP server reads it from `GET /api/v1/global/config`, so the instance URL is configured in one place.
  901. For example, add this environment variable to the SigNoz deployment and restart SigNoz:
  902. ```bash
  903. SIGNOZ_GLOBAL_EXTERNAL__URL=https://observe.example.com
  904. ```
  905. There are two underscores before `URL`. The equivalent SigNoz YAML configuration is:
  906. ```yaml
  907. global:
  908. external_url: https://observe.example.com
  909. ```
  910. Keep `SIGNOZ_URL` on the MCP server pointed at its reachable API address, such as `http://signoz:8080`. If the deployment uses a path prefix, include it in the API address as required by SigNoz and your proxy routing. Configure a backend path in `SIGNOZ_URL`: per-request URLs supplied through OAuth or `X-SigNoz-URL` currently support origins only.
  911. Browser links use the discovered URL, including any configured base path, while API requests retain their destination and credentials. Each tenant client caches discovery for 15 minutes. An unset external URL uses the request's API URL; unavailable or invalid global configuration logs a warning and retries discovery after one minute. Authentication and permission errors are returned to the client.
  912. ## Claude Desktop Extension
  913. ### Building the Bundle
  914. Requires **Node.js**. See [Anthropic MCPB](https://github.com/anthropics/mcpb) for details.
  915. ```bash
  916. make bundle
  917. ```
  918. ### Installing
  919. 1. Open **Claude Desktop → Settings → Developer → Edit Config → Add bundle.mcpb**
  920. 2. Select `./bundle/bundle.mcpb`
  921. 3. Enter your `SIGNOZ_URL`, `SIGNOZ_API_KEY`, and optionally `LOG_LEVEL`
  922. 4. Restart Claude Desktop
  923. For browser links, configure [SigNoz's global external URL](#browser-links-for-self-hosted-signoz).
  924. ## End-to-End Tests
  925. The e2e suite under [`tests/`](tests/README.md) runs the server (built from the working tree) against a real SigNoz instance provisioned by foundry and drives it over the MCP HTTP transport:
  926. ```bash
  927. make test-e2e # cast SigNoz, run the suites, tear down
  928. make test-e2e-reuse # rerun against the cached environment
  929. ```
  930. Requires Docker, `foundryctl`, Go, and uv. See [tests/README.md](tests/README.md) for the full workflow.
  931. ## Architecture
  932. For a detailed overview of request flow, component interactions, and design decisions, see [docs/architecture.md](docs/architecture.md).
  933. ## Contributing
  934. See [CONTRIBUTING.md](CONTRIBUTING.md) for development workflow, required docs/manifest sync for MCP changes, and PR checklist.
  935. **Made with ❤️ for the observability community**

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.