signoz-mcp-setup

SigNoz MCP 配置

初始化或修复此插件附带的 SigNoz MCP 服务注册。目标状态是拥有一个可正常工作的 signoz MCP 服务。除非用户明确要求单独配置，否则不要创建重复服务。

共享参考

在检查状态、映射用户输入或编辑注册文件之前，请阅读 references/mcp-settings.md。其中包含此流程使用的服务状态检查、注册文件位置、编辑规则和区域映射。

如果用户要求安装便携式 Agent Plugins v1、指定的客户端不是捆绑的 Claude Code 或 Cursor 插件路径、已有原生客户端配置，或用户要求配置自托管 stdio／本地二进制文件，请阅读 references/client-configs.md。

配置流程

步骤 1：识别客户端

在检查状态之前确定客户端：这决定了允许从何处检查状态。

使用 $ARGUMENTS 或用户最新消息中指定的客户端。如果未指定客户端，仅当活动环境明确时才推断（即运行此技能的 Agent CLI 或编辑器，而不只是磁盘上碰巧存在的文件）：

根据活动客户端加载的格式对安装进行分类，而不是根据插件根目录中碰巧共存的其他文件进行分类。如果根目录的 plugin.json 声明了规范的 Agent Plugins 架构，则 Agent Plugins v1 安装使用便携式 mcp.json，即使同一根目录中包含 Claude Code、Cursor 或 Grok Build 的注册文件也一样。只有当客户端加载了对应的兼容包时，才使用特定客户端的注册文件。

• 便携式 Agent Plugins v1 安装，包括根清单声明 Agent Plugins 架构的 VS Code 或 Codex 安装：使用已安装插件根目录中的标准 mcp.json。
• Claude Code 兼容包安装：使用其捆绑注册文件引用的持久化插件选项。Cursor 兼容包安装：使用其捆绑注册文件。
• Grok Build：使用 client-configs.md 中的 Grok Build CLI 配置方案。它附带捆绑注册文件，但其端点通过 [mcp_servers.signoz] 配置，而不是通过编辑该文件配置。
• VS Code／GitHub Copilot 原生 MCP 配置：仅当没有启用 Agent Plugins v1 安装、用户明确要求原生配置，或端点不符合便携式 mcp.json 的适用条件时，才使用原生配置方案。
• Claude Desktop、Gemini CLI、Devin CLI、Windsurf、Zed、Antigravity CLI 或 OpenCode：使用 client-configs.md 中对应的原生客户端配置方案。
• 未知或不受支持的客户端：使用通用 HTTP MCP 配置方案，并引导用户查阅 SigNoz MCP Server 文档，了解其客户端的具体配置方式。

如果需要编辑原生客户端配置，但客户端仍不明确，请询问用户要配置哪个客户端。

步骤 2：检查状态

按照参考流程，针对步骤 1 中识别的客户端，静默确定 SigNoz MCP 服务的状态：

使用 signoz_list_services(timeRange: "1h", limit: 1) 探测。请勿使用文档工具（signoz_search_docs 或 signoz_fetch_doc）进行此检查。

• 对于 Codex，在查看插件根目录中的 mcp.json 之前，先使用 codex mcp get signoz 或 codex mcp list 检查生效的 signoz 条目；同名的原生条目优先级更高，并且可能有意作为当前启用的备用项。对于其他 Agent Plugins v1 客户端，以及捆绑式 Claude Code 或 Cursor 安装，请使用参考流程中针对相应客户端的备用方案。
• 对于 Grok Build，请改为从 Grok 的配置范围中读取 [mcp_servers.signoz]（或运行 grok mcp list）。Grok 随附的 .signoz_grok_mcp.json 提供可用的默认配置，并会被配置覆盖，因此它无法反映当前的实时状态。
• 对于所有其他客户端，包括原生 VS Code 配置和 Devin CLI，请勿读取或搜索插件根目录中的 mcp.json、.signoz_claude_mcp.json 或 .signoz_cursor_mcp.json。这些是为其他插件发行版本捆绑的文件，与此处无关，即使文件搜索工具碰巧找到了它们也不例外（例如，当此技能通过 agent-skills 源代码仓库的本地检出链接时）。这并不排除 .vscode/mcp.json 或 .cursor/mcp.json 等原生文件；请根据 client-configs.md 检查已识别客户端自己的原生配置位置。

