Skip to content

MCP Server (Legacy Version)

Legacy Documentation

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

What is MCP Server?

MCP Server, Model Context Protocol (MCP), 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 retraining the models.

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 TrueWatch's core functionalities, including monitors, logs, dashboards, and DQL queries.

Getting Started

  • The MCP Server service provides capability integration using the MCP standard protocol.
  • The service uses the TrueWatch API Key for authentication. The workspace for the request is determined by the workspace associated with the DF-API-KEY.
  • The service uniformly exposes tool capabilities to AI clients, with consistent calling methods, facilitating reuse across different models and clients.
  • The service's response structure and tool capabilities are designed around TrueWatch's actual business scenarios, suitable for query, analysis, retrieval, and management tasks.
Integration Methods

More integration methods are under development. Stay tuned!

Download Version

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

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

Here, using Volcengine as an example, configure the API key.

Configure TrueWatch MCP Service

  1. Custom input service name and description.
  2. Select type as streamableHttp.
  3. Define URL: https://us1-toby-ai.truewatch.com/toby_ai_mcp/mcp.
  4. Request header format: 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 as the authentication method. Each request uses the value of DF-API-KEY in the request header for validity verification and as the basis for limiting the workspace for this request (using the workspace to which this DF-API-KEY belongs).

  • All interfaces currently exposed by the MCP service only require providing the 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, e.g., us2. The specific corresponding MAP is as follows:

SITE_KEY_MAP = {
    # === International TrueWatch Deployment ===
    "us2": "https://us1-openapi.truewatch.com", # Global 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)
}

Calling the 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 include at least title and main.charts

Example prompts:

  • Help me create a dashboard named "APM Overview" with the same title, start 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 the new configuration I give you.
  • 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. When full expressive power is needed, prioritize using query_text, as it is suitable for directly writing official DQL syntax, 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 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:

  • 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 ..., but write in DQL form like L::source:(count(*)) ... BY ....

Example prompts:

  • Query 500 errors in Nginx logs from the last hour.
  • Use PromQL to query the CPU usage trend over the last 30 minutes.
  • Query detailed data for the nginx source in the default index under the log namespace.
  • Count the number of nginx logs grouped by source and status over the last hour.

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 new 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): Extension 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 for 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): Extension fields

Example prompts:

  • Update comment comment_xxx to "Root cause confirmed, fixing."
  • 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 with status "Alerting" from the last day, 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 detailed information for 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 by time.

owl.incident_comment.add

Toolset: incident_comment

Function: Add a new 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 team member for handling.
  • Append a latest progress note under 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 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 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 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 log index list, suitable for determining available indexes before 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 member list

Parameters:

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

Example prompts:

  • List all members in the current workspace.
  • Search for members whose emails contain alice.

Metric

owl.metric.list

Toolset: metric

Function: Query source or field discovery results in the metric domain, for subsequent data queries.

Parameters:

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

Example prompts:

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

Monitor

owl.monitor.list

Toolset: monitor

Function: Query 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, performs 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): Extension fields
  • tags (Optional, array): List of tags

Example prompts:

  • Create a monitor for high CPU usage.
  • Update the title and alert message for monitor rul_xxx.
  • Create a monitor of type OuterEventChecker 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 source or field discovery results in the network domain, for subsequent data queries.

Parameters:

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

Example prompts:

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

Pipeline

owl.pipeline.list

Toolset: pipeline

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

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 Pipeline. Currently, calling returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

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

Profile

owl.profile.list

Toolset: profile

Function: Query source or field discovery results in the performance profiling domain, for subsequent data queries.

Parameters:

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

Example prompts:

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

RUM

owl.rum.list

Toolset: rum

Function: Query source or field discovery results in the RUM domain, for subsequent data queries.

Parameters:

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

Example prompts:

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

APM

owl.apm.list

Toolset: apm

Function: Query source or field discovery results in the APM domain, for subsequent data queries.

Parameters:

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

Example prompts:

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

Catalog

owl.catalog.query

Toolset: catalog

Function: Query Catalog. Currently, calling returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

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

owl.catalog.update

Toolset: catalog

Function: Update Catalog. Currently, calling returns a fixed result DEFERRED_TOOL.

Parameters:

  • None

Example prompts:

  • Update an object in the Catalog.
  • Attempt 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. As needed, call owl.metric.list, owl.rum.list, owl.apm.list, owl.network.list, owl.profile.list, owl.log_index.list, owl.field_schema.get to obtain the required source, field, index for the query.
  3. Finally call owl.data.query to execute the formal query.

Alert and Incident Handling 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.