MCP Server Quickstart¶

OWL MCP Server is a server-side implementation based on the Model Context Protocol, provided by TrueWatch. It encapsulates TrueWatch capabilities—including metrics, logs, events, monitors, APM, RUM, infrastructure, and notes—as MCP tools, which can be invoked by any MCP-compatible AI client.

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

The server supports two modes of tool exposure: the default facade mode provides three wrapper tools (list_catalogs, list_tools, exec_tool); the static mode directly exposes the allowed business tools via the MCP tools/list endpoint. The mode is determined by server configuration and does not require the client to switch transport protocols.

Representative tools that can be invoked by an MCP client include:

• Cross-workspace Trace query within the same organization: First discover candidate workspaces with 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 in queries.
• Notes (owl.nbook_note.list / owl.nbook_note.get / owl.nbook_note.add / owl.nbook_note.modify / owl.nbook_note.delete): 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 manual confirmation in the MCP client.
• Event queries (owl.event.list / owl.event.get): Query events by time range and status, and retrieve event details by document ID.
• Pipeline queries and sample validation (owl.pipeline.list / owl.pipeline.validate): Query Pipelines or validate processing results with sample data. Validation only runs tests and does not create or modify Pipelines.
• Simplified data query (owl.data.simple_query): A more user-friendly data query entry.
• Document search (mdsearch_search / mdsearch_document / mdsearch_catalog): Search TrueWatch documentation.
• SLO list (owl.slo.list): List configured SLOs.

Prerequisites¶

Before connecting, ensure the following are ready:

1. An TrueWatch API Key with the required business permissions has been created
2. The OWL MCP Endpoint corresponding to the workspace's site has been obtained
3. The MCP client is configured to connect to the OWL MCP service
4. The current network environment can reach the OWL MCP Endpoint

Endpoint¶

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

Authentication¶

Configure the request header in your MCP client:

Authorization: Bearer <API Key>

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

OWL MCP Server authenticates the request before processing it via MCP. Unauthenticated or invalid credentials will be rejected with a 401 Unauthorized response and the header WWW-Authenticate: Bearer realm="mcp". Additionally, rate limiting returns 429, and requests from IPs not in the whitelist return 403.

Client Configuration¶

OWL MCP Server uses the standard streamableHttp transport, which can be used by any MCP client that supports this transport. Configuration entry points and field names may vary slightly between clients; refer to the actual client documentation for details.

The following examples illustrate configuration for Cherry Studio, Claude Code, Codex, OpenClaw, and Hermes. Other MCP clients that support streamableHttp can be configured following the same principles:

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

The placeholder your-owl-mcp-endpoint is used in the examples below. When connecting, replace it with the actual OWL MCP Endpoint for your workspace's site.

Cherry Studio¶

Add a new MCP service in Cherry Studio with the following configuration:

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

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

Claude Code¶

Claude Code uses the http type to connect to a Streamable HTTP service. 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, injecting the full authentication string via a team-approved credential management method. Do not write actual credentials directly into .mcp.json or commit them to the repository. After saving, restart Claude Code and run claude mcp list; you can also type /mcp in a session to confirm that owl is connected and tools are discoverable.

Codex¶

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

To configure manually, Codex desktop, CLI, and IDE extensions share MCP configuration. Edit ~/.codex/config.toml and add the following:

[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 Codex is launched, set OWL_MCP_API_KEY to your TrueWatch API Key. Codex automatically sends this value as a Bearer Token; do not prepend Bearer in the variable value, and do not write actual credentials directly into config.toml or commit them to the repository.

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

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, we recommend following these conventions:

Verification¶

After configuration, you can ask your MCP client:

List the available metric sources.

In facade mode, the client should discover list_catalogs, list_tools, exec_tool, and can invoke owl.metric.list via exec_tool. In static mode, the client will directly discover business tools such as owl.metric.list. If the server has an exclusion list configured, some tools will not appear. If you cannot connect, authentication fails, the tool list is empty, or the returned results are empty, refer to Troubleshooting.