SigNoz MCP Server

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.

📖 Full Documentation

Table of Contents

• Connect to SigNoz Cloud
• Self-Hosted Installation
• Connect to Self-Hosted SigNoz
• MCP Protocol Compatibility
• What Can You Do With It?
• Available Tools
• Environment Variables
• Claude Desktop Extension
• End-to-End Tests
• Architecture
• Contributing

Connect to SigNoz Cloud

Connect your AI tool to SigNoz Cloud's hosted MCP server. No installation is required; just add the hosted MCP URL and authenticate.

https://mcp.<region>.signoz.cloud/mcp

Make sure you select the correct region that matches your SigNoz Cloud account. Using the wrong region will result in authentication failures.

Find your region under Settings → Ingestion in SigNoz, or see the SigNoz Cloud region reference.

One-Click Install Links

GitHub does not reliably make custom-protocol links like cursor:// and vscode: clickable in README rendering.

Use the documentation page for one-click install buttons:

• Open one-click install links for Cursor
• Open one-click install links for VS Code

If you prefer, use the manual configuration examples below in this README.

Cursor

Manual Configuration

Add this configuration to .cursor/mcp.json:

{
  "mcpServers": {
    "signoz": {
      "url": "https://mcp.<region>.signoz.cloud/mcp"
    }
  }
}

Need help? See the Cursor MCP docs.

VS Code / GitHub Copilot

Manual Configuration

Add this configuration to .vscode/mcp.json:

{
  "servers": {
    "signoz": {
      "type": "http",
      "url": "https://mcp.<region>.signoz.cloud/mcp"
    }
  }
}

Need help? See the VS Code MCP docs.

Claude Desktop

Add SigNoz Cloud as a custom connector in Claude Desktop:

1. Open Claude Desktop.
2. Go to Settings → Developer (or Features, depending on your version).
3. Click Add Custom Connector or Add Remote MCP Server.
4. Enter your SigNoz MCP URL: https://mcp.<region>.signoz.cloud/mcp

When prompted, complete the authentication flow.

Claude Code

Run this command to add the hosted SigNoz MCP server:

claude mcp add --scope user --transport http signoz https://mcp.<region>.signoz.cloud/mcp

After configuring the MCP server, authenticate in a terminal:

claude /mcp

Select the signoz server and complete the authentication flow.

OpenAI Codex

Run this command to add the hosted SigNoz MCP server:

codex mcp add signoz --url https://mcp.<region>.signoz.cloud/mcp

Or add this configuration to config.toml:

[mcp_servers.signoz]
url = "https://mcp.<region>.signoz.cloud/mcp"

After adding the server, authenticate:

codex mcp login signoz

Then run /mcp inside Codex to verify the connection.

Grok Build

Run this command to add the hosted SigNoz MCP server:

grok mcp add -t http signoz https://mcp.<region>.signoz.cloud/mcp

Or add this configuration to ~/.grok/config.toml:

[mcp_servers.signoz]
url = "https://mcp.<region>.signoz.cloud/mcp"
enabled = true

Adding the server does not authenticate it. Start Grok Build, run /mcps, select the signoz server, and complete the OAuth flow in your browser:

grok

/mcps

No API key is stored in the config file; credentials are saved separately once the OAuth flow completes.

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.

Verify the connection with:

grok mcp list
grok mcp doctor

SigNoz Cloud Authentication

When you add the hosted MCP URL to your client, the client initiates an authentication flow. You will be prompted to enter:

1. Your SigNoz instance URL (for example, your-instance.signoz.cloud). Protocol-less URLs are accepted; paths, query parameters, and fragments are ignored.
2. Your API key

Create an API key in Settings → API Keys in SigNoz. Only Admin users can create API keys.

Self-Hosted Installation

Download Binary (Recommended)

Download the latest binary from GitHub 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:

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.

Connect to Self-Hosted SigNoz

Prerequisites

• A running SigNoz instance
• SigNoz v0.135.0 or newer for the dashboard tools (create/get/update/patch/list/delete/import), which use the v2/Perses dashboards API
• SigNoz v0.135.0 or newer for signoz_check_metric_usage (it reads v2/Perses dashboards for dashboard usage; on older versions the dashboard half is silently empty, though alert usage alone works from v0.131.0)
• SigNoz v0.120.0 or newer for alert-rule list/get/create/update/delete tools, and v0.118.0 or newer for alert history
• A SigNoz API key (Settings → API Keys in the SigNoz UI)
• The signoz-mcp-server binary (see Self-Hosted Installation)

Stdio Mode (Claude Desktop / Cursor / Any MCP Client)

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:

{
    "mcpServers": {
        "signoz": {
            "command": "/absolute/path/to/signoz-mcp-server",
            "args": [],
            "env": {
                "SIGNOZ_URL": "https://your-signoz-instance.com",
                "SIGNOZ_API_KEY": "your-api-key-here",
                "LOG_LEVEL": "info"
            }
        }
    }
}

HTTP Mode

