MCP Server クイックスタート¶

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

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

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

• 同一組織内のワークスペースをまたがるトレースクエリ：まず owl.account.workspace.same_org.list で候補ワークスペースを検出し、返却された workspace_uuid を workspace_uuids として 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 を設定可能です。get のみ Markdown 本文を返します。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 にアクセスできること

エンドポイント¶

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

認証方式¶

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、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 が接続され、ツールを検出できることを確認することもできます。

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 を呼び出せる必要があります。接続できない、認証に失敗する、ツールリストが空、または返される結果が空の場合は、トラブルシューティング を参照してください。