signoz
Query SigNoz observability data(metrics, traces, logs, alerts, dashboards, services) via the SigNoz Cloud hosted MCP server.
Open source Open in the app JSON README (API)
About
Query SigNoz observability data(metrics, traces, logs, alerts, dashboards, services) via the SigNoz Cloud hosted MCP server.
Details
- Kind
- Plugins
- Topic
- Cloud & DevOps
- Publisher
- signoz
- Origin
- gemini
- Category
- ferramentas
- Version
- 2026.09.02
- Stars
- 16
- Forks
- 11
- Open pull requests
- 3
- Last push
- 2026-09-02T11:19:55Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-30 14:13:39
- Updated
- 2026-09-02 19:00:43
- Origin id
signoz/agent-skills
README
# SigNoz Agent Skills
Official SigNoz skills and MCP configuration for Claude Code, Codex, Cursor,
VS Code/GitHub Copilot, Gemini CLI, Devin CLI, Grok Build, Antigravity CLI, and
the [skills.sh](https://skills.sh) ecosystem. The repository publishes an
[Agent Plugins v1](https://agent-plugins.org/) package for compatible clients.
The MCP setup skill
includes client-specific recipes for VS Code/GitHub Copilot, Claude Desktop,
Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, and
generic HTTP MCP clients.
## Skills
| Skill | Description |
|-------|-------------|
| [signoz-mcp-setup](plugins/signoz/skills/signoz-mcp-setup/SKILL.md) | Initialize or repair the SigNoz Agent Plugins v1 or client-specific MCP server configuration for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, or another MCP client. |
| [signoz-creating-alerts](plugins/signoz/skills/signoz-creating-alerts/SKILL.md) | Create SigNoz alert rules for threshold breaches, error rates, latency, anomaly detection, and absent-data conditions across metrics, logs, and traces. |
| [signoz-explaining-alerts](plugins/signoz/skills/signoz-explaining-alerts/SKILL.md) | Explain and interpret an existing SigNoz alert rule's configuration, evaluation behavior, notification routing, and recent fire frequency. |
| [signoz-investigating-alerts](plugins/signoz/skills/signoz-investigating-alerts/SKILL.md) | Diagnose why a SigNoz alert fired by correlating its signal with neighbor metrics, traces, and logs around the fire window, and ranking likely causes. |
| [signoz-creating-dashboards](plugins/signoz/skills/signoz-creating-dashboards/SKILL.md) | Create a new SigNoz dashboard from a natural-language intent — import a curated template (PostgreSQL, Redis, JVM, k8s, APM, LLM, etc.) when one fits, or build a custom dashboard with metric, trace, and log panels. |
| [signoz-explaining-dashboards](plugins/signoz/skills/signoz-explaining-dashboards/SKILL.md) | Explain panels, queries, and layout of an existing SigNoz dashboard. |
| [signoz-modifying-dashboards](plugins/signoz/skills/signoz-modifying-dashboards/SKILL.md) | Modify an existing SigNoz dashboard: add, remove, or edit panels, variables, queries, and layout — patching targeted changes rather than replacing the whole dashboard. |
| [signoz-generating-queries](plugins/signoz/skills/signoz-generating-queries/SKILL.md) | Generate queries against SigNoz observability data (traces, logs, metrics). |
| [signoz-writing-clickhouse-queries](plugins/signoz/skills/signoz-writing-clickhouse-queries/SKILL.md) | Optimized ClickHouse queries for SigNoz OpenTelemetry traces and logs. |
| [signoz-searching-docs](plugins/signoz/skills/signoz-searching-docs/SKILL.md) | SigNoz docs guidance for instrumentation, setup, querying, alerts, and APIs. |
| [signoz-managing-views](plugins/signoz/skills/signoz-managing-views/SKILL.md) | Create, list, inspect, update, or delete SigNoz saved Explorer views (logs, traces, metrics) via the SigNoz MCP server. |
| [signoz-setting-up-observability](plugins/signoz/skills/signoz-setting-up-observability/SKILL.md) | Orchestrate the full post-ingestion observability setup for a service — SLI/SLO capture, RED/USE exploration, focused dashboards, saved views, burn-rate and absent-data alerts, and a tuning loop — sequencing the single-artifact skills into one SLO-aware workflow. |
| [signoz-reducing-telemetry-cost](plugins/signoz/skills/signoz-reducing-telemetry-cost/SKILL.md) | Investigate and reduce SigNoz telemetry ingestion cost and metric cardinality across metrics, logs, and traces through the Cost Meter, with dashboard-, alert-, and Infra-page-aware reduction recommendations. |
## Installation
The Agent Plugins v1 `mcp.json` is used by Codex and portable clients. Claude
Code and Cursor use their client-specific MCP registration files. Claude Code
asks for the MCP endpoint URL during install; Codex and Cursor can use
`signoz-mcp-setup` to initialize or repair it. The setup skill accepts a SigNoz
Cloud region such as `us`, `us2`, `eu`, `eu2`, `in`, or `in2`, any hosted MCP
URL, or a self-hosted HTTP `/mcp` endpoint. Plugin updates can reset the bundled
Codex and Cursor registration files to the placeholder; if that happens, rerun
`signoz-mcp-setup`. Claude Code stores its endpoint as a persisted plugin
option, so changing it through the setup skill or **Customize** survives plugin
updates.
The Devin CLI plugin ships skills only — Devin's plugin system does not bundle
MCP servers or prompt for install-time config. Run `signoz-mcp-setup` after
installing to write the `signoz` MCP server into `.devin/config.json`.
The Grok Build plugin bundles an MCP registration that works out of the box on
the SigNoz Cloud `us` endpoint. Grok has no install-time prompt, but unlike the
other bundled registrations it expands `${SIGNOZ_MCP_URL}`, and a
`[mcp_servers.signoz]` entry in Grok's own config replaces the bundled server
rather than duplicating it — so the endpoint survives plugin updates instead of
resetting.
The skills are authored against the current SigNoz MCP server contract. If a
tool call fails because a parameter or schema looks different from what a skill
describes, update or reconfigure the SigNoz MCP server before changing the
workflow.
See the full setup guide in the [SigNoz MCP Server docs](https://signoz.io/docs/ai/signoz-mcp-server/).
### Agent Plugins v1
Agent Plugins v1 standardizes the portable package format but leaves
distribution and installation to individual clients. SigNoz publishes the clean
package from this repository's generated
[`agent-plugin`](https://github.com/SigNoz/agent-skills/tree/agent-plugin)
branch. The client-specific packages below remain supported.
#### VS Code / GitHub Copilot
1. Run **Chat: Install Plugin From Source** from the Command Palette.
2. Enter `https://github.com/SigNoz/agent-skills` and install `signoz` if
prompted.
3. In Copilot Chat Agent mode, run
`/signoz:signoz-mcp-setup <region-or-mcp-url>`, then complete authentication.
For local development, build the same clean package from the compatibility
source tree:
```sh
python3 scripts/package_agent_plugin.py
```
The builder refuses to overwrite an existing output directory. Before
rebuilding, deliberately remove or rename `dist/signoz`, or pass a different
new output path as the command's final argument.
This creates `dist/signoz` containing only `plugin.json`, `mcp.json`, `LICENSE`,
and immediate-child Agent Skills under `skills/`. It can be loaded locally in a
[compatible Agent Plugins client](https://agent-plugins.org/compatible-clients)
for testing. The source tree at [`plugins/signoz`](plugins/signoz) intentionally
also contains native Claude, Codex, Cursor, and Grok files and is not itself a
portable package.
The portable MCP registration starts at `https://not-setup/mcp`, because Agent
Plugins v1 does not define portable install-time configuration or credential
fields. After installing, run `signoz-mcp-setup <region-or-mcp-url>` and complete
the client's OAuth flow for SigNoz Cloud. Portable non-loopback endpoints must
use HTTPS; for a self-hosted HTTP endpoint on another host, the skill configures
the named client's native MCP surface instead.
### Claude Code
```sh
/plugin marketplace add SigNoz/agent-skills
/plugin install signoz@signoz-skills
```
On install, Claude Code prompts for your **SigNoz MCP endpoint**. For SigNoz
Cloud, keep the default `https://mcp.us.signoz.cloud/mcp` or edit the region
segment to your region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`). Find your
region under **Settings -> Ingestion** in SigNoz, or see the
[region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/). For a
self-hosted SigNoz, enter your own HTTP `/mcp` URL, for example
`http://localhost:8000/mcp`.
Then run `/mcp`, select the `signoz` plugin's `mcp` server, and complete the
authentication flow if prompted. To change the endpoint later, reconfigure the
plugin's options or run `signoz-mcp-setup` with the new region or MCP URL.
Update:
```sh
/plugin marketplace update
/plugin update signoz@signoz-skills
```
> The plugin ships a `PreToolUse` hook that auto-allows `WebFetch` to `signoz.io` domains. This does not affect `Bash`-based network calls (`curl`, `wget`), which follow the normal permission flow.
### Codex
```sh
codex plugin marketplace add SigNoz/agent-skills
```
Then, in a Codex session started from your project:
1. Run `/plugins`, open the `SigNoz` marketplace, and install `signoz`.
2. Run `signoz-mcp-setup <region>` with your SigNoz Cloud region (`us`, `us2`,
`eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL. This rewrites the
bundled `mcp.json` placeholder when the endpoint is valid for Agent Plugins.
Non-loopback plain-HTTP endpoints cannot be stored there; for those, the
skill leaves `mcp.json` unchanged and configures the same `signoz` server
through native `codex mcp add` instead.
3. For SigNoz Cloud, or a self-hosted MCP server explicitly configured with
OAuth, authenticate the MCP server:
```sh
codex mcp login signoz
```
Complete the browser flow with your SigNoz instance URL and a service account
API key. For an ordinary self-hosted endpoint without OAuth enabled, skip
this step and continue to verification.
4. Verify the connection:
```sh
codex mcp list # signoz -> enabled, Auth = logged in
```
or run `/mcp` in a session, then call any `signoz_*` tool. Restart Codex if
the `signoz` server does not appear.
The bundled `mcp.json` lives inside Codex's versioned plugin cache, so plugin
updates reinstall that file from this repository and can reset it to the
placeholder. If you want the endpoint to persist across plugin updates, also
add a native Codex MCP entry after resolving the endpoint:
```sh
codex mcp add signoz --url http://localhost:8000/mcp
```
Replace the URL with your SigNoz Cloud MCP URL or self-hosted HTTP `/mcp`
endpoint. Verify with `codex mcp get signoz`.
The Agent Plugins manifest registers the root `mcp.json` for Codex, so normal
plugin installs do not need a separate native Codex MCP entry. To use in another
repo, copy `plugins/signoz` into the target repo's `plugins/` directory, add a
marketplace entry in `$REPO_ROOT/.agents/plugins/marketplace.json`, and repeat
the setup step for that workspace.
### Cursor
Not yet on the public Cursor Marketplace. Install via a Team Marketplace:
1. Add `https://github.com/SigNoz/agent-skills` as a team marketplace in `Settings -> Plugins`.
2. Install the `signoz` plugin from the marketplace panel.
On install, Cursor prompts for your **SigNoz Region**. The picker offers the
SigNoz Cloud regions (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) plus a
**`self-hosted`** option:
- **SigNoz Cloud** — select your region. The bundled MCP config fills it into
`https://mcp.<region>.signoz.cloud/mcp` and Cursor starts the OAuth login.
Find your region under **Settings -> Ingestion** in SigNoz, or see the
[region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/).
- **Self-hosted** — choose `self-hosted`. This skips the Cloud OAuth and leaves
the MCP endpoint unconfigured. After install you **must** run
`/signoz-mcp-setup` with your own HTTP `/mcp` URL (next step) to point Cursor
at your instance.
3. **Self-hosted only:** run `/signoz-mcp-setup` in an agent chat with your
self-hosted HTTP MCP URL (for example `/signoz-mcp-setup http://localhost:8000/mcp`).
This updates the bundled `.signoz_cursor_mcp.json` placeholder used by the
Cursor plugin. (SigNoz Cloud users can skip this — the region picker already
configured the endpoint.)
4. Reload Cursor, then open MCP settings and complete authentication for the
`signoz` server if prompted.
If you picked the wrong region or need to change a self-hosted HTTP MCP
endpoint, run `/signoz-mcp-setup` again with the correct region or URL and
reload Cursor.
### Gemini CLI
```sh
gemini extensions install https://github.com/SigNoz/agent-skills
```
When prompted for the **SigNoz MCP endpoint**, enter:
- **SigNoz Cloud:** `https://mcp.<region>.signoz.cloud/mcp` — replace `<region>` with
your region (`us`, `us2`, `eu`, `eu2`, `in`, or `in2`). The default is the `us`
Cloud endpoint.
- **Self-hosted SigNoz:** your own `/mcp` URL, for example `http://localhost:8000/mcp`.
Then authenticate:
```
/mcp auth signoz
```
Follow the prompts to enter your SigNoz instance URL and API key.
### Devin CLI
```sh
devin plugins install SigNoz/agent-skills
```
This installs at user level and works across all projects. Devin's plugin
system does not support bundled MCP servers or install-time config prompts, so
run `/signoz:signoz-mcp-setup` (Devin namespaces plugin skills as
`/<plugin>:<skill>`) in a Devin session afterward with your SigNoz Cloud
region (`us`, `us2`, `eu`, `eu2`, `in`, `in2`) or a self-hosted HTTP MCP URL.
This writes a `signoz` entry into the highest-precedence Devin config scope
that already has one, or `~/.config/devin/config.json` by default.
For SigNoz Cloud, start a new session and run `devin mcp login signoz` to
complete OAuth. For self-hosted SigNoz, no OAuth step is needed unless the
server runs with `OAUTH_ENABLED=true`.
### Grok Build
```sh
grok plugin marketplace add SigNoz/agent-skills
grok plugin install signoz --trust
```
`--trust` is required for the bundled MCP server and hooks to activate; without
it the skills load but the `signoz` server stays inactive. To skip the
marketplace source, install the plugin subdirectory directly with
`grok plugin install SigNoz/agent-skills#plugins/signoz --trust`.
The plugin registers the `signoz` MCP server against the SigNoz Cloud `us`
endpoint by default, so `us` users need no further configuration.
**Set the endpoint.** For any other region, or for self-hosted SigNoz:
```sh
grok mcp add signoz -t http https://mcp.<region>.signoz.cloud/mcp -s user
```
Replace `<region>` with `us`, `us2`, `eu`, `eu2`, `in`, or `in2`. Find your
region under **Settings -> Ingestion** in SigNoz, or see the
[region reference](https://signoz.io/docs/ingestion/signoz-cloud/keys/). For
self-hosted SigNoz, pass your own HTTP `/mcp` URL, for example
`http://localhost:8000/mcp`. You can also run `/signoz-mcp-setup <region>` in a
Grok session and let the skill do it.
Use `-s user` to write `~/.grok/config.toml` (per machine, the default) or
`-s project` to commit the endpoint to `./.grok/config.toml` for the whole team.
Re-running the command updates the entry in place, so switching regions later is
the same command again. A `[mcp_servers.signoz]` entry **replaces** the
plugin-provided server of the same name, so you always end up with exactly one
`signoz` server rather than a duplicate. For a one-off or CI run, skip config
entirely and export `SIGNOZ_MCP_URL` instead — the bundled registration reads it.
**Authenticate (SigNoz Cloud).** Run `/mcps` (or press Ctrl+L and open the MCP
Servers tab), press `r` to reload after a config change, then select `signoz`
and press `i` to start the OAuth flow. Self-hosted endpoints need no OAuth
unless the server runs with `OAUTH_ENABLED=true`. Verify with
`grok mcp doctor signoz`, which should report `1 healthy`.
Update:
```sh
grok plugin marketplace update
grok plugin update signoz
```
> **Already using SigNoz in Claude Code or Cursor?** Grok also reads
> `~/.claude.json`, `~/.cursor/mcp.json`, and `.mcp.json` as compatibility
> sources. If one of them already defines a `signoz` server, Grok loads it
> *alongside* the plugin's — two live servers with the same name pointing at
> different endpoints, which `grok mcp doctor` reports as two. Setting
> `[mcp_servers.signoz]` with the `grok mcp add` command above outranks both
> and collapses them to one.
### Antigravity CLI
Install directly from this repository — Antigravity CLI stages the repo root as
a native plugin (`plugin.json` + `mcp_config.json` + `skills/`):
```sh
agy plugin install https://github.com/SigNoz/agent-skills
agy plugin list # confirm signoz is loaded
```
Reinstall with the same command to update. Antigravity registers the `signoz`
MCP server (default SigNoz Cloud `us` endpoint, `https://mcp.us.signoz.cloud/mcp`)
and the SigNoz skills automatically. The installed plugin is staged at
`~/.gemini/antigravity-cli/plugins/signoz/`.
**Authenticate (SigNoz Cloud).** In the `agy` prompt, type `/mcp`, select the
`signoz` server, and choose **Authenticate** to start the OAuth flow. Complete
it in the browser (over SSH, `agy` prints an authorization URL to paste in and a
code to paste back). Self-hosted endpoints need no OAuth unless the server runs
with `OAUTH_ENABLED=true`.
**Change the endpoint.** In the `agy` prompt, run the setup skill with your
target — a SigNoz Cloud region or a self-hosted MCP URL:
```
/signoz:signoz-mcp-setup <region> # e.g. us, us2, eu, eu2, in, in2
/signoz:signoz-mcp-setup <mcp-url> # e.g. http://localhost:8000/mcp
```
This rewrites `serverUrl` in the installed `mcp_config.json`. Then run `/mcp` to
reload and re-authenticate (self-hosted needs no OAuth unless the server runs
with `OAUTH_ENABLED=true`). You can also edit the `serverUrl` value directly.
### Other MCP Clients
The setup skill includes native config recipes for VS Code/GitHub Copilot,
Claude Desktop, Gemini CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity
CLI, OpenCode, and generic HTTP MCP clients. These clients do not all consume this plugin
automatically; install or copy the skill where your client supports skills, or
use the client-specific setup snippets in the skill as a reference.
For SigNoz Cloud, prefer the hosted MCP URL and client OAuth flow. For
self-hosted SigNoz, the skill supports HTTP `/mcp` endpoints and stdio
local-binary recipes. It avoids writing API keys into tracked project files.
### skills.sh
```sh
npx skills add SigNoz/agent-skills # all skills
npx skills add SigNoz/agent-skills --skill signoz-searching-docs # specific skill
npx skills add SigNoz/agent-skills --skill signoz-writing-clickhouse-queries # specific skill
```
## Repository Structure
```text
.
├── .agents/plugins/marketplace.json # Codex marketplace
├── .claude-plugin/marketplace.json # Claude Code marketplace
├── .cursor-plugin/marketplace.json # Cursor marketplace
├── .grok-plugin/marketplace.json # Grok Build marketplace
├── .devin-plugin/plugin.json # Devin CLI plugin manifest
├── .github/workflows/
│ ├── auto-version-bump.yml # Follow-up version PR automation
│ ├── publish-agent-plugin.yml # Publishes the generated agent-plugin branch
│ └── validate-agent-plugin.yml # Portable schema and skill checks
├── gemini-extension.json # Gemini CLI extension manifest
├── plugin.json # Antigravity plugin manifest (native, repo root)
├── mcp_config.json # Antigravity MCP config (serverUrl)
├── scripts/package_agent_plugin.py # Builds clean dist/signoz package
├── skills -> plugins/signoz/skills # Gemini CLI, Devin CLI & Antigravity skills (symlink)
├── plugins/signoz/
│ ├── plugin.json # Portable manifest source
│ ├── mcp.json # Portable and Codex MCP config source
│ ├── .codex-plugin/plugin.json # Codex plugin manifest
│ ├── .claude-plugin/plugin.json # Claude Code plugin manifest
│ ├── .cursor-plugin/plugin.json # Cursor plugin manifest
│ ├── .grok-plugin/plugin.json # Grok Build plugin manifest
│ ├── .signoz_claude_mcp.json # Claude Code MCP config
│ ├── .signoz_cursor_mcp.json # Cursor MCP config
│ ├── .signoz_grok_mcp.json # Grok Build MCP config (env-interpolated)
│ ├── hooks/ # Auto-allow hooks
│ └── skills/
│ ├── signoz-mcp-setup/
│ │ └── references/ # Endpoint mapping and client recipes
│ ├── signoz-creating-alerts/
│ ├── signoz-explaining-alerts/
│ ├── signoz-investigating-alerts/
│ ├── signoz-writing-clickhouse-queries/
│ ├── signoz-explaining-dashboards/
│ ├── signoz-modifying-dashboards/
│ ├── signoz-searching-docs/
│ ├── signoz-generating-queries/
│ └── signoz-managing-views/
└── README.md
```
| ID | Value |
|----|-------|
| Marketplace | `signoz-skills` |
| Plugin | `signoz` |
| Repository | `SigNoz/agent-skills` |
| Versioning | Client CalVer `YYYY.MM.DD`; portable/Devin SemVer `YYYY.M.<DD*100+micro>`; auto-bumped |
## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).
## License
MIT. See [LICENSE](./LICENSE).