Skip to content

MCP Server (Legacy Version)

Legacy Documentation

This document is the legacy MCP Server integration guide, maintained for historical compatibility only. For new integrations, please refer to MCP Server Quick Start first.

What is MCP Server?

MCP Server, the Model Context Protocol, is an open protocol designed to standardize secure connections and data source access between applications and AI models. Its core goal is to enable developers to easily provide context information (such as data, content, operations) to models through unified "tools" and "resources", thereby enhancing model capabilities without the need for retraining.

Services built based on MCP Server ultimately provide a unified multi-model callable interface. This service supports multi-client access and employs an API Key authentication mechanism to securely access the core functionalities of TrueWatch, including monitors, logs, dashboards, and DQL queries.

Getting Started

This example uses the Cherry Studio integration method.

Integration Methods

More integration methods are under development. Stay tuned!

Download Version

  1. Download the MCP Server client Cherry Studio and select the appropriate version.

  2. Open Cherry Studio and start configuring the foundational large model service.

This example uses Volcengine to configure the API key.

Configure TrueWatch MCP Service

  1. Customize the service name and description.
  2. Select type as streamableHttp.
  3. Define the URL: https://us1-toby-ai.truewatch.com/toby_ai_mcp/mcp.
  4. The request header format is: Authorization=DF-API-KEY;Endpoint=SITE_KEY.
  5. After configuring the MCP service, save and enable it. Then return to the homepage and select the MCP service.

Configuration Notes

  • The interface uses API KEY for authentication. Each request uses the value of DF-API-KEY in the request header for validity verification and as the basis for workspace limitation for this request (using the workspace to which this DF-API-KEY belongs).

  • All interfaces currently displayed by the MCP service only require providing an API KEY (Header: DF-API-KEY) as the credential. If the credential exists and is valid, authentication is considered passed.

  • The MCP Endpoint configuration parameter is SITE_KEY, for example: us2. The specific corresponding MAP is as follows:

SITE_KEY_MAP = {
    # === Overseas TrueWatch Deployment ===
    "us2": "https://us1-openapi.truewatch.com", # Overseas Region 2 (Oregon)
    "eu2": "https://eu1-openapi.truewatch.com", # Europe Region 2 (Frankfurt)
    "ap2": "https://ap1-openapi.truewatch.com", # Asia-Pacific Region 2 (Singapore)
    "za2": "https://za1-openapi.truewatch.com", # Africa Region 2 (South Africa)
    "id2": "https://id1-openapi.truewatch.com", # Indonesia Region 2 (Jakarta)
}

Call MCP Service

mcp_servers:
  guance:
    type: streamableHttp
    url: https://owl-mcp.guance.com/mcp
    headers:
      Authorization: Bearer TrueWatch API Key>
    enabled: true

Verification:

hermes mcp list
hermes mcp test guance

Tool Overview

Currently, 37 business tools are provided, covering Dashboard, Data, Errors, Event, Field Schema, Incident, Infrastructure, LLM, Log Index, Member, Metric, Monitor, Pipeline, APM, RUM, Network, Profile, Catalog, and other domains.

Dashboard

owl.dashboard.create

Toolset: dashboard

Function: Create a dashboard

Parameters:

  • name (Required, string): Dashboard name
  • dashboard_json (Required, object): Dashboard template content, must at least include title and main.charts

Example prompts:

  • Help me create a dashboard named "APM Overview" with the same title, initially with empty charts.
  • Create a new Nginx monitoring dashboard according to the dashboard_json I provide.

owl.dashboard.replace

Toolset: dashboard

Function: Replace the content of an existing dashboard

Parameters:

  • dashboard_uuid (Required, string): Target dashboard UUID
  • dashboard_json (Required, object): New dashboard template content

Example prompts:

  • Replace the dashboard dsbd_xxx with this new version configuration I provide.
  • Update the title and chart layout of the specified dashboard using this dashboard_json.

owl.dashboard.get

Toolset: dashboard

Function: Get dashboard details

Parameters:

  • dashboard_uuid (Required, string): Dashboard UUID

Example prompts:

  • Query the detailed content of dashboard dsbd_xxx.
  • Retrieve the complete configuration corresponding to this dashboard UUID.

Data

owl.data.show_dql_namespace

Toolset: data

Function: View the currently supported DQL namespaces, and whether each namespace supports the index parameter.

Parameters:

  • None

Example prompts:

  • List the currently supported DQL namespaces.
  • Which data namespaces support passing index?

owl.data.query

Toolset: data

