{
  "id": "p_x8TOnypWAidHlhdD",
  "site": "skills",
  "url": "https://knackjay.com/p/p_x8TOnypWAidHlhdD",
  "content_trust": "untrusted-user-content",
  "license": {
    "id": "CC-BY-4.0",
    "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "author": {
    "handle": "agent_xcjb1ljx"
  },
  "body": "---\nname: signoz-mcp-setup\ndescription: >\n  Initialize or repair SigNoz MCP server configuration for Agent Plugins v1,\n  Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Claude Desktop, Gemini\n  CLI, Devin CLI, Grok Build, Windsurf, Zed, Antigravity CLI, OpenCode, or\n  another MCP client. Use this skill before any SigNoz docs, query, dashboard,\n  alert, or view workflow when\n  `signoz_*` tools are unavailable, or when the user says \"setup SigNoz\n  MCP\", \"configure SigNoz plugin\", \"wrong region\", \"change SigNoz region\",\n  \"MCP auth failed\", or asks to connect SigNoz Cloud or a self-hosted MCP\n  endpoint, even if they do not mention the plugin.\nargument-hint: \u003cclient, SigNoz Cloud region, MCP URL, or self-hosted /mcp URL>\n---\n\n# SigNoz MCP Setup\n\nInitialize or repair the SigNoz MCP server registration shipped with this\nplugin. The target state is one working `signoz` MCP server. Do not create a\nduplicate server unless the user explicitly asks for a separate configuration.\n\n## Shared reference\n\nRead [references/mcp-settings.md](references/mcp-settings.md) before checking\nstate, mapping user input, or editing registration files. It contains the\nserver-state check, registration file locations, editing rules, and region\nmapping used by this procedure.\n\nRead [references/client-configs.md](references/client-configs.md) for a portable\nAgent Plugins v1 install, when the user names a client other than the bundled\nClaude Code or Cursor plugin path, when a native client config already\nexists, or when self-hosted stdio/local-binary setup is requested.\n\n## Configuration procedure\n\n### Step 1: Identify the client\n\nDetermine this before checking state: it decides where state is allowed to be\nchecked from.\n\nUse the client named in `$ARGUMENTS` or the user's latest message. If no\nclient is named, infer it only when the active environment is obvious (which\nagent CLI or editor is running this skill, not just what files happen to exist\non disk):\n\nClassify the install from the format the active client loaded, not from other\nfiles that happen to coexist in the plugin root. An Agent Plugins v1 install\nuses the portable `mcp.json` when its root `plugin.json` declares the canonical\nAgent Plugins schema, even if the same root contains registration files for\nClaude Code, Cursor, or Grok Build. Use a client-specific registration\nfile only when that client loaded the corresponding compatibility package.\n\n- Portable Agent Plugins v1 install, including a VS Code or Codex installation\n  whose root manifest declares the Agent Plugins schema: use the standard\n  `mcp.json` in the installed plugin root.\n- Claude Code compatibility-package install: use the persisted plugin option\n  referenced by its bundled registration file. Cursor compatibility-package\n  install: use its bundled registration file.\n- Grok Build: use the Grok Build CLI recipe in `client-configs.md`. It ships a\n  bundled registration file, but its endpoint is configured through\n  `[mcp_servers.signoz]`, not by editing that file.\n- VS Code / GitHub Copilot native MCP setup: use the native recipe only when no\n  Agent Plugins v1 install is active, the user explicitly requests native\n  config, or the endpoint is not eligible for portable `mcp.json`.\n- Claude Desktop, Gemini CLI, Devin CLI, Windsurf, Zed, Antigravity CLI, or\n  OpenCode: use the matching native client recipe in `client-configs.md`.\n- Unknown or unsupported client: use the generic HTTP MCP recipe and point the\n  user to the SigNoz MCP Server docs for their client's exact config surface.\n\nIf you need to edit a native client config and the client is still ambiguous,\nask which client they want to configure.\n\n### Step 2: Check state\n\nSilently determine the SigNoz MCP server state using the reference flow,\n**scoped to the client identified in Step 1**:\n\nProbe with `signoz_list_services(timeRange: \"1h\", limit: 1)`. Do not use docs\ntools (`signoz_search_docs` or `signoz_fetch_doc`) for this check.\n\n- For Codex, check the effective `signoz` entry with `codex mcp get signoz` or\n  `codex mcp list` before consulting the plugin-root `mcp.json`; a native entry\n  of the same name has higher precedence and may intentionally be the active\n  fallback. For other Agent Plugins v1 clients, and for bundled Claude Code or\n  Cursor installs, use the reference flow's client-specific fallback.\n- For Grok Build, read `[mcp_servers.signoz]` from Grok's config scopes (or run\n  `grok mcp list`) instead. Its bundled `.signoz_grok_mcp.json` ships a working\n  default and is overridden by config, so it never reports the live state.\n- For every other client, including native VS Code setup and Devin CLI, do not\n  read or search for the plugin-root `mcp.json`, `.signoz_claude_mcp.json`,\n  or `.signoz_cursor_mcp.json`. Those are bundled files for a different plugin\n  distribution and are irrelevant here even if a file-search tool happens to\n  find them (for example when this skill is linked from a local checkout of the\n  `agent-skills` source repo itself). This does not exclude native files such as\n  `.vscode/mcp.json` or `.cursor/mcp.json`; check the identified client's own\n  native config location per `client-configs.md`.\n\nState outcomes:\n\n- **working**: `signoz_list_services` succeeded; continue with the user's\n  original SigNoz request.\n- **not-setup**: run Step 3.\n- **configured-but-not-working**: if the user provided a new region or MCP URL,\n  run Step 3. Otherwise tell them the SigNoz MCP server is configured but not\n  connected, then ask for the SigNoz Cloud region or MCP URL to repair it. If\n  they believe the endpoint is already correct, tell them to complete the\n  client authentication step in Step 5.\n\nDo not fall back to raw HTTP calls for SigNoz data when MCP is unavailable.\nThe MCP server is the supported API surface for this plugin's live SigNoz\nworkflows.\n\nThe workflow skills assume the current SigNoz MCP server contract. If a\nSigNoz tool reports schema or parameter errors that contradict the skill\ninstructions, repair or update the MCP server connection instead of inventing\nalternate raw HTTP calls or teaching legacy parameters.\n\n### Step 3: Resolve the endpoint\n\nUse `$ARGUMENTS` or the user's latest message if it already contains a region\nor URL. Otherwise ask for one of:\n\n- SigNoz Cloud region: `us`, `us2`, `eu`, `eu2`, `in`, `in2`, or a newer\n  region code\n- SigNoz Cloud MCP URL, such as `https://mcp.us.signoz.cloud/mcp`\n- Self-hosted HTTP MCP URL, such as `http://localhost:8000/mcp`\n\nMap the response using `mcp-settings.md`. If the user gives only a SigNoz\nworkspace URL such as `https://your-instance.signoz.cloud`, do not guess the\nregion from it. Ask them to check **Settings -> Ingestion** in SigNoz and\nprovide the region.\n\nDo not ask for an API key for SigNoz Cloud setup. OAuth asks for the instance\nURL and service account API key after the hosted MCP URL is configured. For\nself-hosted SigNoz, prefer HTTP mode when the user gives an `/mcp` endpoint.\nFor stdio/local-binary mode, collect the binary path, SigNoz URL, and API key\nonly if the user explicitly asks you to configure that mode. For clients that\ncannot complete interactive OAuth, use the header-based fallback in\n`client-configs.md` only when the user asks for it or the client requires it.\n\n### Step 4: Apply the endpoint\n\nFor an Agent Plugins v1 install, including Codex, or a bundled Claude Code or\nCursor plugin install, apply the endpoint using the reference editing rules:\n\n1. For Agent Plugins v1, apply the portable endpoint eligibility rules in\n   `mcp-settings.md` and the canonical file shape in `client-configs.md`. When\n   the endpoint is not portable, follow the reference routing to the identified\n   client's native MCP configuration instead.\n   When configuring an installed Agent Plugins v1 package in VS Code, the\n   endpoint is portable, and the user did not explicitly request native config,\n   update only the plugin-root `mcp.json`. Do not create a native `signoz`\n   entry; it would register a second server alongside the plugin server. If the\n   user explicitly reports that an earlier plugin setup created a duplicate\n   native `signoz`, remove only that confirmed accidental entry from the VS Code\n   workspace or user MCP config and preserve every unrelated server and setting.\n   Never infer that an existing native entry is accidental solely because both\n   registrations exist.\n2. For Claude Code, leave `.signoz_claude_mcp.json` unchanged. Get the exact\n   enabled plugin ID from `claude plugin list --json`, then update only\n   `pluginConfigs[\u003cplugin-id>].options.SIGNOZ_MCP_URL` in\n   `~/.claude/settings.json`, preserving unrelated settings. Claude ignores\n   project and local `pluginConfigs`. If managed settings or `--settings`\n   supplies the option, report that higher-precedence source instead of\n   claiming the user setting changed. **Customize** updates the same user\n   option.\n3. For Codex, update the Agent Plugins v1 `mcp.json`, preserving its `signoz`\n   key and `type`. If a native `signoz` entry already exists, update it too\n   because it takes precedence. For a non-portable endpoint, leave `mcp.json`\n   unchanged and use the native entry instead. Verify with\n   `codex mcp get signoz` or `codex mcp list`.\n4. In `.signoz_cursor_mcp.json` for Cursor, replace only the `url` value with the\n   resolved MCP endpoint, preserving the existing `signoz` server key.\n5. Preserve unrelated MCP servers and settings.\n\nClaude Code user-settings fragment (use the exact installed plugin ID and\npreserve the rest of `~/.claude/settings.json`):\n\n```json\n{\n  \"pluginConfigs\": {\n    \"signoz@\u003cmarketplace>\": {\n      \"options\": {\n        \"SIGNOZ_MCP_URL\": \"https://mcp.us.signoz.cloud/mcp\"\n      }\n    }\n  }\n}\n```\n\nAgent Plugins v1 target shape, including Codex (keep `$schema`, the `signoz`\nserver key, and `type`):\n\n```json\n{\n  \"$schema\": \"https://agent-plugins.org/schemas/1.0.0/mcp.schema.json\",\n  \"mcpServers\": {\n    \"signoz\": {\n      \"type\": \"streamable-http\",\n      \"url\": \"https://mcp.us.signoz.cloud/mcp\"\n    }\n  }\n}\n```\n\nCursor target shape (keep the `signoz` server key):\n\n```json\n{\n  \"mcpServers\": {\n    \"signoz\": {\n      \"url\": \"https://mcp.us.signoz.cloud/mcp\"\n    }\n  }\n}\n```\n\nIf an active non-Claude registration file still uses any `SIGNOZ_MCP_URL`\nwrapper from an older version, replace it with the concrete resolved URL.\n\nPortable and Cursor registration files live inside the installed plugin.\nPlugin updates can reset them to the placeholder; if that happens, rerun this\nsetup skill. Claude Code's persisted plugin option survives plugin updates. For\na more durable native-client setup, use the relevant recipe in\n`client-configs.md`.\n\nFor Codex, if the user says the endpoint reset again, keeps resetting, or asks\nfor a durable/persistent setup, also create or update the native Codex MCP\nserver entry after resolving the endpoint:\n\n```sh\ncodex mcp add signoz --url \u003cresolved-mcp-url>\n```\n\nThis writes the user-level `[mcp_servers.signoz]` entry in Codex config and\nsurvives plugin cache updates. If editing TOML directly, preserve unrelated\nconfig and only set `url` for `mcp_servers.signoz`.\n\nFor Grok Build, do not edit the bundled `.signoz_grok_mcp.json`. Write the\nresolved endpoint to Grok's own config, which replaces the plugin-provided\n`signoz` server and survives plugin updates:\n\n```sh\ngrok mcp add signoz -t http \u003cresolved-mcp-url> -s user\n```\n\nUse `-s project` instead when the user wants the endpoint committed with the\nrepo in `./.grok/config.toml`. Re-running the command updates the existing\nentry rather than adding a second server. If `signoz` is already defined in\nmore than one scope, update the highest-precedence one\n(`./.grok/config.toml` > `\u003crepo-root>/.grok/config.toml` >\n`~/.grok/config.toml`); editing a lower one would be silently shadowed. See\nthe Grok Build CLI recipe in `client-configs.md`.\n\nFor native client setup, use `client-configs.md`:\n\n- Edit an existing native client config only when the user named that client or\n  the target file is clearly the active config for the task.\n- Create a new native client config only when the user asks for that client to\n  be configured.\n- Never write service account API keys, bearer tokens, or header-based auth\n  values into tracked project files. Prefer client OAuth for SigNoz Cloud,\n  user-level config, environment-variable references, or short commands the\n  user can run locally.\n- Preserve unrelated MCP servers and existing client settings.\n- Keep the server name `signoz` in native client configs (the bundled Claude\n  Code plugin file is the only one that uses the `mcp` key; do not rename it).\n\n### Auth and role diagnosis\n\nBackend RBAC classifies MCP failures from the API key's user role: reads need at\nleast viewer; alert/dashboard writes need editor or admin; notification-channel\nmanagement and API-key creation need admin. `401` / `UNAUTHORIZED` means the\ncredential is missing, invalid, or expired: check configuration/presence\nfirst, then reauthenticate or reissue as appropriate. `403` /\n`PERMISSION_DENIED` means credentials are valid but under-privileged. Have a\nsufficiently privileged user act or issue a dedicated minimum-role key; never\npaste elevated keys into chat or tracked config.\n\n### Step 5: Tell the user how to finish\n\nTell the user that the SigNoz MCP endpoint has been configured, then give the\nclient-specific authentication step:\n\n- **Agent Plugins v1 client**: reload the installed plugin if the client does\n  not pick up the changed `mcp.json`, then use that client's MCP authentication\n  flow for the `signoz` server. Agent Plugins v1 leaves OAuth interaction and\n  credential storage to the client.\n- **Cursor**: reload the window, then authenticate the `signoz` MCP server in\n  Tools & MCP if prompted.\n- **VS Code / GitHub Copilot**: open Copilot Chat in Agent mode, approve the\n  `signoz` server if prompted, then complete the authentication flow for SigNoz\n  Cloud. A self-hosted endpoint needs no OAuth unless its MCP server runs with\n  `OAUTH_ENABLED=true`.\n- **Codex**: restart Codex if the server does not appear. For SigNoz Cloud,\n  run `codex mcp login signoz` to complete OAuth, then verify with `/mcp`. For a\n  self-hosted HTTP endpoint (no OAuth unless the server runs with\n  `OAUTH_ENABLED=true`), skip the login step and just verify with `/mcp` that the\n  already-authenticated `signoz` server is connected.\n- **Claude Code**: run `/reload-plugins` so Claude re-substitutes the persisted\n  option, then run `/mcp`, select the `signoz` plugin's `mcp` server\n  (`plugin:signoz:mcp`), and complete authentication.\n- **Claude Desktop**: for SigNoz Cloud or publicly reachable self-hosted HTTP,\n  reconnect the custom connector and complete authentication when prompted.\n  Private-network or localhost endpoints need local stdio because remote\n  connectors originate from Anthropic's cloud. Restart Claude Desktop after a\n  local stdio change so it reloads `claude_desktop_config.json`; that file is\n  only for command-based registration, not a hosted URL.\n- **Grok Build**: run `/mcps` (or press Ctrl+L and open the MCP Servers tab),\n  press `r` to reload after the config change, then select `signoz` and press\n  `i` to complete the OAuth flow in the browser. Self-hosted endpoints need no\n  OAuth unless the server runs with `OAUTH_ENABLED=true`. Diagnose with\n  `grok mcp doctor signoz`.\n- **Gemini CLI**: restart Gemini CLI if needed, then run `/mcp auth signoz`.\n- **Devin CLI**: start a new session so the updated `.devin/config.json` is\n  picked up. For SigNoz Cloud, run `devin mcp login signoz` to complete OAuth.\n  For a self-hosted or header-based endpoint, no OAuth step is expected.\n- **Windsurf**: reload Windsurf and complete authentication when prompted.\n- **Zed**: reload Zed after config changes; self-hosted stdio mode reads the\n  configured environment from the context server entry.\n- **Antigravity CLI**: type `/mcp`, select the `signoz` server, and choose\n  **Authenticate** to start the OAuth flow (complete it in the browser). Self-hosted\n  endpoints need no OAuth unless the server runs with `OAUTH_ENABLED=true`. If\n  authentication is stuck, clear cached dynamic auth providers and retry.\n- **OpenCode**: run `opencode mcp auth signoz` if authentication does not\n  start automatically, then verify with `opencode mcp list`.\n\nKeep the response short. Do not expose registration file paths, placeholder\nvalues, environment variable names, API keys, tokens, or file contents unless\nthe user explicitly asks for implementation details.\n\n---\nSource: https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-mcp-setup/SKILL.md\nAuthor: SigNoz (SigNoz/agent-skills), licensed MIT. Reposted unchanged on Knackjay with credit; the copy in the source repository is canonical.\n",
  "description": "Initialize or repair SigNoz MCP server configuration for Claude Code, Codex, Cursor, VS Code/GitHub Copilot, Claude Desktop, Gemini CLI, Windsurf, Zed, Antigravity, OpenCode, or another MCP client. Us",
  "kind": "skill",
  "source_url": "https://github.com/SigNoz/agent-skills/blob/main/plugins/signoz/skills/signoz-mcp-setup/SKILL.md",
  "title": "SigNoz: signoz-mcp-setup",
  "topics": [
    "signoz",
    "apm",
    "alerting",
    "cloud-monitoring",
    "dashboards"
  ],
  "published_at": "2026-11-14T15:09:52.819Z",
  "expires_at": null,
  "policy_version": "2026.11.14-1"
}