signoz-mcp-setup

SigNoz MCP のセットアップ

このプラグインに付属する SigNoz MCP サーバーの登録を初期化または修復します。目標の状態は、正常に動作する signoz MCP サーバーが 1 つあることです。ユーザーから別個の設定を明示的に求められない限り、重複するサーバーを作成しないでください。

共通の参照資料

状態の確認、ユーザー入力の対応付け、登録ファイルの編集を行う前に、references/mcp-settings.md を読んでください。この手順で使用するサーバー状態の確認方法、登録ファイルの場所、編集ルール、リージョンの対応付けが記載されています。

Agent Plugins v1 のポータブルなインストールを行う場合、ユーザーが付属の Claude Code または Cursor プラグイン以外のクライアントを指定した場合、ネイティブクライアント設定がすでに存在する場合、またはセルフホストの stdio／ローカルバイナリのセットアップを求められた場合は、references/client-configs.md を読んでください。

設定手順

ステップ 1：クライアントを特定する

状態を確認する前に、クライアントを特定してください。どこから状態を確認してよいかが決まります。

$ARGUMENTS またはユーザーの最新のメッセージで指定されたクライアントを使用してください。クライアントが指定されていない場合は、現在の環境が明らかなときに限り推定してください（ディスク上にどのファイルが存在するかだけでなく、このスキルを実行しているエージェント CLI またはエディターを基準にします）。

プラグインルート内に共存する他のファイルではなく、アクティブなクライアントが読み込んだ形式に基づいてインストールの種類を判定してください。ルートの plugin.json が標準の Agent Plugins スキーマを宣言している場合、同じルートに Claude Code、Cursor、Grok Build 用の登録ファイルが存在していても、Agent Plugins v1 インストールではポータブルな mcp.json を使用します。クライアント固有の登録ファイルを使うのは、そのクライアントが対応する互換パッケージを読み込んだ場合に限ります。

• VS Code または Codex のインストールを含む、ルートマニフェストが Agent Plugins スキーマを宣言するポータブルな Agent Plugins v1 インストール：インストール済みプラグインルートの標準 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 のドキュメントを案内します。

ネイティブクライアント設定を編集する必要があり、クライアントが特定できない場合は、どのクライアントを設定するかユーザーに尋ねてください。

Step 2: 状態を確認する

Step 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 を実行します。バンドルされている .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 に従って、特定したクライアント独自のネイティブ設定場所を確認してください。

状態の判定結果：

• working：signoz_list_services が成功しました。ユーザーの元の SigNoz リクエストを続行します。
• not-setup：Step 3 を実行します。
• configured-but-not-working：ユーザーが新しいリージョンまたは MCP URL を提示した場合は、Step 3 を実行します。それ以外の場合は、SigNoz MCP サーバーは設定済みですが接続されていないことを伝え、修復に必要な SigNoz Cloud のリージョンまたは MCP URL を尋ねます。エンドポイントが正しいはずだとユーザーが考えている場合は、Step 5 のクライアント認証手順を完了するよう伝えてください。

MCP を利用できない場合でも、SigNoz のデータ取得に生の HTTP 呼び出しへフォールバックしないでください。MCP サーバーは、このプラグインの SigNoz ライブワークフローでサポートされている API です。

ワークフロースキルは、現在の SigNoz MCP サーバーの契約を前提としています。SigNoz ツールで、スキルの指示に反するスキーマまたはパラメーターエラーが報告された場合は、代替の生の HTTP 呼び出しを考案したり、古いパラメーターを案内したりせず、MCP サーバーへの接続を修復または更新してください。

Step 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 を使用して回答を対応付けます。ユーザーが https://your-instance.signoz.cloud のような SigNoz ワークスペース URL だけを提示した場合、そこからリージョンを推測しないでください。SigNoz の Settings -> Ingestion を確認して、リージョンを知らせるよう依頼します。

SigNoz Cloud の設定に API キーを尋ねないでください。ホスト型 MCP URL の設定後、OAuth でインスタンス URL とサービスアカウントの API キーが求められます。セルフホストの SigNoz では、ユーザーが /mcp エンドポイントを提示した場合、HTTP モードを優先してください。stdio／ローカルバイナリモードの場合は、ユーザーからそのモードの設定を明示的に依頼された場合に限り、バイナリのパス、SigNoz URL、API キーを収集します。対話型 OAuth を完了できないクライアントでは、ユーザーから依頼された場合、またはクライアントが必要とする場合に限り、client-configs.md にあるヘッダーベースのフォールバックを使用します。

Step 4: エンドポイントを適用する

Codex を含む Agent Plugins v1 のインストール、または Claude Code もしくは Cursor のバンドル版プラグインのインストールでは、参照フローの編集ルールを使用してエンドポイントを適用します。

1. Agent Plugins v1 では、mcp-settings.md のポータブルなエンドポイントの適格性ルールと、client-configs.md の標準ファイル形式に従ってください。エンドポイントがポータブルでない場合は、参照先のルーティングに従い、特定されたクライアントのネイティブ MCP 設定を使用してください。 VS Code でインストール済みの Agent Plugins v1 パッケージを設定する場合、エンドポイントがポータブルで、ユーザーがネイティブ設定を明示的に要求していないときは、プラグインルートの mcp.json のみを更新してください。ネイティブの signoz エントリは作成しないでください。プラグインサーバーと並んで 2 つ目のサーバーが登録されてしまいます。以前のプラグイン設定でネイティブの 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 にオプションが指定されている場合は、ユーザー設定が変更されたと主張せず、より優先順位の高い設定元を報告してください。Customize では同じユーザーオプションを更新します。
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 では、既存の signoz サーバーキーを保持し、url の値のみを解決済み MCP エンドポイントに置き換えてください。
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

エンドポイントをリポジトリとともにコミットしたい場合は、代わりに -s project を使用して ./.grok/config.toml に設定してください。コマンドを再実行すると、2 つ目のサーバーを追加するのではなく、既存のエントリが更新されます。signoz が複数のスコープですでに定義されている場合は、最も優先順位の高いもの（./.grok/config.toml > <repo-root>/.grok/config.toml > ~/.grok/config.toml）を更新してください。優先順位の低いものを編集しても、警告なしに上書きされてしまいます。client-configs.md の Grok Build CLI レシピを参照してください。

ネイティブクライアントのセットアップには、client-configs.md を使用してください：

• ユーザーがクライアントを指定した場合、または対象ファイルがタスクに使用する有効な設定ファイルであることが明らかな場合にのみ、既存のネイティブクライアント設定を編集してください。
• ユーザーがそのクライアントの設定を依頼した場合にのみ、新しいネイティブクライアント設定を作成してください。
• サービスアカウントの API キー、ベアラートークン、ヘッダー認証の値を、追跡対象のプロジェクトファイルに書き込まないでください。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：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 は不要です）、ログイン手順を省略し、すでに認証済みの signoz サーバーが接続されていることを /mcp で確認します。
• Claude Code：/reload-plugins を実行して、Claude に保存済みのオプションを再置換させてから、/mcp を実行し、signoz プラグインの mcp サーバー（plugin:signoz:mcp）を選択して認証を完了します。
• Claude Desktop：SigNoz Cloud または外部からアクセス可能なセルフホストの HTTP の場合は、カスタムコネクターに再接続し、プロンプトが表示されたら認証を完了します。プライベートネットワークまたは localhost のエンドポイントでは、リモートコネクターは Anthropic のクラウドから接続するため、ローカルの stdio が必要です。ローカルの 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 キー、トークン、ファイルの内容は開示しないでください。