cd /news/ai-tools/signoz-mcp-server · home › topics › ai-tools › article
[ARTICLE · art-16605] src=signoz.io pub= topic=ai-tools verified=true sentiment=↑ positive

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.

read13 min publishedMay 27, 2026

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

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 underSettings → Ingestion in SigNoz, or see theregion 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 Cloudregion

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 Cloudregion

Need help? See the VS Code MCP docs ↗

Configure

You can add SigNoz Cloud as a custom connector in Claude Desktop:

  • Open Claude Desktop.
  • Go to Settings→** Developer**(or** Featuresdepending on your version). - Click Add Custom Connector orAdd Remote MCP Server**. - Enter your SigNoz MCP URL: https://mcp.<region>.signoz.cloud/mcp

<region>

: Your SigNoz Cloudregion

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 Cloudregion

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 Cloudregion

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 Cloudregion

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 Cloudregion

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 Cloudregion

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 Accountsin SigNoz, create a service account, and generate an API key (requires Admin**role). SeeService Accountsfor 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 Cloudregion<your-api-key>

: API key fromSigNoz 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, clickAdd Key, and copy the generated key. SeeService Accountsfor 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:

curl -L https://github.com/SigNoz/signoz-mcp-server/releases/latest/download/signoz-mcp-server_darwin_arm64.tar.gz | tar xz

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

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 fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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 thesignoz-mcp-server

binary<your-signoz-url>

: Your SigNoz instance URL<your-api-key>

: The API key fromFetch 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

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.

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

source & further reading
signoz.io — original article AI Tools and Skills MCP Use Cases Monitor Kubernetes CronJobs
── more in #ai-tools 4 stories · sorted by recency
sponsored brought to you by zahid.host 4,200+ EU-deployed projects
reading about agents? ship yours in a single git push.

Run your AI side-project on zahid.host

EU-based hosting, git-push deploys, automatic HTTPS, no cold starts. Free tier with a custom domain — perfect for shipping the agent you just read about.

$git push zahid main
→ Live at https://your-agent.zahid.host ✓
Get free account → Pricing
from €0/mo · no card required
LIVE [news/signoz-mcp-server] indexed:0 read:13min 2026-05-27 · —