SigNoz MCP Server - AI Agent Integration Guide

The SigNoz MCP Server implements the Model Context Protocol (MCP), an open standard that lets AI agents interact with your SigNoz observability data. Use natural language to query metrics, traces, and logs; investigate alerts; and manage dashboards, alert rules, saved views, and notification channels.

The MCP server works best with the SigNoz plugin: one install adds the server registration and every Agent Skill, so your agent can query, build, and troubleshoot in SigNoz from the first prompt.

If you've already set up the MCP server, skip ahead to the use cases to see what you can do with it.

Connect to SigNoz's MCP server

Connect your AI tool to SigNoz Cloud's hosted MCP server. No installation required: just add the 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.

Verify these values:

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

Install in one click

Manual Configuration

Add this configuration to .cursor/mcp.json:

.cursor/mcp.json

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

Verify these values:

<region>: Your SigNoz Cloud region

Need help? See the Cursor MCP docs ↗

Install in one click

Manual Configuration

Add this configuration to .vscode/mcp.json:

.vscode/mcp.json

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

Verify these values:

<region>: Your SigNoz Cloud region

Need help? See the VS Code MCP docs ↗

Configure

Run this command to add the SigNoz MCP server:

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

Verify these values:

<region>: Your SigNoz Cloud region

After configuring the MCP server, you need to authenticate. In a terminal run:

claude /mcp

Select the signoz server and complete the authentication flow.

Configure

Run this command to add the SigNoz MCP server:

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

Or add this configuration to config.toml:

config.toml

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

Verify these values:

<region>: Your SigNoz Cloud region

After adding the server, authenticate:

codex mcp login signoz

Then run /mcp inside Codex to verify the connection.

Configure

Add the MCP server via CLI:

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

Or add this configuration to ~/.gemini/settings.json:

settings.json

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

Verify these values:

<region>: Your SigNoz Cloud region

After installation, start Gemini CLI and authenticate:

/mcp auth signoz

Configure

Add this configuration to ~/.codeium/windsurf/mcp_config.json:

mcp_config.json

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

Verify these values:

<region>: Your SigNoz Cloud region

When prompted, complete the authentication flow.

Configure

Open the MCP Store via the ... menu in the agent panel.
Click Manage MCP Servers.
Add a new server with the SigNoz MCP URL: https://mcp.<region>.signoz.cloud/mcp

Or manually add to mcp_config.json:

mcp_config.json

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

Verify these values:

<region>: Your SigNoz Cloud region

After saving the config, it will prompt you to complete the OAuth flow. To edit the config from within Antigravity, click the ... menu at the top of the Agent pane → MCP Servers → Manage MCP Servers → View raw config.

If you run into authentication issues, open the command palette and run Authentication: Remove Dynamic Authentication Providers to clear cached OAuth credentials and re-authenticate.

Configure

Add the MCP server via CLI:

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

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

config.toml

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

Verify these values:

<region>: Your SigNoz Cloud region

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.

Add -s project to the add command to write to ./.grok/config.toml instead, sharing the server with everyone working in that directory.

Verify the connection:

grok mcp list
grok mcp doctor

Authenticate from your client

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