HTTP mode listens on all interfaces by default. Set MCP_SERVER_HOST=127.0.0.1 when the server should accept loopback connections only.

With OAuth (Multi-Tenant / Cloud)

Start the server:

TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
OAUTH_ENABLED=true \
OAUTH_TOKEN_SECRET=$(openssl rand -base64 32) \
OAUTH_ISSUER_URL=https://your-public-mcp-url.com \
./signoz-mcp-server

Client config needs just the URL, no keys:

{
    "mcpServers": {
        "signoz": {
            "url": "https://your-public-mcp-url.com/mcp"
        }
    }
}

The client discovers OAuth endpoints automatically, opens a browser for credentials, and handles token exchange.

Without OAuth (Simple Setup)

The API key and SigNoz URL only need to be provided in one place: the server or the client.

Option A — Credentials on the server (simpler client config):

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

{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp"
        }
    }
}

Option B — API key on the client (server holds the URL, client sends the key):

SIGNOZ_URL=https://your-signoz-instance.com \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
./signoz-mcp-server

{
    "mcpServers": {
        "signoz": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "SIGNOZ-API-KEY": "your-api-key-here"
            }
        }
    }
}

MCP Protocol Compatibility

SigNoz uses the official MCP Go SDK v1.7.0 and supports both current lifecycle models over HTTP and stdio:

Protocol era	Lifecycle
2025-11-25	Legacy clients use initialize, then notifications/initialized, before ordinary requests.
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.

The HTTP /mcp endpoint is stateless and sessionless. MCP messages use JSON POST requests and successful responses use application/json; the server does not issue or require Mcp-Session-Id. GET /mcp and DELETE /mcp return 405 Method Not Allowed, so deployments need neither sticky routing nor the old GET listener/heartbeat. Existing client configuration does not change.

The server intentionally does not advertise the deprecated logging capability. Discovery ordering is not a compatibility guarantee. Unknown tools, resources, and prompts use the official SDK's standard invalid-params behavior rather than legacy implementation-specific wording or error codes.

HTTP Probe Endpoints

HTTP mode exposes unauthenticated probe endpoints. New Kubernetes deployments should use /livez for livenessProbe and /readyz for readinessProbe.

Endpoint	Purpose
/livez	Shallow liveness probe. Returns 200 OK when the server process can answer HTTP requests. It does not check dependencies.
/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.
/healthz	Legacy/generic health check kept for backward compatibility. It follows the same strict status as /readyz; use /livez for shallow liveness.

What Can You Do With It?

"Show me all available metrics"
"What's the p99 latency for http_request_duration_seconds?"
"List all active alerts"
"Show me error logs for the paymentservice from the last hour"
"How many errors per service in the last hour?"
"Search traces for the checkout service from the last hour"
"Get details for trace ID abc123"
"Create a dashboard with CPU and memory widgets"
"How do I send Docker logs to SigNoz?"

Available Tools

