MCP Server Quick Start¶

OWL MCP Server is the server-side implementation provided by Guance based on the Model Context Protocol. It encapsulates Guance capabilities such as metrics, logs, events, monitors, APM, RUM, infrastructure, and notes as MCP tools for MCP-compatible AI clients to call.

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

The server supports two modes for exposing tools: the default facade mode provides three wrapper tools — list_catalogs, list_tools, and exec_tool; static mode directly returns the allowed business tools in the MCP tools/list. The specific mode is determined by the server configuration; clients do not need to switch transport protocols.

Representative tools that MCP clients can call include:

• Authorized cross-workspace data query: Use owl.workspace.data_authorized.list to discover authorized workspaces, then pass workspace_uuids and target_region to owl.data.simple_query; each query is limited to one target site. See Cross-Workspace Query.
• Incident details: owl.incident.get, which retrieves details and paginated related event references by incident UUID, then use owl.event.get to read event content.
• Cross-workspace Trace query within the same organization: Query directly within the current workspace; when querying across workspaces in the same organization and the target UUID is not yet determined, use owl.account.workspace.same_org.list to discover candidate workspaces, then pass the returned workspace_uuid as workspace_uuids to owl.data.same_org.trace.query. Note that workspace_id is only used for list pagination and cannot be used for querying.
• Notes: owl.nbook_note.list / owl.nbook_note.get / owl.nbook_note.add / owl.nbook_note.modify / owl.nbook_note.delete, used to list, read, create, modify, and delete notes. The normal and runbook types are supported; list can filter by type, and add can set type. Only get returns the Markdown content. add, modify, and delete are write tools, so it is recommended to configure manual confirmation in the MCP client.
• Event query: owl.event.list / owl.event.get, used to query event lists by time range and status, and to get details by event document ID.
• Pipeline query and sample validation: owl.pipeline.list / owl.pipeline.validate, used to query Pipelines or validate processing results with sample data. Validation only executes tests and does not create or modify Pipelines.
• Simplified data query: owl.data.simple_query, which provides a more user-friendly data query entry point.
• Document search: mdsearch_search / mdsearch_document / mdsearch_catalog, used to search Guance documentation.
• SLO list: owl.slo.list, which lists the configured SLOs.

Prerequisites¶

Before connecting, make sure the following preparations are complete:

1. Created a Guance API Key with the corresponding business permissions
2. Obtained the OWL MCP Endpoint corresponding to the site of the workspace
3. Completed the OWL MCP service connection configuration in the MCP client
4. The current network environment can access the OWL MCP Endpoint

Endpoint¶

OWL MCP Server provides a dedicated Endpoint per site. Select the address that corresponds to the site of the workspace.

Authentication¶

Configure the request header in the MCP client:

Authorization: Bearer <API Key>

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

OWL MCP Server performs authentication before entering MCP processing. Unauthenticated requests or requests with invalid credentials are rejected directly with 401 Unauthorized and the response header WWW-Authenticate: Bearer realm="mcp". In addition, rate limiting returns 429, and requests from source IPs not on the allowlist return 403.

Client Configuration¶

OWL MCP Server uses the standard streamableHttp connection method and can be connected to any MCP client that supports this transport. Different clients may have slightly different configuration entry points and field names; refer to the actual client documentation.

The following uses Cherry Studio, Claude Code, Codex, OpenClaw, and Hermes as examples to illustrate how to configure common MCP clients. Other MCP clients that support streamableHttp can also be configured following the same principles:

• Set the URL to the OWL MCP Endpoint corresponding to the site of the workspace
• Configure Authorization: Bearer <API Key> in the request headers
• Enable the MCP service

The following examples use the placeholder address your-owl-mcp-endpoint. In actual use, replace it with the OWL MCP Endpoint corresponding to the site of the workspace.

Cherry Studio¶

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

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

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

Claude Code¶

Claude Code uses the http type to connect to Streamable HTTP services. Create or edit .mcp.json in the project root directory and add the following configuration:

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

Set OWL_MCP_AUTHORIZATION as a local environment variable and inject the full authentication information through your team's approved credential management method. Do not write actual credentials directly into .mcp.json or commit them to the code repository. After saving, restart Claude Code and run claude mcp list; you can also enter /mcp in the session to confirm that owl is connected and the tools are discoverable.

Codex¶

Simply paste the MCP JSON to Codex and enter "Help me configure this MCP", and Codex will complete the configuration automatically.

For manual configuration, the Codex desktop app, CLI, and IDE extension share the MCP configuration. Edit ~/.codex/config.toml and add the following configuration:

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

In the environment where you start Codex, set OWL_MCP_API_KEY to the Guance API Key. Codex automatically sends this value as the Bearer Token. Do not append Bearer again in the variable value, and do not write actual credentials directly into config.toml or commit them to the code repository.

After saving the configuration, restart Codex and run codex mcp list; you can also enter /mcp in the session to confirm that owl is connected and the tools are discoverable. The default_tools_approval_mode = "writes" in the example requests confirmation before calling tools that may write data; it is recommended to keep it.

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 the conventions below:

Verification¶

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

List the currently available metric sources.

In facade mode, the client should discover list_catalogs, list_tools, and exec_tool, and can call owl.metric.list through exec_tool; in static mode, the client directly discovers business tools such as owl.metric.list. If the server is configured with an exclusion list, some tools will not appear. If you cannot connect, authentication fails, the tool list is empty, or the returned results are empty, see Troubleshooting.