SigNoz MCP Server

The SigNoz MCP Server implements the Model Context Protocol (MCP) — an open standard that lets AI assistants interact with your SigNoz observability data. Query metrics, traces, logs, alerts, and dashboards through natural language.

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

📝 Note

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

<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:

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

<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:

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

<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

<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:

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

<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:

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

<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:

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

<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:

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

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

Get your API Key

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 → API Keys in SigNoz to create one (requires Admin role)

⚠️ Warning

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

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

Fetch your API key

Log in to your SigNoz instance.
Go to Settings → API Keys.
Click Create API Key and copy the generated key.

⚠️ Warning

Only Admin users can create API keys. Keep your API 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

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

<your-signoz-url>: Your self-hosted SigNoz instance URL (e.g., http://localhost:3301)
<your-api-key>: The API key from Fetch your API key

✅ Info

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:

{
  "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"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL
<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:

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

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

{
  "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"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL
<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:

{
  "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:

{
  "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"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL
<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:

{
  "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

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

✅ Info

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"

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

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

[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"

Add this configuration to ~/.codeium/windsurf/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"
      }
    }
  }
}

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

Add to ~/.gemini/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"
      }
    }
  }
}

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

Open Zed settings (Cmd+,) and add:

{
  "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"
      }
    }
  }
}

<path-to-binary>: Absolute path to the signoz-mcp-server binary
<your-signoz-url>: Your SigNoz instance URL
<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):

{
  "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"
      }
    }
  }
}

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

Configuration Reference

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

Variable	Description	Default
`SIGNOZ_URL`	URL of your SigNoz instance	(required for stdio; optional for http with OAuth)
`SIGNOZ_API_KEY`	API key for authenticating with SigNoz	(required for stdio; optional for http with OAuth)
`TRANSPORT_MODE`	Transport protocol: `stdio` or `http`	`stdio`
`MCP_SERVER_PORT`	Port for HTTP server (when `TRANSPORT_MODE=http`)	`8000`
`LOG_LEVEL`	Logging verbosity: `debug`, `info`, `warn`, `error`	`info`
`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	`1440` (24h)
`OAUTH_AUTH_CODE_TTL_SECONDS`	Authorization code lifetime in seconds	`600` (10min)

Validate

After connecting, verify the server is working:

Open your AI assistant.
Ask: "List all alerts" or "Show me all available services".
The assistant should return structured results from your SigNoz instance.

Available Tools

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

Tool	Description
`signoz_list_metrics`	Search and list available metrics
`signoz_query_metrics`	Query metrics with smart aggregation defaults
`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 all active alerts
`signoz_get_alert`	Get details of a specific alert rule
`signoz_get_alert_history`	Get alert history timeline for a 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`	Update an existing dashboard
`signoz_list_services`	List services within a time range
`signoz_get_service_top_operations`	Get top operations for a service
`signoz_list_log_views`	List all saved log views
`signoz_get_log_view`	Get details of a saved log view
`signoz_aggregate_logs`	Aggregate logs (count, avg, p99, etc.) with grouping
`signoz_search_logs`	Search logs with flexible filtering
`signoz_aggregate_traces`	Aggregate trace statistics with grouping
`signoz_search_traces`	Search traces with flexible filtering
`signoz_get_trace_details`	Get full trace with all spans
`signoz_execute_builder_query`	Execute a raw Query Builder v5 query

For detailed parameter reference, 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, ensure the Authorization header format is Bearer <your-api-key>.

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.

SigNoz MCP Server

Connect to SigNoz's MCP server

Install in one click

Manual Configuration

Install in one click

Manual Configuration

Configure

Configure

Configure

Configure

Configure

Configure

Get your API Key

Fetch your API key

Install the MCP server

Configure your MCP client

Configuration Reference

Validate

Available Tools

Troubleshooting

Tools not appearing in the AI client

Authentication errors

SigNoz Cloud connection issues

Server not starting (self-hosted HTTP mode)

Was this page helpful?

Is this page helpful?