状态结果：

• 正常工作：signoz_list_services 成功；继续处理用户原本的 SigNoz 请求。
• 未配置：执行步骤 3。
• 已配置但无法工作：如果用户提供了新的区域或 MCP URL，请执行步骤 3。否则告知用户 SigNoz MCP 服务已配置但尚未连接，然后询问 SigNoz Cloud 区域或 MCP URL，以便修复。如果用户认为端点已经正确，请告知他们完成步骤 5 中的客户端身份验证步骤。

当 MCP 不可用时，请勿退而使用原始 HTTP 调用获取 SigNoz 数据。对于此插件的 SigNoz 实时工作流，MCP 服务是受支持的 API 接口。

工作流技能假定当前 SigNoz MCP 服务契约有效。如果 SigNoz 工具报告的架构或参数错误与技能说明不符，请修复或更新 MCP 服务连接，而不是自行编造其他原始 HTTP 调用或沿用旧参数。

步骤 3：确定端点

如果 $ARGUMENTS 或用户最新消息中已包含区域或 URL，请使用该信息。否则，询问以下任一信息：

• SigNoz Cloud 区域：us、us2、eu、eu2、in、in2，或更新的区域代码
• SigNoz Cloud MCP URL，例如 https://mcp.us.signoz.cloud/mcp
• 自托管 HTTP MCP URL，例如 http://localhost:8000/mcp

使用 mcp-settings.md 映射用户的回复。如果用户只提供了 SigNoz 工作区 URL（例如 https://your-instance.signoz.cloud），请勿据此猜测区域。请让用户在 SigNoz 的 设置 -> 数据接入 中查看并提供区域。

配置 SigNoz Cloud 时，请勿询问 API 密钥。配置好托管 MCP URL 后，OAuth 流程会要求提供实例 URL 和服务账号 API 密钥。对于自托管 SigNoz，如果用户提供 /mcp 端点，优先使用 HTTP 模式。只有在用户明确要求配置 stdio／本地二进制模式时，才收集二进制文件路径、SigNoz URL 和 API 密钥。对于无法完成交互式 OAuth 的客户端，仅当用户提出要求或客户端要求时，才使用 client-configs.md 中基于请求头的备用方案。

步骤 4：应用端点

对于 Agent Plugins v1 安装（包括 Codex），或捆绑式 Claude Code 或 Cursor 插件安装，请按照参考编辑规则应用端点：

1. 对于 Agent Plugins v1，请遵循 mcp-settings.md 中的可移植端点资格规则，以及 client-configs.md 中的规范文件结构。如果端点不可移植，请改用参考路由中指定客户端的原生 MCP 配置。 在 VS Code 中配置已安装的 Agent Plugins v1 软件包时，如果端点可移植，且用户未明确要求使用原生配置，则只更新插件根目录中的 mcp.json。不要创建原生 signoz 条目，否则会在插件服务之外再注册一个服务。如果用户明确说明先前的插件设置创建了重复的原生 signoz，则只从 VS Code 工作区或用户 MCP 配置中移除已确认的意外条目，并保留所有无关服务和设置。绝不能仅因原生条目与插件注册同时存在，就推断该原生条目是意外创建的。
2. 对于 Claude Code，请保持 .signoz_claude_mcp.json 不变。通过 claude plugin list --json 获取准确的已启用插件 ID，然后只更新 ~/.claude/settings.json 中的 pluginConfigs[<plugin-id>].options.SIGNOZ_MCP_URL，并保留无关设置。Claude 会忽略项目级和本地的 pluginConfigs。如果托管设置或 --settings 提供了该选项，请报告这个优先级更高的来源，不要声称用户设置已更改。自定义操作会更新同一个用户选项。
3. 对于 Codex，请更新 Agent Plugins v1 的 mcp.json，并保留其中的 signoz 键和 type。如果已存在原生 signoz 条目，也要更新，因为它的优先级更高。对于不可移植的端点，请保持 mcp.json 不变，改用原生条目。通过 codex mcp get signoz 或 codex mcp list 验证。
4. 对于 Cursor，请在 .signoz_cursor_mcp.json 中仅替换 url 值为解析出的 MCP 端点，并保留现有的 signoz 服务键。
5. 保留无关的 MCP 服务和设置。

