MCP Server クイックスタート¶

OWL MCP Server は、Guance が Model Context Protocol に基づいて提供するサーバーサイド実装です。Guance のメトリクス、ログ、イベント、モニター、APM、RUM、インフラストラクチャー、ノートなどの機能を MCP ツールとしてカプセル化し、MCP 対応の AI クライアントから呼び出せるようにします。

このドキュメントでは、streamableHttp を介して OWL MCP Server に接続する方法について説明します。

サーバーサイドは、2 種類のツール公開方式をサポートしています。デフォルトのファサードモードでは、list_catalogs、list_tools、exec_tool の 3 つのラッパーツールを提供します。static モードでは、MCP の tools/list で公開を許可されたビジネスツールを直接返します。どちらのモードを使用するかはサーバーサイドの設定に依存し、クライアント側でトランスポートプロトコルを切り替える必要はありません。

MCP クライアントが呼び出せる代表的なツールは次のとおりです。

• 認可されたクロスワークスペース DQL クエリでは、必要に応じて owl.workspace.data_authorized.list で対象を検出し、workspace_uuids と target_region を渡します。1 回のクエリは 1 サイトに限定し、範囲パラメータを省略すると現在のワークスペースをクエリします。CLI/MCP の例とページネーションはクロスワークスペースクエリを参照してください。
• owl.incident.get はインシデント UUID（incident_*）を受け取り、詳細と related_event_refs を返します。参照は 1 ページあたりデフォルトおよび最大 100 件です。page_info.has_more と next_page_index に従って取得し、インシデント UUID ではなくイベント参照を使って owl.event.get を呼び出します。取得可能な参照数と報告されたイベント数は異なる場合があり、不足する証拠を明記してください。
• 現在のワークスペースは直接クエリします。同一組織の他のワークスペースを対象にする場合、UUID が不明なときだけ owl.account.workspace.same_org.list（CLI：owl workspace same-org list）で候補を検出します。返された workspace_uuid を owl.data.same_org.trace.query に渡し、一覧のページネーション専用の workspace_id は使用しません。
• ノート: owl.nbook_note.list / owl.nbook_note.get / owl.nbook_note.add / owl.nbook_note.modify / owl.nbook_note.delete は、ノートの一覧表示、読み取り、作成、変更、削除を行います。normal と runbook の 2 つのタイプをサポートし、list では type によるフィルタリングが可能、add では type を設定できます。Markdown の本文を返すのは get のみです。add、modify、delete は書き込みツールであるため、MCP クライアントで人間による確認を設定することを推奨します。
• イベントクエリ: owl.event.list / owl.event.get は、時間範囲とステータスに基づくイベント一覧のクエリ、およびイベントドキュメント ID による詳細の取得を行います。
• Pipeline のクエリとサンプル検証: owl.pipeline.list / owl.pipeline.validate は、Pipeline のクエリ、またはサンプルデータを使用した処理結果の検証を行います。検証はテストのみを実行し、Pipeline の作成や変更は行いません。
• 簡易データクエリ: owl.data.simple_query は、より使いやすいデータクエリエントリを提供します。
• ドキュメント検索: mdsearch_search / mdsearch_document / mdsearch_catalog は、Guance のドキュメントを検索します。
• SLO 一覧: owl.slo.list は、設定済みの SLO を一覧表示します。

使用前の準備¶

接続する前に、以下の準備が完了していることを確認してください。

1. 対応するビジネス権限を持つ Guance API Key が作成済みであること
2. ワークスペースが所属するサイトに対応する OWL MCP Endpoint を取得済みであること
3. MCP クライアントで OWL MCP サービスの接続設定が完了していること
4. 現在のネットワーク環境から OWL MCP Endpoint にアクセスできること

Endpoint¶

OWL MCP Server はサイトごとに独立した Endpoint を提供します。ワークスペースが所属するサイトに応じて、対応するアドレスを選択してください。

認証方式¶

MCP クライアントでリクエストヘッダを設定します。

Authorization: Bearer <API Key>

<API Key> は Guance API Key です。適切に管理し、公開コードリポジトリ、共有ドキュメント、長期保存のログなどに書き込まないでください。

OWL MCP Server は、認証を完了してから MCP 処理に入ります。未認証または無効な資格情報のリクエストは直接拒否され、401 Unauthorized と応答ヘッダ WWW-Authenticate: Bearer realm="mcp" が返されます。また、レート制限に達した場合は 429、ソース IP がホワイトリストに含まれていない場合は 403 が返されます。

クライアント設定¶