SigNoz compatibility: signoz_check_metric_usage needs SigNoz v0.135.0 for dashboard usage: its /api/v3/metrics/dashboards?metricName=... route reads v2/Perses dashboards, which go live in v0.135.0, so on older versions the dashboard half returns empty (the route itself exists from v0.131.0 but has no Perses dashboards to read). Its alert-usage route /api/v2/metrics/alerts?metricName=... works from v0.131.0. The dashboard tools (create/get/update/patch/list/delete/import) use the v2/Perses dashboards API and require SigNoz v0.135.0 or newer. Alert-rule list/get/create/update/delete require SigNoz v0.120.0 or newer. signoz_get_alert_history requires v0.118.0 or newer. Self-hosted deployments on older SigNoz versions will see HTTP 404 from the affected tools. Notification-channel tools target the render-envelope /api/v1/channels/* routes introduced by SigNoz/signoz#10941, #10957, #10995, and #10997.

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.

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.

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.

Tool	Description
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
signoz_list_metrics	Discover active metric names and catalog metadata
signoz_query_metrics	Query known metrics for values, trends, breakdowns, or formulas
signoz_get_top_metrics	Return top 100 metrics ranked by ingested sample volume with pre-computed percentages for cost and volume analysis
signoz_check_metric_usage	Given a list of metric names (up to 50 per call), return which dashboards and alerts reference each one
signoz_check_metric_cardinality	Return label/attribute keys for a single metric with cardinality counts and sample values, sorted highest-cardinality first
signoz_get_field_keys	Discover available field keys for metrics, traces, or logs
signoz_get_field_values	Get possible values for a field key
signoz_list_alerts	List firing/silenced/inhibited Alertmanager alert instances (not rule definitions)
signoz_list_alert_rules	List configured alert-rule summaries, including inactive/OK and disabled rules
signoz_get_alert	Get one alert rule's full definition by id
signoz_get_alert_history	Get one rule's firing or state-transition history
signoz_create_alert	Create a v2 direct/policy-routed alert or a direct-routed v1 anomaly alert
signoz_update_alert	Fully replace an existing alert rule by id
signoz_delete_alert	Permanently delete a confirmed alert rule by UUIDv7 id
signoz_list_dashboards	List tenant-dashboard summaries and discover UUIDs
signoz_get_dashboard	Get one dashboard's full layout, variables, panels, and queries
signoz_create_dashboard	Create a custom multi-panel dashboard
signoz_update_dashboard	Fully replace a fetched dashboard while preserving unrequested fields
signoz_patch_dashboard	Apply a partial RFC 6902 JSON Patch without resending the whole dashboard
signoz_delete_dashboard	Permanently delete a confirmed dashboard by id
signoz_import_dashboard	Create a dashboard from a known curated template path
signoz_list_dashboard_templates	List curated templates and discover an import path
signoz_list_services	List APM services with trace activity in a time range
signoz_get_service_top_operations	Get ranked operations for one traced service
signoz_list_views	List saved Explorer views for traces/logs/metrics/Cost Meter/AI Observability and discover UUIDs
signoz_get_view	Get one saved Explorer view's complete definition by id
signoz_search_docs	Find ranked official-doc matches when no exact page is selected
signoz_fetch_doc	Fetch one known official-doc page or heading as Markdown
signoz_create_view	Save one reusable Explorer query spec
signoz_update_view	Fully replace a fetched saved view while preserving unrequested fields
signoz_delete_view	Permanently delete a confirmed saved view by id
signoz_aggregate_logs	Aggregate log statistics and grouped or top-N breakdowns
signoz_search_logs	Return individual log records matching filters
signoz_aggregate_traces	Aggregate span statistics and grouped or top-N breakdowns
signoz_search_traces	Return individual span rows or discover trace IDs
signoz_get_trace_details	Get one known trace with all spans and hierarchy
signoz_execute_builder_query	Query Builder v5 requests the dedicated tools cannot express
signoz_list_notification_channels	List channel summaries for name verification and ID discovery
signoz_get_notification_channel	Get all provider-specific settings for one channel by ID
signoz_create_notification_channel	Create a uniquely named channel and send a test notification
signoz_update_notification_channel	Fully replace a fetched channel and send a test notification
signoz_delete_notification_channel	Permanently delete a confirmed channel by ID

For detailed usage and examples, see the full documentation.

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).

Agent Routing Guidance

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.

Docs tools use the same authentication path as other MCP tools.

Available Resources

Resource	Read when you need
signoz://alert/instructions	Alert schemas, fields, thresholds, evaluation, and notification workflow
signoz://alert/examples	Alert payload examples for v2 direct/policy routing and v1 direct anomaly routing
signoz://dashboard/instructions	Dashboard fields, variables, chaining, and layout
signoz://dashboard/widgets-instructions	Panel choices and query-specific guides
signoz://dashboard/widgets-examples	Panel examples and validation patterns
signoz://dashboard/list-filter-guide	signoz_list_dashboards filter DSL: grammar, per-key operators, and examples
signoz://dashboard/patch-instructions	signoz_patch_dashboard JSON Patch recipes and exact paths (add/edit/move/remove a panel, query, variable)
signoz://dashboard/examples	Complete server-verified dashboard payloads (metrics timeseries, dynamic-variable filter, number panel, multi-panel)
signoz://dashboard/query-builder-example	Dashboard Query Builder aggregations, filters, legends, and functions
signoz://promql/instructions	PromQL widgets or alerts, especially dotted OTel metric names
signoz://dashboard/clickhouse-schema-for-logs	Bundled logs schema snapshot for dashboard SQL
signoz://dashboard/clickhouse-logs-example	Raw ClickHouse logs widget patterns
signoz://dashboard/clickhouse-schema-for-metrics	Bundled metrics schema snapshot for dashboard SQL
signoz://dashboard/clickhouse-metrics-example	Raw ClickHouse metrics widget patterns
signoz://dashboard/clickhouse-schema-for-traces	Bundled traces schema snapshot for dashboard SQL
signoz://dashboard/clickhouse-traces-example	Raw ClickHouse traces widget patterns
signoz://logs/query-builder-guide	Logs Query Builder v5 JSON or unfamiliar log fields
signoz://traces/query-builder-guide	Traces Query Builder v5 JSON or unfamiliar trace fields
signoz://metrics-aggregation-guide	Metric aggregations, formulas, grouping, limits, and Cost Meter queries
signoz://view/instructions	Saved view fields, the v2 typed spec, and read-before-replace workflow
signoz://view/examples	Saved-view typed-spec payloads for traces, logs, metrics, and Cost Meter
signoz://docs/sitemap	Indexed official-doc catalog and page URLs

Resource Template Migration

The live signoz://dashboard/{id}/summary and signoz://alert/{id}/summary resource templates are retired. resources/templates/list now returns an empty catalog. Use signoz_get_dashboard for a dashboard definition. For the former alert summary, call signoz_get_alert, then signoz_get_alert_history; omit the time range for the same six-hour window and set limit: 10 and order: "desc" for the closest history result.

signoz_get_org_overview

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.