Claude Code 用户设置片段（使用准确的已安装插件 ID，并保留 ~/.claude/settings.json 的其余内容）：

{
  "pluginConfigs": {
    "signoz@<marketplace>": {
      "options": {
        "SIGNOZ_MCP_URL": "https://mcp.us.signoz.cloud/mcp"
      }
    }
  }
}

Agent Plugins v1 目标结构，包括 Codex（保留 $schema、signoz 服务键和 type）：

{
  "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json",
  "mcpServers": {
    "signoz": {
      "type": "streamable-http",
      "url": "https://mcp.us.signoz.cloud/mcp"
    }
  }
}

Cursor 目标结构（保留 signoz 服务键）：

{
  "mcpServers": {
    "signoz": {
      "url": "https://mcp.us.signoz.cloud/mcp"
    }
  }
}

如果仍在使用的非 Claude 注册文件中包含旧版本的 SIGNOZ_MCP_URL 包装形式，请将其替换为解析出的具体 URL。

可移植注册文件和 Cursor 注册文件位于已安装的插件中。插件更新可能会将它们重置为占位符；如果发生这种情况，请重新运行此设置技能。Claude Code 持久化的插件选项会在插件更新后保留。若要设置更持久的原生客户端配置，请使用 client-configs.md 中的相应配置方法。

对于 Codex，如果用户表示端点再次重置、总是重置，或要求设置持久配置，在解析端点后，还要创建或更新原生 Codex MCP 服务条目：

codex mcp add signoz --url <resolved-mcp-url>

这会在 Codex 配置中写入用户级 [mcp_servers.signoz] 条目，并在插件缓存更新后继续保留。如果直接编辑 TOML，请保留无关配置，且只设置 mcp_servers.signoz 的 url。

对于 Grok Build，不要编辑捆绑的 .signoz_grok_mcp.json。请将解析出的端点写入 Grok 自身的配置，以替换插件提供的 signoz 服务，并在插件更新后继续保留：

grok mcp add signoz -t http <resolved-mcp-url> -s user

如果用户希望将端点随仓库一同提交到 ./.grok/config.toml，请改用 -s project。重新运行该命令会更新现有条目，而不是添加第二个服务。如果 signoz 已在多个作用域中定义，请更新优先级最高的条目（./.grok/config.toml > <repo-root>/.grok/config.toml > ~/.grok/config.toml）；编辑优先级较低的条目会被更高优先级的配置静默覆盖。请参阅 client-configs.md 中的 Grok Build CLI 配置方法。

对于原生客户端设置，请使用 client-configs.md：

• 仅当用户指定了某个客户端，或目标文件显然是当前任务所用的活动配置时，才编辑现有的原生客户端配置。
• 仅当用户要求配置某个客户端时，才为其创建新的原生客户端配置。
• 切勿将服务账号 API 密钥、Bearer 令牌或基于请求头的身份验证值写入受版本控制的项目文件。对于 SigNoz Cloud，优先使用客户端 OAuth、用户级配置、环境变量引用，或可由用户在本地运行的短命令。
• 保留无关的 MCP 服务和现有客户端设置。
• 在原生客户端配置中保留服务名称 signoz（捆绑的 Claude Code 插件文件是唯一使用 mcp 键的文件；不要重命名）。

身份验证与角色诊断