OWL MCP Server は標準の streamableHttp 接続方式を使用しており、このトランスポート方式をサポートする MCP クライアントから接続できます。クライアントによって設定の入口やフィールド名が異なる場合がありますので、実際のクライアントのドキュメントを参照してください。

以下では、Cherry Studio、Claude Code、Codex、OpenClaw、Hermes を例に、一般的な MCP クライアントの設定方法を説明します。streamableHttp をサポートする他の MCP クライアントでも、同様の原則で設定できます。

• URL には、ワークスペースが所属するサイトに対応する OWL MCP Endpoint を入力します
• リクエストヘッダに Authorization: Bearer <API Key> を設定します
• この MCP サービスを有効にします

以下の例では、プレースホルダアドレス your-owl-mcp-endpoint を使用しています。実際に接続する際は、ワークスペースが所属するサイトに対応する OWL MCP Endpoint に置き換えてください。

Cherry Studio¶

Cherry Studio で新しい MCP サービスを追加し、次のように設定します。

• タイプ: streamableHttp
• URL: your-owl-mcp-endpoint
• リクエストヘッダ: Authorization=Bearer <API Key>

設定後、保存して有効にし、クライアントのトップページに戻ってこの MCP サービスを選択します。

Claude Code¶

Claude Code は http タイプを使用して Streamable HTTP サービスに接続します。プロジェクトのルートディレクトリに .mcp.json を作成するか、既存のファイルを編集し、以下の設定を追加します。

{
  "mcpServers": {
    "owl": {
      "type": "http",
      "url": "your-owl-mcp-endpoint",
      "headers": {
        "Authorization": "${OWL_MCP_AUTHORIZATION}"
      }
    }
  }
}

OWL_MCP_AUTHORIZATION をローカル環境変数として設定し、チームで承認された資格情報管理方法を通じて完全な認証情報を注入します。実際の資格情報を .mcp.json に直接書き込んだり、コードリポジトリにコミットしたりしないでください。保存後、Claude Code を再起動し、claude mcp list を実行します。または、セッション内で /mcp と入力し、owl が接続され、ツールが検出可能であることを確認します。

Codex¶

MCP JSON を Codex にコピーし、「この MCP を設定してください」と入力するだけで、Codex が自動的に関連設定を完了します。

手動で設定する場合、Codex のデスクトップ版、CLI、IDE 拡張機能は MCP 設定を共有します。~/.codex/config.toml を編集し、以下の設定を追加します。

[mcp_servers.owl]
url = "your-owl-mcp-endpoint"
bearer_token_env_var = "OWL_MCP_API_KEY"
default_tools_approval_mode = "writes"

Codex を起動する環境で、OWL_MCP_API_KEY を Guance API Key に設定します。Codex は自動的にこの値を Bearer Token として送信します。変数値に Bearer を重複して追加しないでください。また、実際の資格情報を config.toml に直接書き込んだり、コードリポジトリにコミットしたりしないでください。

設定を保存後、Codex を再起動し、codex mcp list を実行します。または、セッション内で /mcp と入力し、owl が接続され、ツールが検出可能であることを確認します。例の default_tools_approval_mode = "writes" は、データを書き込む可能性のあるツールを呼び出す前に確認を求めるもので、維持することを推奨します。

OpenClaw¶

openclaw mcp set owl '{
  "type": "streamableHttp",
  "url": "your-owl-mcp-endpoint",
  "headers": {
    "Authorization": "Bearer <API Key>"
  },
  "enabled": true
}'

設定の確認:

openclaw mcp list
openclaw mcp show owl

Hermes¶

~/.hermes/config.yaml を編集します。

mcp_servers:
  owl:
    type: streamableHttp
    url: your-owl-mcp-endpoint
    headers:
      Authorization: Bearer <API Key>
    enabled: true

設定の確認:

hermes mcp list
hermes mcp test owl

使用上の注意¶

OWL MCP Server を使用する際は、以下の注意事項に従うことを推奨します。

検証方法¶

設定が完了したら、MCP クライアントで以下のように質問できます。

現在利用可能なメトリクス source を一覧表示してください。

ファサードモードの場合、クライアントは list_catalogs、list_tools、exec_tool を検出し、exec_tool を介して owl.metric.list を呼び出せます。static モードの場合、クライアントは owl.metric.list などのビジネスツールを直接検出します。サーバーサイドで除外リストが設定されている場合、一部のツールは表示されません。接続できない、認証に失敗する、ツール一覧が空、または返される結果が空の場合は、トラブルシューティング を参照してください。