MCP Server Quick Start¶

Owl MCP Server is Guance's server-side implementation based on the Model Context Protocol. It encapsulates Guance's capabilities such as Metrics, LOGs, Events, Monitors, Dashboards, APM, RUM, and Infrastructure as MCP tools for invocation by AI clients that support MCP.

This document explains how to connect to Owl MCP Server via streamableHttp.

In addition to the above capabilities, MCP clients can also invoke the following tools:

• Same Organization Workspace Discovery: owl.account.workspace.same_org.list, lists workspaces within the same organization as the current API Key's organization. It can be used with the same_org_workspace_uuids parameter of owl.data.simple_query to achieve cross-workspace trace queries (supporting up to 20 workspaces).
• Simplified Data Query: owl.data.simple_query, provides a more user-friendly data query entry point.
• Document Search: mdsearch_search / mdsearch_document / mdsearch_catalog, used for searching Guance documentation.
• SLO List: owl.slo.list, lists configured SLOs.

Prerequisites¶

Before connecting, please ensure the following preparations are complete:

1. A Guance API Key with corresponding business permissions has been created.
2. The Owl MCP Endpoint corresponding to the workspace's site has been obtained.
3. The Owl MCP service connection configuration has been completed in the MCP client.
4. The current network environment can access the Owl MCP Endpoint.

Endpoint¶

Owl MCP Server provides independent Endpoints by site. Please select the corresponding address based on the workspace's site.

Authentication Method¶

Configure the request header in the MCP client:

Authorization: Bearer <API Key>

Here, <API Key> is the Guance API Key. Please keep it secure and do not write it into public code repositories, shared documents, or long-term logs.

Owl MCP Server completes authentication before proceeding to MCP processing. Unauthenticated or invalid credential requests are directly rejected, returning 401 Unauthorized with the response header WWW-Authenticate: Bearer realm="mcp". Additionally, triggering rate limiting returns 429, and requests from IPs not in the whitelist return 403.

Client Configuration¶

Owl MCP Server uses the standard streamableHttp connection method and can be connected to MCP clients that support this transport. The configuration entry points and field names may vary slightly between different clients. Please refer to the actual client documentation.

The following examples use Cherry Studio, OpenClaw, and Hermes to illustrate the configuration methods for common MCP clients. Other MCP clients supporting streamableHttp can also be configured following the same principles:

• URL: Fill in the Owl MCP Endpoint corresponding to the workspace's site.
• Configure Authorization: Bearer <API Key> in the request headers.
• Enable this MCP service.

The following examples use the placeholder address your-owl-mcp-endpoint. For actual connection, please replace it with the Owl MCP Endpoint corresponding to the workspace's site.

Cherry Studio¶

Add a new MCP service in Cherry Studio and configure it as follows:

• Type: streamableHttp
• URL: your-owl-mcp-endpoint
• Headers: Authorization=Bearer <API Key>

After completing the configuration, save and enable it, then return to the client homepage and select this MCP service.

OpenClaw¶

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

Verify the configuration:

openclaw mcp list
openclaw mcp show owl

Hermes¶

Edit ~/.hermes/config.yaml:

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

Verify the configuration:

hermes mcp list
hermes mcp test owl

Usage Conventions¶

When using Owl MCP Server, it is recommended to follow these conventions:

Verification Method¶

After configuration is complete, you can ask in the MCP client:

List the currently available metric sources.

The client should be able to discover and invoke owl.metric.list. If unable to connect, authentication fails, the tool list is empty, or returns empty results, please refer to Troubleshooting.