# SigNoz MCP Server

Connect Claude, Cursor, Copilot, and other AI agents to SigNoz via MCP for natural language access to metrics, logs, traces, and alerts.

> For the complete documentation index, see [llms.txt](https://signoz.io/llms.txt). Markdown versions are also available by appending `.md` to documentation URLs.

Tags: SigNoz Cloud, Self-Host

The SigNoz MCP Server implements the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/), an open standard that lets AI agents interact with your SigNoz observability data. Query metrics, traces, logs, alerts, and dashboards through natural language.

The MCP server works best with the [SigNoz plugin](https://signoz.io/docs/ai/agent-skills/#install-the-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.

**Already configured?**

If you've already set up the MCP server, skip ahead to the [use cases](https://signoz.io/docs/ai/use-cases/) to see what you can do with it.

## Connect to SigNoz's MCP server

### SigNoz Cloud

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](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint).

### Cursor

### Install in one click

- [Add to Cursor (US)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC51cy5zaWdub3ouY2xvdWQvbWNwIn0=)
- [Add to Cursor (EU)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC5ldS5zaWdub3ouY2xvdWQvbWNwIn0=)
- [Add to Cursor (IN)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC5pbi5zaWdub3ouY2xvdWQvbWNwIn0=)
- [Add to Cursor (US2)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC51czIuc2lnbm96LmNsb3VkL21jcCJ9)
- [Add to Cursor (EU2)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC5ldTIuc2lnbm96LmNsb3VkL21jcCJ9)
- [Add to Cursor (IN2)](cursor://anysphere.cursor-deeplink/mcp/install?name=SigNoz\&config=eyJ1cmwiOiJodHRwczovL21jcC5pbjIuc2lnbm96LmNsb3VkL21jcCJ9)

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

### VS Code / GitHub Copilot

### Install in one click

- [Add to VS Code (US)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.us.signoz.cloud%2Fmcp%22%7D%7D)
- [Add to VS Code (EU)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.eu.signoz.cloud%2Fmcp%22%7D%7D)
- [Add to VS Code (IN)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.in.signoz.cloud%2Fmcp%22%7D%7D)
- [Add to VS Code (US2)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.us2.signoz.cloud%2Fmcp%22%7D%7D)
- [Add to VS Code (EU2)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.eu2.signoz.cloud%2Fmcp%22%7D%7D)
- [Add to VS Code (IN2)](vscode:mcp/install?%7B%22name%22%3A%22signoz%22%2C%22config%22%3A%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.in2.signoz.cloud%2Fmcp%22%7D%7D)

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

### Claude Desktop

### Configure

You can 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`

- `<region>`: Your SigNoz Cloud [region](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint)

When prompted, complete the authentication flow.

### Claude Code

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

### OpenAI Codex

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

### Gemini CLI

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

### Windsurf

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

### Antigravity

### Configure

1. Open the **MCP Store** via the `...` menu in the agent panel.
2. Click **Manage MCP Servers**.
3. 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.

### Grok Build

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

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

- `<region>`: Your SigNoz Cloud [region](https://signoz.io/docs/ingestion/signoz-cloud/overview/#endpoint)

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:

1. Your **SigNoz instance URL** (e.g., `https://your-instance.signoz.cloud`)
2. 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.

> **Info: How authentication works?**
>
> 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.

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

> **Info: When to use header-based authentication?**
>
> 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

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

### Self-Hosted

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

1. Log in to your SigNoz instance.
2. Go to **Settings** → **Service Accounts**.
3. 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.

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

### Install the MCP server

### Download Binary (Recommended)

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

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

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

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

### Configure your MCP client

### Cursor

### Stdio (Recommended)

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)

### HTTP

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

2. Add to `.cursor/mcp.json`:

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

### VS Code / GitHub Copilot

### Stdio (Recommended)

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.

### HTTP

1. Start the MCP server in HTTP mode.
2. 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.

### Claude Desktop

### Stdio (Recommended)

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)

### HTTP

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

2. Add to `claude_desktop_config.json`:

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

### Claude Code

### Stdio (Recommended)

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

> **Info**
>
> Use `--scope project` to limit to the current project. Remove with `claude mcp remove signoz`.

### HTTP

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

```
claude mcp add --scope user --transport http signoz http://localhost:8000/mcp
```

### OpenAI Codex

### CLI (Recommended)

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

### config.toml

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

**HTTP mode**

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

### Windsurf

### Stdio (Recommended)

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)

### HTTP

1. Start the MCP server in HTTP mode.
2. Edit `~/.codeium/windsurf/mcp_config.json`:

```
{
  "mcpServers": {
    "signoz": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}
```

### Gemini CLI

### Stdio (Recommended)

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)

### HTTP

1. Start the MCP server in HTTP mode.
2. Add to `~/.gemini/settings.json`:

```
{
  "mcpServers": {
    "signoz": {
      "httpUrl": "http://localhost:8000/mcp"
    }
  }
}
```

### Zed

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)

### Antigravity

### Stdio (Recommended)

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)

### HTTP

1. Start the MCP server in HTTP mode.
2. Add to `mcp_config.json`:

```
{
  "mcpServers": {
    "signoz": {
      "serverUrl": "http://localhost:8000/mcp"
    }
  }
}
```

### Grok Build

### Stdio (Recommended)

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

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

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.

### HTTP

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

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

Or add to `~/.grok/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`                        | 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_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 added to every SigNoz API request, such as reverse-proxy auth headers. Format: `Key1:Value1,Key2:Value2`    | *(optional)*                                         |
| `SIGNOZ_INSTANCE_URL_ALLOWLIST`     | Multi-tenant HTTP mode only: comma-separated allowlist of SigNoz backend hosts the server will proxy to. Empty allows any host | *(any host)*                                         |
| `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:

1. Open your AI agent.
2. Ask: *"List all alerts"* or *"Show me all available services"*.
3. The agent should return structured results from your SigNoz instance.

## Available Tools

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

> **Note**
>
> Some tools use newer SigNoz APIs. Dashboard tools (create/get/update/patch/list/delete/import) require SigNoz v0.135.0 or later because they use the v2 dashboards API. `signoz_check_metric_usage` needs v0.135.0 for dashboard usage; its alert usage works from v0.131.0. Alert-rule list/get/create/update/delete tools require v0.120.0 or later, and `signoz_get_alert_history` requires v0.118.0 or later. Notification-channel tools also use newer channels APIs. Older SigNoz deployments may return HTTP 404 from affected tools.

| Tool                                 | Description                                                                                                                            |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `signoz_get_org_overview`            | Get the current status and overall posture of your SigNoz deployment                                                                   |
| `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                                                                             |
| `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 a rule's firing and state-transition history (cursor-paginated)                                                                    |
| `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_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`    | 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 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 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`       | 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 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                                                                                                    |

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

For detailed parameter reference and the full resource list, see the [GitHub repository README](https://github.com/SigNoz/signoz-mcp-server?tab=readme-ov-file#available-tools).

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

More docs: /docs/sitemap.md