MCP Server Quick Start¶

OWL MCP Server is a server-side implementation provided by TrueWatch based on the Model Context Protocol. It encapsulates capabilities such as TrueWatch Metrics, Logs, Events, Monitors, APM, RUM, Infrastructure, and Notes into MCP tools, which can be called by AI clients that support MCP.

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

Representative tools that MCP clients can call include:

• Cross-Workspace Trace Query within the Same Organization: First, discover candidate workspaces using owl.account.workspace.same_org.list, then pass the returned workspace_uuid as workspace_uuids to owl.data.same_org.trace.query; workspace_id is only used for list pagination and cannot be used for queries.
• 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; supports normal and runbook types. list can filter by type, add can set type. Only get returns the Markdown body. add, modify, and delete are write tools, it is recommended to configure human 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 event details by event document ID.
• Pipeline Query and Sample Validation: owl.pipeline.list / owl.pipeline.validate, used to query Pipelines, or validate processing results using sample data; validation only performs tests and does not create or modify Pipelines.
• Simplified Data Query: owl.data.simple_query, provides a more user-friendly data query entry.
• Document Retrieval: mdsearch_search / mdsearch_document / mdsearch_catalog, used to retrieve TrueWatch documentation.
• SLO List: owl.slo.list, lists configured SLOs.

Prerequisites¶

Before accessing, ensure the following preparations are complete:

1. A TrueWatch API Key with the 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 has been configured in the MCP client.
4. The current network environment can access the OWL MCP Endpoint.

Endpoint¶

OWL MCP Server provides independent Endpoints per site. Select the corresponding address based on the site of your workspace.

Authentication¶

Configure the request header in the MCP client:

Authorization: Bearer <API Key>

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

OWL MCP Server performs authentication before entering MCP processing. Requests without authentication or with invalid credentials will be directly rejected, returning 401 Unauthorized with the response header WWW-Authenticate: Bearer realm="mcp". Additionally, rate limiting will return 429, and requests from IPs not on the whitelist will 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 clients; please refer to the actual client documentation.

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

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

The following examples use the placeholder address your-owl-mcp-endpoint. When connecting, 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 as follows:

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

After configuration, save and enable it, then return to the client home page 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¶

After configuration, you can ask the MCP client:

List the available metric sources.

The client should be able to discover list_catalogs, list_tools, exec_tool, and can call owl.metric.list via exec_tool. If connection fails, authentication fails, the tool list is empty, or the returned result is empty, please refer to Troubleshooting.