MCP Server クイックスタート¶
OWL MCP Server は、Guance が Model Context Protocol に基づいて提供するサーバー側実装です。また、Guance のメトリクス、ログ、イベント、モニター、APM、RUM、インフラストラクチャ、ノートなどの機能を MCP ツールとしてカプセル化し、MCP をサポートする AI クライアントから呼び出せるようにします。
このドキュメントでは、streamableHttp 経由で OWL MCP Server に接続する方法を説明します。
リモート OWL MCP Server に接続する場合、OWL CLI や CLI 対応の Skill をインストールする必要はありません。Agent がターミナルコマンドを実行できる場合は、CLI 統一フローを選択することもできます。2 つの方式の選択については、接続方式の説明を参照してください。
使用前の準備¶
接続前に、次の準備が完了していることを確認してください:
- 対応する業務権限を持つ Guance API Key を作成済みであること
- ワークスペースが属するサイトに対応する OWL MCP Endpoint を取得済みであること
- クライアントが Streamable HTTP をサポートし、
Authorizationリクエストヘッダーを設定できること - クライアントが実際にリクエストを送信する環境から OWL MCP Endpoint にアクセスできること
Endpoint¶
OWL MCP Server はサイトごとに独立した Endpoint を提供します。ワークスペースが属するサイトに応じて、対応するアドレスを選択してください。
| デプロイタイプ | サイト名 | Endpoint |
|---|---|---|
| SaaS デプロイ | 中国リージョン1(杭州) | https://owl-mcp.guance.com/mcp |
| SaaS デプロイ | 中国リージョン2(寧夏) | https://aws-owl-mcp.guance.com/mcp |
| SaaS デプロイ | 中国リージョン4(広州) | https://cn4-owl-mcp.guance.com/mcp |
| SaaS デプロイ | 中国リージョン6(香港) | https://cn6-owl-mcp.guance.one/mcp |
| SaaS デプロイ | グローバルリージョン1(オレゴン) | https://us1-owl-mcp.guance.com/mcp |
| SaaS デプロイ | ヨーロッパリージョン1(フランクフルト) | https://eu1-owl-mcp.guance.one/mcp |
| SaaS デプロイ | アジア太平洋リージョン1(シンガポール) | https://ap1-owl-mcp.guance.one/mcp |
| SaaS デプロイ | アジア太平洋リージョン2(シンガポール) | https://ap2-owl-mcp.guance.com/mcp |
| SaaS デプロイ | アフリカリージョン1(南アフリカ) | https://za1-owl-mcp.guance.com/mcp |
| SaaS デプロイ | インドネシアリージョン1(ジャカルタ) | https://id1-owl-mcp.guance.com/mcp |
| SaaS デプロイ | 無料ゾーン(北京) | https://cn3-owl-mcp.guance.com/mcp |
| プライベートデプロイメントプラン | プライベートデプロイメントプラン | 実際のデプロイで提供される OWL MCP Endpoint に従う |
認証方式¶
MCP クライアントでリクエストヘッダーを設定します:
サイトは上記の Endpoint URL で選択します。別途 Endpoint リクエストヘッダーを追加する必要はなく、Authorization の値にサイト識別子を付加しないでください。
MCP と OWL CLI は異なるサービスエンドポイントとリクエストヘッダーを使用します。設定時は区別してください:
| 呼び出しエントリ | サイト選択 | 認証設定 |
|---|---|---|
| OWL MCP Server | このページの Endpoint 表にある /mcp アドレスを使用 |
MCP クライアントで Authorization: Bearer <API Key> を設定 |
| OWL CLI | OWL CLI Endpoint を使用 | CLI のログインまたは Profile で API Key を設定すると、CLI が DF-API-KEY を自動送信します。詳細は CLI 設定と認証 を参照してください |
CLI の DF-API-KEY リクエストヘッダーを、このページの MCP クライアント設定にそのまま適用しないでください。
ここで、<API Key> は Guance の API Key です。適切に管理し、公開コードリポジトリ、共有ドキュメント、長期保存するログに書き込まないでください。
OWL MCP Server は認証を完了してから MCP 処理に進みます。未認証または資格情報が無効なリクエストは直ちに拒否され、
401 UnauthorizedとレスポンスヘッダーWWW-Authenticate: Bearer realm="mcp"が返されます。また、レート制限が発生した場合は429、送信元 IP がホワイトリストにない場合は403が返されます。
クライアント設定¶
OWL MCP Server は標準の streamableHttp 接続方式を使用しており、このトランスポート方式をサポートする MCP クライアントに接続できます。クライアントによって設定場所やフィールド名が若干異なる場合があるため、実際のクライアントのドキュメントを参照してください。
以下から使用するクライアントを選択し、同じ接続情報を入力します:
- ワークスペースが属するサイトの OWL MCP Endpoint を選択する
- リクエストヘッダー
Authorization: Bearer <API Key>を設定する - 保存してサービスを有効にし、現在の会話でそのツールの使用を許可する
- 検証方法に従って、ツール検出と 1 回の読み取り専用呼び出しを完了する
| クライアント | 設定場所 |
|---|---|
| Codex | MCP 設定 |
| Claude Code | MCP 設定 |
| Cursor | MCP 設定 |
| Trae | MCP 設定 |
| VS Code + GitHub Copilot | MCP 設定 |
| Windsurf(Cascade) | MCP 設定 |
| Claude Desktop | リモートコネクタ |
| Cherry Studio | MCP 設定 |
| OpenClaw | MCP 設定 |
| Hermes | 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 をローカル環境変数として使用し、チームで承認された資格情報管理方法で完全な Bearer <API Key> を注入してください。実際の資格情報を .mcp.json に直接書き込んだり、コードリポジトリにコミットしたりしないでください。保存後に Claude Code を再起動し、claude mcp list を実行します。会話で /mcp を入力し、owl が接続済みでツールを検出できることを確認することもできます。変数の展開と設定範囲については、Claude Code 公式ドキュメント を参照してください。
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" は、読み取り専用とマークされていないツールに対して確認を求めます。そのまま保持することを推奨します。facade モードの exec_tool でも確認が発生します。フィールドの説明については、Codex 公式ドキュメント を参照してください。
Cursor¶
プロジェクトの .cursor/mcp.json またはユーザーレベルの ~/.cursor/mcp.json に次を追加します:
{
"mcpServers": {
"owl": {
"url": "your-owl-mcp-endpoint",
"headers": {
"Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
}
}
}
}
Cursor を起動する環境で OWL_MCP_API_KEY に API Key を設定し、環境変数参照としてリクエストヘッダーに渡します。保存後、MCP 設定で owl が有効になっていることを確認し、Agent との会話で検証方法に従って 1 回の読み取り専用呼び出しを実行します。設定場所と変数の構文については、Cursor 公式ドキュメント を参照してください。
Trae¶
設定の MCP 管理に移動し、手動追加を選択して、次の設定を入力します:
{
"mcpServers": {
"owl": {
"url": "your-owl-mcp-endpoint",
"headers": {
"Authorization": "Bearer <API Key>"
}
}
}
}
<API Key> を実際の値に置き換える場合は、クライアントのプライベート設定内でのみ操作し、資格情報を含む設定を会話、共有ドキュメント、コードリポジトリに送信しないでください。保存後、現在の Agent で owl を有効にし、検証方法に従って呼び出しを実行します。具体的な設定場所については、Trae 公式ドキュメント を参照してください。
VS Code + GitHub Copilot¶
VS Code のコマンドパレットで MCP: Add Server を実行し、HTTP を選択して、OWL MCP Endpoint を入力し、owl という名前を付けます。以下は VS Code 形式の .vscode/mcp.json 設定です:
{
"servers": {
"owl": {
"type": "http",
"url": "your-owl-mcp-endpoint",
"headers": {
"Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
}
}
}
}
VS Code を実行する環境で OWL_MCP_API_KEY を設定します。リモート開発やコンテナを使用する場合は、実際に MCP クライアントを実行する環境で設定してください。Agent との会話で対応するツールを有効にし、検証方法に従って呼び出しを実行します。
VS Code 形式ではトップレベルの servers を使用し、ポータブル Copilot 形式では mcpServers を使用します。2 つの構造を直接混在させないでください。具体的な設定範囲と実行モードについては、VS Code 公式ドキュメント を参照してください。
Windsurf(Cascade)¶
Cascade の MCP 管理画面で mcp_config.json を開き、次を追加します:
{
"mcpServers": {
"owl": {
"serverUrl": "your-owl-mcp-endpoint",
"headers": {
"Authorization": "Bearer ${env:OWL_MCP_API_KEY}"
}
}
}
}
クライアントを起動する環境で OWL_MCP_API_KEY を設定し、保存後に MCP サービスを更新して owl を有効にしたうえで、検証方法に従って呼び出しを実行します。
この設定は Cascade に適用されます。他の Agent モードでは異なる設定場所を使用する場合があります。serverUrl、headers、環境変数の構文については、Cascade 公式ドキュメント を参照してください。
Claude Desktop¶
リモートカスタムコネクタを使用して接続します:
- コネクタ設定でカスタムリモートコネクタを追加し、OWL MCP Endpoint を入力します。
- 固定 API Key を使用する場合は、Authentication で
No sign in(OAuth ログインを使用しない)を選択し、Request headers にAuthorizationを追加して、値にBearer <API Key>を設定します。サーバー側では引き続きこのリクエストヘッダーで認証を行います。 - 保存後、現在の会話でコネクタを有効にし、検証方法に従って呼び出しを実行します。
リモートコネクタのリクエストはローカルマシンではなく Anthropic のクラウドから送信されます。プライベートネットワークや IP ホワイトリストでは、実際のリクエスト送信元を許可する必要があります。組織アカウントでは、管理者が先にコネクタを追加する必要がある場合があります。設定場所、権限、リクエストヘッダーの設定については、Claude 公式ドキュメント を参照してください。
OpenClaw¶
openclaw mcp set owl '{
"transport": "streamable-http",
"url": "your-owl-mcp-endpoint",
"headers": {
"Authorization": "Bearer ${OWL_MCP_API_KEY}"
},
"enabled": true
}'
実際に OpenClaw を実行するプロセス環境で、OWL_MCP_API_KEY に API Key を設定します。上記の一重引用符は環境変数参照を保持するもので、実際の資格情報がコマンドに書き込まれることはありません。保存した設定を確認し、サービスをプローブします:
list / show は設定を表示するだけで、サービスに接続できることを証明するものではありません。mcp doctor をサポートするバージョンでは、引き続き openclaw mcp doctor owl --probe を実行してサービスをプローブできます。旧バージョンでは、実際のツール呼び出し結果で検証します。Gateway が別のプロセスで実行されている場合は、該当するプロセスに設定と環境を再読み込みさせてから、初回呼び出しを完了してください。フィールドとコマンドについては、OpenClaw 公式ドキュメント を参照してください。
Hermes¶
~/.hermes/config.yaml を編集します:
mcp_servers:
owl:
url: your-owl-mcp-endpoint
headers:
Authorization: "Bearer ${OWL_MCP_API_KEY}"
enabled: true
Hermes の実行環境または現在の Profile の資格情報設定で OWL_MCP_API_KEY を設定します。url はリモート HTTP サービスに対応し、デフォルトで Streamable HTTP が使用されるため、type: streamableHttp は不要です。設定を検証します:
現在の Hermes の指示に従って MCP を再読み込みするか新しいセッションを作成し、初回呼び出しを完了してください。フィールドと変数参照については、Hermes 公式ドキュメント を参照してください。
検証方法¶
設定完了後、MCP クライアントで次のように質問できます:
facade モードでは、クライアントは
list_catalogs、list_tools、exec_toolを検出でき、exec_tool経由でowl.metric.listを呼び出せる必要があります。static モードでは、クライアントはowl.metric.listなどの業務ツールを直接検出します。サーバー側で除外リストが設定されている場合、一部のツールは表示されません。接続できない、認証に失敗する、ツール一覧が空、または返却結果が空の場合は、トラブルシューティング を参照してください。
次の項目をそれぞれ確認してください:
| チェック項目 | 成功時の状態 |
|---|---|
| 接続と認証 | サービスに正常に接続でき、認証エラーやネットワークエラーがない |
| ツール検出 | facade のラッパーツール、または static モードの業務ツールを検出でき、現在の会話で有効になっている |
| 実際の呼び出し | 呼び出し記録にメトリクス source のクエリが 1 回あり、MCP および業務結果のいずれにもエラーがなく、データまたは成功した空リストが返されている。回答がその結果に基づいて生成されている |
「接続済み」と表示されるだけ、または Agent が「設定成功」と返答するだけでは、業務ツールが利用可能であることを証明できません。成功した空リストも、ワークスペースに必ずメトリクスデータがあることを意味するものではありません。データの取り込みと API Key の権限をあわせて確認してください。次のステップとして、典型的な質問 を試すことができます。
利用可能なツール¶
サーバーは 2 つのツール公開方式をサポートしています。デフォルトの facade モードでは list_catalogs、list_tools、exec_tool の 3 つのラッパーツールを提供します。static モードでは、MCP tools/list で公開が許可された業務ツールを直接返します。具体的なモードはサーバー側の設定で決まり、クライアントがトランスポートプロトコルを切り替える必要はありません。
MCP クライアントから呼び出せる代表的なツールには、次のものもあります:
- クロスワークスペースの承認済みデータクエリ:
owl.workspace.data_authorized.listで承認済みワークスペースを検出し、workspace_uuidsとtarget_regionをowl.data.simple_queryに渡します。1 回のクエリで対象となるサイトは 1 つに限定されます。詳細はクロスワークスペースクエリ を参照してください。 - インシデント詳細:
owl.incident.get。インシデント UUID で詳細とページングされた関連イベント参照を取得し、owl.event.getでイベント内容を読み取ります。 - 同一組織内のクロスワークスペース Trace クエリ:現在のワークスペースでは直接クエリします。同一組織内の別ワークスペースをまたぎ、対象 UUID が未確定の場合は、
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 を一覧表示します。
使用上の規約¶
OWL MCP Server を使用する際は、次の規約に従うことを推奨します:
| 種類 | 規約 |
|---|---|
| 時間範囲関連ツール | 13 桁のミリ秒タイムスタンプを統一して使用 |
| ページング関連ツール | 通常、page_size と page_index をサポート |
| 詳細関連ツール | 通常、一覧系ツールが返す識別子フィールドに依存(例:rule_uuid、incident_uuid、issue_id、note_uuid) |
| データクエリ関連ツール | 「先に検出、後にクエリ」の順序で使用することを推奨します。まず検出系ツールで利用可能な source、field、index を取得し、その後で実際のクエリを実行します |