Function: Execute Guance's DQL or PromQL queries, applicable to data domains such as logs, metrics, RUM, APM, Network, Profile, etc. If unsure about dql_namespace, call owl.data.show_dql_namespace first. Prioritize using query_text when full expressive power is needed, as it is suitable for writing official DQL syntax directly, such as filtering, time windows, BY grouping, HAVING, ORDER BY, aliases, and aggregate functions. Note that DQL grouping syntax is BY ..., not SQL-style GROUP BY.

Parameters:

  • dql_namespace (Required, string): Query namespace, common ones like L (Log), M (Metric)
  • start_time (Required, int): Start time, 13-digit millisecond timestamp
  • end_time (Required, int): End time, 13-digit millisecond timestamp
  • query_mode (Optional, string): Query mode, supports dql or promql, where promql is only applicable to metric-type queries.
  • query_text (Optional, string): Complete query statement. When writing DQL, follow the official syntax, e.g., L::nginx:(count(*)) [1h] BY source, status, do not write GROUP BY.
  • source (Optional, string): Data source name used to construct a simple query when query_text is not provided.
  • select (Optional, string[]): List of select expressions used to construct a simple query when query_text is not provided.
  • index (Optional, string): Index name used for the log namespace, corresponding to namespace[index] in DQL.

Recommended writing style:

  • For simple queries, prioritize using source + select.
  • When needing WHERE, BY, HAVING, ORDER BY, complex functions, aliases, or more complete semantics, prioritize using query_text.
  • For log statistics, do not write COUNT(L::*) GROUP BY .... Instead, write in DQL form like L::source:(count(*)) ... BY ....

Example prompts:

  • Query 500 errors in Nginx logs from the last hour.
  • Query CPU usage trends for the last 30 minutes using PromQL.
  • Query detailed data for the nginx source within the default index in the log namespace.
  • Count the number of nginx logs in the last hour grouped by source and status.

Errors

owl.errors.list

Toolset: errors

Function: Query the error center list

Parameters:

  • start_time (Required, int): Start time, 13-digit millisecond timestamp
  • end_time (Required, int): End time, 13-digit millisecond timestamp
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number
  • conditions (Optional, string): Filter expression
  • assigner (Optional, string): Assignee filter condition
  • issue_status (Optional, string): Error status filter condition

Example prompts:

  • Query the error center list for the last 24 hours.
  • Check the high-priority error issues currently assigned to Alice.
  • Filter Java exception issues from the last week based on conditions.

owl.errors.comment.add

Toolset: errors

Function: Add a comment to an error issue

Parameters:

  • issue_id (Required, string): Error issue ID
  • comment (Required, string): Comment content
  • attachment_uuids (Optional, string[]): List of attachment UUIDs
  • extend (Optional, object): Extended fields

Example prompts:

  • Add a comment to issue_xxx: Please check the latest release first.
  • Append a handling note to this error issue, along with a list of attachment IDs.

owl.errors.comment.list

Toolset: errors

Function: Query the comment list of an error issue

Parameters:

  • issue_id (Required, string): Error issue ID
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number

Example prompts:

  • List all comments for issue_xxx.
  • View the most recent page of comment records for this error issue.

owl.errors.comment.update

Toolset: errors

Function: Update an existing error comment

Parameters:

  • comment_uuid (Required, string): Comment UUID
  • comment (Required, string): Updated comment content
  • attachment_uuids (Optional, string[]): List of attachment UUIDs
  • extend (Optional, object): Extended fields

Example prompts:

  • Update comment comment_xxx to "Root cause confirmed, fixing in progress."
  • Update the body of this error comment and supplement the attachment list.

Event

owl.event.list

Toolset: event

Function: Query the event list

Parameters:

  • start_time (Required, int): Start time, 13-digit millisecond timestamp
  • end_time (Required, int): End time, 13-digit millisecond timestamp
  • status (Optional, string): Event status
  • limit (Optional, int): Maximum number of items to return, max 100

Example prompts:

  • Query the event list for the last 6 hours.
  • List events from the last day with status "Alerting", returning up to 50 items.

owl.event.get

Toolset: event

Function: Get event details

Parameters:

  • doc_id (Required, string): Event document ID

Example prompts:

  • View the detailed information of event doc_xxx.
  • Display the complete original event content corresponding to this event ID.

Field Schema

owl.field_schema.get

Toolset: field_schema

Function: Get a simplified field catalog, suitable for viewing available fields before constructing query conditions or selecting fields.

Parameters:

  • None

Example prompts:

  • List the currently available field catalog.
  • I want to write a data query, first show me the field list.

Incident

owl.incident.list