后端 RBAC 根据 API 密钥所属用户的角色对 MCP 故障进行分类：读取操作至少需要 viewer；写入告警/仪表盘需要 editor 或 admin；管理通知渠道和创建 API 密钥需要 admin。401 / UNAUTHORIZED 表示凭据缺失、无效或已过期：先检查配置/凭据是否存在，再视情况重新进行身份验证或重新签发。403 / PERMISSION_DENIED 表示凭据有效，但权限不足。应由具备足够权限的用户执行操作，或签发专用的最低角色密钥；切勿将高权限密钥粘贴到聊天或受版本控制的配置中。

步骤 5：告知用户如何完成

告知用户 SigNoz MCP 端点已配置，然后提供客户端专属的身份验证步骤：

• Agent Plugins v1 客户端：如果客户端未读取更新后的 mcp.json，请重新加载已安装的插件，然后使用该客户端的 MCP 身份验证流程连接 signoz 服务。Agent Plugins v1 将 OAuth 交互和凭据存储交由客户端处理。
• Cursor：重新加载窗口，然后如果出现提示，在 Tools & MCP 中对 signoz MCP 服务进行身份验证。
• VS Code / GitHub Copilot：在 Agent 模式下打开 Copilot Chat，如果出现提示，请批准 signoz 服务，然后完成 SigNoz Cloud 的身份验证流程。除非自托管端点的 MCP 服务以 OAUTH_ENABLED=true 运行，否则无需 OAuth。
• Codex：如果服务未显示，请重启 Codex。对于 SigNoz Cloud，运行 codex mcp login signoz 完成 OAuth，然后使用 /mcp 验证。对于自托管 HTTP 端点（除非服务以 OAUTH_ENABLED=true 运行，否则无需 OAuth），跳过登录步骤，直接使用 /mcp 验证已完成身份验证的 signoz 服务是否已连接。
• Claude Code：运行 /reload-plugins，让 Claude 重新替换已保存的选项，然后运行 /mcp，选择 signoz 插件的 mcp 服务（plugin:signoz:mcp），并完成身份验证。
• Claude Desktop：对于 SigNoz Cloud 或可公开访问的自托管 HTTP 端点，请重新连接自定义连接器，并在出现提示时完成身份验证。私有网络或 localhost 端点需要使用本地 stdio，因为远程连接器从 Anthropic 的云端发起。更改本地 stdio 设置后，请重启 Claude Desktop，使其重新加载 claude_desktop_config.json；该文件仅用于基于命令的注册，不适用于托管 URL。
• Grok Build：运行 /mcps（或按 Ctrl+L 并打开 MCP Servers 选项卡），配置更改后按 r 重新加载，然后选择 signoz 并按 i，在浏览器中完成 OAuth 流程。除非自托管端点的服务以 OAUTH_ENABLED=true 运行，否则无需 OAuth。使用 grok mcp doctor signoz 进行诊断。
• Gemini CLI：如有需要，请重启 Gemini CLI，然后运行 /mcp auth signoz。
• Devin CLI：启动新会话，以读取更新后的 .devin/config.json。对于 SigNoz Cloud，运行 devin mcp login signoz 完成 OAuth。对于自托管或基于标头的端点，无需进行 OAuth。
• Windsurf：重新加载 Windsurf，并在出现提示时完成身份验证。
• Zed：配置更改后重新加载 Zed；自托管 stdio 模式会读取上下文服务条目中配置的环境。
• Antigravity CLI：输入 /mcp，选择 signoz 服务，然后选择 Authenticate 以启动 OAuth 流程（在浏览器中完成）。除非自托管端点的服务以 OAUTH_ENABLED=true 运行，否则无需 OAuth。如果身份验证卡住，请清除缓存的动态身份验证提供程序，然后重试。
• OpenCode：如果身份验证未自动启动，请运行 opencode mcp auth signoz，然后使用 opencode mcp list 验证。

简短作答。除非用户明确要求实现细节，否则不要透露注册文件路径、占位符值、环境变量名称、API 密钥、令牌或文件内容。