Your SigNoz instance URL (e.g., https://your-instance.signoz.cloud)
Your API key: go to Settings → Service Accounts in SigNoz, create a service account, and generate an API key (requires Admin role). See Service Accounts for details.

SigNoz Cloud's hosted MCP server uses OAuth 2.1 for client-to-MCP authentication. MCP clients discover the auth endpoints from the server metadata, dynamically register as an OAuth client using Dynamic Client Registration (DCR, RFC 7591) when supported, then use Authorization Code + PKCE. During the browser step, SigNoz asks for your SigNoz instance URL and service account API key; the MCP server validates those credentials and issues bearer/refresh tokens for future MCP requests.

SigNoz Cloud's MCP server also supports header-based authentication for clients that can't do OAuth, but the recommended approach is to use OAuth when possible for better security and token management.

Only Admin users can create API keys. If you don't see the option, contact your workspace administrator.

Header-Based Authentication

Some MCP clients (like Cursor Automations) run entirely in the cloud and cannot perform interactive OAuth authentication. For these clients, use header-based authentication by passing your API key and instance URL directly in the request headers.

If your MCP client doesn't support OAuth flows or stdio transport (for example, Cursor Automations), use this header-based configuration instead.

mcp.json

{
  "mcpServers": {
    "signoz": {
      "url": "https://mcp.<region>.signoz.cloud/mcp",
      "headers": {
        "SIGNOZ-API-KEY": "<your-api-key>",
        "X-SigNoz-URL": "<your-signoz-instance-url>"
      }
    }
  }
}

Verify these values:

<region>: Your SigNoz Cloud region
<your-api-key>: API key from SigNoz Service accounts
<your-signoz-instance-url>: Your SigNoz Cloud instance URL

Keep your API key secure: never commit mcp.json to version control when it contains secrets.

For Self-Hosted SigNoz, you run the MCP server locally. The server supports two transport modes: Stdio (local binary, launched by the client) and HTTP (standalone server the client connects to over the network).

Use the latest SigNoz release with the latest MCP server. The MCP server targets the current SigNoz APIs; older SigNoz deployments may not support every tool. The MCP server changelog lists breaking changes and the SigNoz release each version targets.

Fetch your API key

Log in to your SigNoz instance.
Go to Settings → Service Accounts.
Create a service account, open its Keys tab, click Add Key, and copy the generated key. See Service Accounts for details.

Only Admin users can create API keys. Keep your key secure: never commit it to version control.

Install the MCP server

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
 
# Linux (arm64)
curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_linux_arm64.tar.gz | tar xz

This extracts a signoz-mcp-server_<os>_<arch> directory in the current directory. The binary is at bin/signoz-mcp-server inside it, for example signoz-mcp-server_linux_amd64/bin/signoz-mcp-server. Move it somewhere on your PATH or note the absolute path for the config below.

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 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="<your-signoz-url>" \
  -e SIGNOZ_API_KEY="<your-api-key>" \
  signoz/signoz-mcp-server:latest

Verify these values:

<your-signoz-url>: The SigNoz API URL reachable from inside the MCP container. For containers on the same Docker network, use the SigNoz service name, such as http://signoz:8080, and attach the MCP container to that network with --network. On Docker Desktop, use http://host.docker.internal:8080 to reach SigNoz on the host. localhost inside the MCP container refers to that container itself.
<your-api-key>: The API key from Fetch your API key

Docker always runs in HTTP transport mode. Use the HTTP tabs in the client setup below.

Configure your MCP client

Add the following to .cursor/mcp.json in your project root, or use Cursor → Settings → Tools & Integrations → + New MCP Server:

.cursor/mcp.json

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Start the MCP server in HTTP mode:

SIGNOZ_URL="<your-signoz-url>" \
SIGNOZ_API_KEY="<your-api-key>" \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
LOG_LEVEL=info \
./signoz-mcp-server

Add to .cursor/mcp.json:

.cursor/mcp.json

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

Open Command Palette (Cmd+Shift+P / Ctrl+Shift+P) → MCP: Open User Configuration, then add:

.vscode/mcp.json

{
  "servers": {
    "signoz": {
      "type": "stdio",
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Open Copilot Chat in Agent mode and confirm you trust the server.

Start the MCP server in HTTP mode.
Add to VS Code MCP config:

.vscode/mcp.json

{
  "servers": {
    "signoz": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Open Copilot Chat in Agent mode and confirm you trust the server.

Go to Settings → Developer → Edit Config and add to claude_desktop_config.json:

claude_desktop_config.json

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Start the MCP server in HTTP mode:

SIGNOZ_URL="<your-signoz-url>" \
SIGNOZ_API_KEY="<your-api-key>" \
TRANSPORT_MODE=http \
MCP_SERVER_PORT=8000 \
LOG_LEVEL=info \
./signoz-mcp-server

Add to claude_desktop_config.json:

claude_desktop_config.json

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

claude mcp add --scope user signoz "<path-to-binary>/signoz-mcp-server" \
  -e SIGNOZ_URL="<your-signoz-url>" \
  -e SIGNOZ_API_KEY="<your-api-key>" \
  -e LOG_LEVEL=info

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Use --scope project to limit to the current project. Remove with claude mcp remove signoz.

codex mcp add signoz \
  --env SIGNOZ_URL="<your-signoz-url>" \
  --env SIGNOZ_API_KEY="<your-api-key>" \
  --env LOG_LEVEL=info \
  -- "<path-to-binary>/signoz-mcp-server"

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Edit ~/.codex/config.toml (global) or .codex/config.toml (project):

config.toml

[mcp_servers.signoz]
command = "<path-to-binary>/signoz-mcp-server"
args = []
 
[mcp_servers.signoz.env]
SIGNOZ_URL = "<your-signoz-url>"
SIGNOZ_API_KEY = "<your-api-key>"
LOG_LEVEL = "info"

For HTTP mode via CLI or config.toml:

codex mcp add signoz --url http://localhost:8000/mcp

[mcp_servers.signoz]
url = "http://localhost:8000/mcp"

Add this configuration to ~/.codeium/windsurf/mcp_config.json

mcp_config.json

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Add to ~/.gemini/settings.json:

settings.json

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Open Zed settings (Cmd+,) and add:

settings.json

{
  "context_servers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Add to mcp_config.json (open via ... menu → MCP Servers → Manage MCP Servers → View raw config):

mcp_config.json

{
  "mcpServers": {
    "signoz": {
      "command": "<path-to-binary>/signoz-mcp-server",
      "args": [],
      "env": {
        "SIGNOZ_URL": "<your-signoz-url>",
        "SIGNOZ_API_KEY": "<your-api-key>",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Add the MCP server via CLI:

grok mcp add signoz "<path-to-binary>/signoz-mcp-server" \
  -e SIGNOZ_URL="<your-signoz-url>" \
  -e SIGNOZ_API_KEY="<your-api-key>" \
  -e LOG_LEVEL=info

Verify these values:

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: The SigNoz API URL reachable from the MCP server
<your-api-key>: The API key from Fetch your API key

Stdio is the default transport, so no -t flag is needed. The server is written to ~/.grok/config.toml; add -s project to write to ./.grok/config.toml instead.

Start the MCP server in HTTP mode.
Add the MCP server via CLI:

grok mcp add -t http signoz http://localhost:8000/mcp

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

config.toml

[mcp_servers.signoz]
url = "http://localhost:8000/mcp"
enabled = true

Use -H "<name>: <value>" on the add command to pass an authentication header if your deployment requires one.

Configuration Reference

Environment variables for the self-hosted MCP server. SigNoz Cloud users do not need to set these.

Variable	Description	Default
`SIGNOZ_URL`	SigNoz API URL reachable from the MCP server; browser links use SigNoz's `global.external_url` when configured	(required for stdio; optional for http with per-request credentials)
`SIGNOZ_API_KEY`	API key for authenticating with SigNoz	(required for stdio; optional for http with per-request credentials)
`TRANSPORT_MODE`	Transport protocol: `stdio` or `http`	`stdio`
`MCP_SERVER_HOST`	Host/interface for the HTTP server. Empty listens on all interfaces; set `127.0.0.1` for loopback-only access	(all interfaces)
`MCP_SERVER_PORT`	Port for HTTP server (when `TRANSPORT_MODE=http`)	`8000`
`MCP_MAX_REQUEST_BYTES`	Max inbound MCP HTTP request body size in bytes (HTTP mode)	`4194304` (4 MiB)
`LOG_LEVEL`	Logging verbosity: `debug`, `info`, `warn`, `error`	`info`
`CLIENT_CACHE_SIZE`	Maximum cached tenant clients in multi-tenant HTTP mode	`256`
`CLIENT_CACHE_TTL_MINUTES`	Tenant-client cache lifetime in minutes	`30`
`SIGNOZ_CUSTOM_HEADERS`	Extra HTTP headers for requests to the configured `SIGNOZ_URL` backend, such as reverse-proxy auth headers. Format: `Key1:Value1,Key2:Value2`	(optional)
`SIGNOZ_INSTANCE_URL_ALLOWLIST`	Multi-tenant HTTP mode only: comma-separated allowed backend hosts. Empty adds no host restriction; the configured `SIGNOZ_URL` is exempt	(no host restriction)
`SIGNOZ_DOCS_REFRESH_INTERVAL`	Refresh interval for the embedded docs sitemap used by `signoz_search_docs` / `signoz_fetch_doc` (Go duration); `0` disables this refresh	`6h`
`SIGNOZ_DOCS_FULL_REFRESH_INTERVAL`	Full refresh interval for the embedded docs corpus (Go duration); `0` disables this refresh	`24h`
`OAUTH_ENABLED`	Enable OAuth 2.1 authentication (`true`/`false`)	`false`
`OAUTH_TOKEN_SECRET`	Encryption key for OAuth tokens (min 32 bytes)	(required when `OAUTH_ENABLED=true`)
`OAUTH_ISSUER_URL`	Public URL of this MCP server	(required when `OAUTH_ENABLED=true`)
`OAUTH_ACCESS_TOKEN_TTL_MINUTES`	Access token lifetime in minutes	`60`
`OAUTH_REFRESH_TOKEN_TTL_MINUTES`	Refresh token lifetime in minutes	`43200` (30d)
`OAUTH_AUTH_CODE_TTL_SECONDS`	Authorization code lifetime in seconds	`600` (10min)
`ANALYTICS_ENABLED`	Enable product analytics (`true`/`false`)	`false`
`SEGMENT_KEY`	Segment write key, used only when analytics is enabled	(optional)
`OTEL_EXPORTER_OTLP_ENDPOINT`	OTLP gRPC endpoint for the MCP server's own traces and metrics; use `http://` for a plaintext collector	(export disabled when unconfigured)
`OTEL_EXPORTER_OTLP_TRACES_ENDPOINT`	Trace-specific OTLP gRPC endpoint; overrides the shared endpoint for traces	(optional)
`OTEL_EXPORTER_OTLP_METRICS_ENDPOINT`	Metrics-specific OTLP gRPC endpoint; overrides the shared endpoint for metrics	(optional)
`OTEL_TRACES_EXPORTER`	Set to `none` to disable internal trace export even with an endpoint configured	(optional)
`OTEL_METRICS_EXPORTER`	Set to `none` to disable internal metric export even with an endpoint configured	(optional)

These OTLP settings instrument the MCP server itself. They do not configure telemetry ingestion from your applications. MCP server logs go to stderr as JSON; the server does not export them over OTLP.

Configure browser links (Optional)

Only needed when SIGNOZ_URL is an internal address that browsers can't open, such as http://signoz:8080. If SIGNOZ_URL is already the URL users open in their browser, skip this section.

Tools return SigNoz links for dashboards, alerts, traces, and other resources. The MCP server builds them from the global.external_url setting it reads from SigNoz (GET /api/v1/global/config), and falls back to SIGNOZ_URL when the setting is unset.

Set it on the SigNoz server, not the MCP server, then restart SigNoz:

SIGNOZ_GLOBAL_EXTERNAL__URL=https://observe.example.com

Or in the SigNoz configuration file:

global:
  external_url: https://observe.example.com

Verify these values:

https://observe.example.com: The URL users open in their browser, including any path prefix.
SIGNOZ_GLOBAL_EXTERNAL__URL: Has two underscores before URL.

Keep SIGNOZ_URL pointed at the API address the MCP server can reach, including any path prefix.

Deploy HTTP mode

The HTTP endpoint is POST /mcp. It is stateless: requests do not need session affinity or a persistent SSE connection. After authentication, GET /mcp returns 405 Method Not Allowed; requests without credentials can return 401 first. Use an MCP client to test the connection.

For a shared deployment, configure OAuth or supply SIGNOZ-API-KEY and X-SigNoz-URL headers per request. Avoid exposing a server configured with a shared API key to untrusted clients. For local use, set MCP_SERVER_HOST=127.0.0.1 to listen only on loopback.

HTTP mode exposes these unauthenticated probe endpoints:

Endpoint	Purpose
`/livez`	Liveness: returns `200` while the process is running
`/readyz`	Readiness: returns `200` after the docs index is ready, otherwise `503`
`/healthz`	Legacy health endpoint with the same readiness check as `/readyz`

Use /livez for Kubernetes liveness probes and /readyz for readiness probes.

Validate

After connecting, verify the server is working:

Open your AI agent.
Ask: "List all alerts" or "Show me all available services".
The agent should return structured results from your SigNoz instance.
Ask for a dashboard or trace link and open the returned link. For Self-Hosted SigNoz, configure the browser URL if the link contains an internal hostname.

Available Tools

The MCP server exposes the following tools to your AI agent:

Each MCP server release targets the latest SigNoz release. If a tool returns 404 from an older self-hosted instance, check the SigNoz and MCP server releases before troubleshooting its parameters.

Tool	Description
`signoz_get_org_overview`	Get the current status and overall posture of your SigNoz deployment, including the org's feature flags
`signoz_list_metrics`	Discover active metric names and catalog metadata such as type, temporality, and unit
`signoz_query_metrics`	Query a known metric for values, trends, breakdowns, or formulas with metric-aware defaults
`signoz_get_top_metrics`	Return top 100 metrics ranked by ingested sample volume with 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, including AI trace fields
`signoz_get_field_values`	Get possible values for a field key
`signoz_list_alerts`	List firing, silenced, or inhibited Alertmanager alert instances
`signoz_list_alert_rules`	List configured alert rules, including inactive or disabled rules; filter by name, label, severity, or state, and sort before paging
`signoz_get_alert`	Get an alert rule definition by ID
`signoz_get_alert_history`	Get a rule's firing and state-transition history (cursor-paginated)
`signoz_create_alert`	Create a threshold, PromQL, or metric anomaly alert rule in the v2alpha1 schema, with direct or policy routing
`signoz_update_alert`	Update an existing alert rule
`signoz_delete_alert`	Delete an alert rule
`signoz_list_dashboards`	List all dashboards with summaries
`signoz_get_dashboard`	Get full dashboard configuration
`signoz_create_dashboard`	Create a new dashboard
`signoz_update_dashboard`	Replace a dashboard with the complete edited definition from `signoz_get_dashboard`
`signoz_patch_dashboard`	Apply a partial JSON Patch to a dashboard without resending the whole definition
`signoz_delete_dashboard`	Delete a dashboard by UUID
`signoz_list_dashboard_templates`	Search the bundled SigNoz dashboard template catalog by technology, such as `postgres` or `kubernetes pod`, so the model can pick one
`signoz_import_dashboard`	Create a dashboard from a curated SigNoz dashboard template by path
`signoz_list_services`	List APM services with trace activity in a time range
`signoz_get_service_top_operations`	Get top operations for a service
`signoz_list_views`	List saved views for Logs, Traces, Metrics, or Cost Meter
`signoz_get_view`	Get a saved Explorer view by UUID
`signoz_create_view`	Create a saved Explorer view
`signoz_update_view`	Replace an existing saved Explorer view
`signoz_delete_view`	Delete a saved Explorer view
`signoz_aggregate_logs`	Aggregate logs with Query Builder expressions such as `count()`, `p99(duration)`, or `countIf(...)`, with grouping and `having`
`signoz_search_logs`	Search logs with flexible filtering; `selectFields` adds fields to each row
`signoz_aggregate_traces`	Aggregate span statistics, or per-trace cost, token, and call counts for AI traces, with grouping and `having`
`signoz_search_traces`	Search span rows, return one row per trace (including AI traces with cost and token counts), or discover trace IDs; `selectFields` adds fields to span rows
`signoz_get_trace_details`	Get a full trace with all spans by trace ID alone; no time range needed
`signoz_get_ai_pricing`	List the AI model prices SigNoz uses to compute span cost, or models seen in the last hour that have no price
`signoz_list_ai_attribute_mappings`	List the attribute mapping groups that turn vendor AI span attributes into `gen_ai.*` keys
`signoz_test_ai_attribute_mapping`	Run sample spans through the AI attribute mappings without saving anything
`signoz_execute_builder_query`	Run Query Builder v5 requests the dedicated tools cannot express, including multi-query requests, formulas, PromQL, and ClickHouse SQL
`signoz_search_docs`	Search official SigNoz docs for product, setup, instrumentation, config, API, deployment, or troubleshooting questions
`signoz_fetch_doc`	Fetch full markdown for one official SigNoz docs page or heading
`signoz_list_notification_channels`	List channel summaries without provider configuration
`signoz_get_notification_channel`	Get one channel's full configuration by ID
`signoz_create_notification_channel`	Create a notification channel; optionally send a test notification
`signoz_update_notification_channel`	Replace a notification channel's full configuration; optionally send a test notification
`signoz_delete_notification_channel`	Delete a notification channel by ID

The server also exposes read-only MCP resources (signoz://... URIs) with schemas, query-builder guides, and payload examples that AI agents read before composing queries and alert, dashboard, view, and notification-channel payloads.

For LLM and agent questions, such as cost per trace or tool-call counts, signoz_search_traces, signoz_aggregate_traces, and signoz_get_field_keys accept queryType: builder_ai_query, the query type the AI Traces Query API uses.

Agents should discover fields before filtering logs or traces, and reuse the current resource definition when making a replacement update. Notification-channel writes default to test=false; use test=true only when a test notification is requested. Tools that return webUrl provide a ready-to-open SigNoz link, so agents can return it directly.

For detailed parameter reference and the full resource list, see the GitHub repository README.

Troubleshooting

Tools not appearing in the AI client

Verify the binary path is correct and the file is executable (self-hosted only).
Set LOG_LEVEL=debug for detailed server logs.

Authentication errors

For SigNoz Cloud: ensure you are using the correct region in the MCP URL.
Confirm your API key is valid and has not expired.
For self-hosted HTTP mode where the client sends the key, use the SIGNOZ-API-KEY: <your-api-key> header.
UNAUTHORIZED means the credentials need attention. For PERMISSION_DENIED, check the service account's role and permissions for the requested operation.

SigNoz Cloud connection issues

Verify the region in the URL matches your account (https://mcp.<region>.signoz.cloud/mcp).
Check your network can reach mcp.<region>.signoz.cloud.
Make sure you completed the authentication flow when prompted.

Server not starting (self-hosted HTTP mode)

Ensure port 8000 is not already in use.
Check that TRANSPORT_MODE=http is set.
Review server logs for startup errors.

Resource links point to an internal address

Configure global.external_url on the SigNoz server as described in Configure browser links, then restart SigNoz. The MCP server may keep a previously discovered URL for up to 15 minutes. Check MCP logs for global-config discovery warnings if links still fall back to SIGNOZ_URL.