Toolset: incident

Function: Query the Incident list

Parameters:

  • search (Optional, string): Keyword search
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number

Example prompts:

  • Query the current Incident list.
  • Search for Incidents whose names contain "Redis".

Incident Comment

owl.incident_comment.list

Toolset: incident_comment

Function: Query the comment list for a specified Incident

Parameters:

  • incident_uuid (Required, string): Incident UUID

Example prompts:

  • View the comment list for Incident inc_xxx.
  • List all comments under this Incident chronologically.

owl.incident_comment.add

Toolset: incident_comment

Function: Add a comment to a specified Incident

Parameters:

  • incident_uuid (Required, string): Incident UUID
  • comment (Required, string): Comment content

Example prompts:

  • Add a comment to inc_xxx: Contacting the on-duty engineer for handling.
  • Append a latest progress note to this Incident.

Incident Operation

owl.incident_operation.list

Toolset: incident_operation

Function: Query Incident operation records

Parameters:

  • incident_uuid (Required, string): Incident UUID
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number

Example prompts:

  • View the operation records for inc_xxx.
  • List the recent two pages of operation history for this Incident.

Incident Schedule

owl.incident_schedule.list

Toolset: incident_schedule

Function: Query the Incident schedule list

Parameters:

  • search (Optional, string): Schedule name keyword
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number

Example prompts:

  • List all current Incident schedules.
  • Search for schedules whose names contain "SRE".

owl.incident_schedule.get

Toolset: incident_schedule

Function: Get Incident schedule details

Parameters:

  • schedule_uuid (Required, string): Schedule UUID

Example prompts:

  • View the detailed configuration of schedule schedule_xxx.
  • Display the timezone, time periods, and notification targets for this on-duty schedule.

Infrastructure

owl.infrastructure.list

Toolset: infrastructure

Function: Query the infrastructure object list, supporting three resource types: host, container, process.

Parameters:

  • resource_type (Required, string): Resource type, supports host, container, process
  • limit (Optional, int): Maximum number of items to return, max 100
  • filters (Optional, object[]): List of filter conditions. Each item contains field, op, value

Example prompts:

  • List recently visible host objects.
  • Query containers whose names contain prod, returning up to 20 items.
  • Filter the process object list based on field conditions.

owl.infrastructure.get

Toolset: infrastructure

Function: Get details of a single infrastructure object

Parameters:

  • resource_type (Required, string): Resource type, supports host, container, process
  • identity_value (Required, string): Object identifier value

Example prompts:

  • View detailed information for host host-01.
  • Get the complete object details for container container_xxx.

LLM

owl.llm.list

Toolset: llm

Function: Query the LLM application list

Parameters:

  • search (Optional, string): Keyword search
  • type (Optional, string): Application type filter
  • page_size (Optional, int): Number of items per page
  • page_index (Optional, int): Page number

Example prompts:

  • List all current LLM applications.
  • Search for LLM applications whose names contain "chat".
  • Filter by type and return the first page of the application list.

Log Index

owl.log_index.list

Toolset: log_index

Function: Query the log index list, suitable for determining available indexes before performing log queries.

Parameters:

  • None

Example prompts:

  • List all current log indexes.
  • I'm about to query logs, first show me the available indexes.

owl.log_index.get

Toolset: log_index

Function: Get log index details

Parameters:

  • index_uuid (Required, string): Log index UUID

Example prompts:

  • View the detailed configuration of log index index_xxx.
  • Display the index details corresponding to this index UUID.

Member

owl.member.list

Toolset: member

Function: Query the member list

Parameters:

  • search (Optional, string): Member name or email keyword

Example prompts:

  • List all members of the current workspace.
  • Search for members whose email contains alice.

Metric

owl.metric.list

Toolset: metric

Function: Query the discovery results of sources or fields in the metric domain, used for subsequent data queries.

Parameters:

  • mode (Optional, string): source or field, default is source

Example prompts:

  • List currently available metric sources.
  • See which fields in the metric domain can be used for queries.

Monitor

owl.monitor.list

Toolset: monitor

Function: Query the monitor list

Parameters:

  • search (Optional, string): Monitor name keyword
  • status_list (Optional, int[]): Status list, supports 0, 2

Example prompts:

  • List all current monitors.
  • Query enabled monitors whose names contain "CPU".

owl.monitor.get

Toolset: monitor

Function: Get monitor details

Parameters:

  • rule_uuid (Required, string): Monitor rule UUID

Example prompts:

  • View the detailed configuration of monitor rul_xxx.
  • Retrieve the complete definition of this monitor rule.

