SigNoz MCP Server

SigNoz has released an MCP server that allows AI assistants to query observability data including metrics, traces, logs, alerts, and dashboards through natural language. The server implements the Model Context Protocol and is available as a hosted service on SigNoz Cloud, requiring only a URL and authentication to connect. The tool supports integration with multiple AI platforms including Cursor, VS Code, Claude Desktop, Gemini CLI, and Windsurf.

The SigNoz MCP Server implements the Model Context Protocol MCP https://modelcontextprotocol.io/ — 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 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint . 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint Need help? See the Cursor MCP docs ↗ https://docs.cursor.com/context/model-context-protocol 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint Need help? See the VS Code MCP docs ↗ https://code.visualstudio.com/docs/copilot/chat/mcp-servers Configure You can add SigNoz Cloud as a custom connector in Claude Desktop: - Open Claude Desktop. - Go to Settings → Developer or Features depending on your version . - Click Add Custom Connector or Add Remote MCP Server . - Enter your SigNoz MCP URL: https://mcp.<region .signoz.cloud/mcp <region : Your SigNoz Cloud region https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint When prompted, complete the authentication flow. 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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": { "serverUrl": "https://mcp.<region .signoz.cloud/mcp" } } } <region : Your SigNoz Cloud region https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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. 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 https://signoz.io/docs/manage/administrator-guide/iam/service-accounts/ for details. 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. { "mcpServers": { "signoz": { "url": "https://mcp.<region .signoz.cloud/mcp", "headers": { "SIGNOZ-API-KEY": "<your-api-key ", "X-SigNoz-URL": "<your-signoz-instance-url " } } } } <region : Your SigNoz Cloud region https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint <your-api-key : API key from SigNoz Service accounts https://signoz.io/docs/manage/administrator-guide/iam/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 . 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 https://signoz.io/docs/manage/administrator-guide/iam/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 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 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 fetch-your-api-key Docker always runs in HTTP transport mode. Use the HTTP tabs in the client setup below. git clone https://github.com/SigNoz/signoz-mcp-server.git cd signoz-mcp-server make build The binary is at ./bin/signoz-mcp-server . 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 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 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 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 fetch-your-api-key Use --scope project to limit to the current project. Remove with claude mcp remove signoz . - Start the MCP server in HTTP mode. - Add via CLI: claude mcp add --scope user --transport http signoz http://localhost:8000/mcp 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 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 fetch-your-api-key - Start the MCP server in HTTP mode. - Edit ~/.codeium/windsurf/mcp config.json : { "mcpServers": { "signoz": { "serverUrl": "http://localhost:8000/mcp" } } } 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 fetch-your-api-key - Start the MCP server in HTTP mode. - Add to ~/.gemini/settings.json : { "mcpServers": { "signoz": { "httpUrl": "http://localhost:8000/mcp" } } } 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 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 fetch-your-api-key - Start the MCP server in HTTP mode. - Add to mcp config.json : { "mcpServers": { "signoz": { "serverUrl": "http://localhost:8000/mcp" } } } 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 | SIGNOZ CUSTOM HEADERS | Extra HTTP headers added to every SigNoz API request, such as reverse-proxy auth headers. Format: Key1:Value1,Key2:Value2 | optional | SIGNOZ DOCS REFRESH INTERVAL | Refresh interval for the embedded docs sitemap used by signoz search docs / signoz fetch doc Go duration | 6h | SIGNOZ DOCS FULL REFRESH INTERVAL | Full refresh interval for the embedded docs corpus Go duration | 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 | 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 Available Tools available-tools The MCP server exposes the following tools to your AI assistant: Alert-rule and notification-channel tools use newer SigNoz rules and channels APIs. Use SigNoz v0.120.0 or later for full compatibility with the latest MCP server. Older SigNoz deployments may return HTTP 404 for those tools. | 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 firing, silenced, or inhibited Alertmanager alert instances | signoz list alert rules | List configured alert rules, including inactive or disabled rules | signoz get alert | Get an alert rule definition by ID | signoz get alert history | Get alert history timeline for a rule | signoz create alert | Create an alert rule using v2 schema validation | 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 | Update an existing dashboard | signoz delete dashboard | Delete a dashboard by UUID | signoz list dashboard templates | List the bundled SigNoz dashboard template catalog so the model can pick one | signoz import dashboard | Create a dashboard from a curated SigNoz dashboard template by path | signoz list services | List services within a time range | signoz get service top operations | Get top operations for a service | signoz list views | List saved Explorer views for traces, logs, or metrics | 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 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 | 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 notification channels | signoz get notification channel | Get a single notification channel by ID | signoz create notification channel | Create a notification channel and send a test notification | signoz update notification channel | Update a notification channel and send a test notification | signoz delete notification channel | Delete a notification channel by ID | For detailed parameter reference, see the GitHub repository README https://github.com/SigNoz/signoz-mcp-server?tab=readme-ov-file available-tools . Troubleshooting Troubleshooting 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 https://signoz.io/docs/ingestion/signoz-cloud/overview/ endpoint 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. 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.