owl.monitor.upsert

Toolset: monitor

Function: Create a monitor, or update an existing monitor when rule_uuid is provided.

Parameters:

  • json_script (Required, object): Monitor configuration object
  • rule_uuid (Optional, string): Existing monitor rule UUID, triggers update when provided.
  • status (Optional, int): Monitor status, supports 0, 2
  • secret (Optional, string): Used when json_script.type is OuterEventChecker.
  • alert_policy_uuids (Optional, string[]): List of alert policy UUIDs
  • extend (Optional, object): Extended fields
  • tags (Optional, array): List of tags

Example prompts:

  • Create a monitor for high CPU usage.
  • Update the title and alert message of monitor rul_xxx.
  • Create an OuterEventChecker type monitor and bind it to specified alert policies.

owl.monitor.receive

Toolset: monitor

Function: Receive external events. Supports direct delivery to an existing target, or creating an OuterEventChecker first and then delivering the event.

Parameters:

  • event (Required, object): Event object, must contain status, title, message, dimension_tags, check_value
  • target (Optional, object): Existing event receiving target, contains secret, sub_uri
  • monitor (Optional, object): Monitor configuration for creating a receiving target, contains secret, sub_uri, status, title, message_template, alert_policy_uuids
  • extra_data (Optional, object): Additional data

Example prompts:

  • Send this external alert event to the specified target.
  • First create an event receiving monitor, then push the CPU alert event into it.
  • Report a critical event using the existing secret and sub_uri.

Network

owl.network.list

Toolset: network

Function: Query the discovery results of sources or fields in the network domain, used for subsequent data queries.

Parameters:

  • mode (Optional, string): source or field, default is source

Example prompts:

  • List currently available network sources.
  • See which fields in the network domain can be directly queried.

Pipeline

owl.pipeline.list

Toolset: pipeline

Function: Query the Pipeline list and return Pipeline content that can be read directly.

Parameters:

  • search (Optional, string): Pipeline name keyword
  • scope (Optional, string): Pipeline scope
  • categories (Optional, string[]): Category filter list

Example prompts:

  • List all current Pipelines.
  • Search for Pipelines whose names contain nginx.
  • Query Pipelines under the local scope with specified categories.

owl.pipeline.validate

Toolset: pipeline

Function: Validate a Pipeline. The current call returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

  • Validate a Pipeline rule.
  • Try to execute the Pipeline validation tool.

Profile

owl.profile.list

Toolset: profile

Function: Query the discovery results of sources or fields in the performance profiling domain, used for subsequent data queries.

Parameters:

  • mode (Optional, string): source or field, default is source

Example prompts:

  • List currently available profile sources.
  • See which fields are in the profile domain.

RUM

owl.rum.list

Toolset: rum

Function: Query the discovery results of sources or fields in the RUM domain, used for subsequent data queries.

Parameters:

  • mode (Optional, string): source or field, default is source

Example prompts:

  • List currently available RUM sources.
  • See which fields are in the RUM domain.

APM

owl.apm.list

Toolset: apm

Function: Query the discovery results of sources or fields in the APM domain, used for subsequent data queries.

Parameters:

  • mode (Optional, string): source or field, default is source

Example prompts:

  • List currently available APM sources.
  • See which fields are in the APM domain.

Catalog

owl.catalog.query

Toolset: catalog

Function: Query Catalog. The current call returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

  • Query Catalog content.
  • Try to execute the Catalog query tool.

owl.catalog.update

Toolset: catalog

Function: Update Catalog. The current call returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

  • Update an object in the Catalog.
  • Try to execute the Catalog update tool.

Typical Usage Paths

Data Analysis Questions

  1. First call owl.data.show_dql_namespace to confirm the namespace.
  2. Call owl.metric.list, owl.rum.list, owl.apm.list, owl.network.list, owl.profile.list, owl.log_index.list, owl.field_schema.get as needed to obtain the required source, field, index for the query.
  3. Finally call owl.data.query to execute the formal query.

Alerting and Troubleshooting Questions

  1. Use owl.monitor.list, owl.monitor.get to view monitors.
  2. Use owl.event.list, owl.event.get to view events.
  3. Use owl.incident.list, owl.incident_comment.list, owl.incident_operation.list to view Incident progress.
  4. Use owl.errors.list and comment tools to track error issue handling processes.

Configuration Management Questions

  1. Use owl.dashboard.create, owl.dashboard.replace, owl.dashboard.get to manage dashboards.
  2. Use owl.pipeline.list to view Pipelines.
  3. Use owl.monitor.upsert to create or update monitors.