MCP Server (Legacy Version)¶

What is MCP Server?¶

MCP Server, the 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 the need to retrain the models.

Services built based on MCP Server ultimately provide a unified multi-model callable interface. This service supports multi-client access and uses an API Key authentication mechanism to securely access the core functionalities of Guance, 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 Guance 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 return structure and tool capabilities are designed around the actual business scenarios of Guance, making them suitable for querying, analysis, retrieval, and management tasks.

Download Version¶

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

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

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

Configure Guance MCP Service¶

1. Customize the service name and description.
2. Select type as streamableHttp.
3. Define the URL: https://obsy-ai.guance.com/obsy_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 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 determining 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, for example: cn1. The specific corresponding MAP is as follows:

SITE_KEY_MAP = {
    # === China SaaS Deployment ===
    "cn1": "https://openapi.guance.com",        # China Region 1 (Hangzhou) -- Default
    "cn2": "https://aws-openapi.guance.com",    # China Region 2 (Ningxia)
    "cn3": "https://cn3-openapi.guance.com",    # Free Zone (Beijing)
    "cn4": "https://cn4-openapi.guance.com",    # China Region 4 (Guangzhou)
    "cn6": "https://cn6-openapi.guance.one",    # China Region 6 (Hong Kong)
    "us1": "https://us1-openapi.guance.com",    # Global Region 1 (Oregon)
    "eu1": "https://eu1-openapi.guance.one",    # Europe Region 1 (Frankfurt)
    "ap1": "https://ap1-openapi.guance.one",    # Asia-Pacific Region 1 (Singapore)
    "za1": "https://za1-openapi.guance.com",    # Africa Region 1 (South Africa)
    "id1": "https://id1-openapi.guance.com",    # Indonesia Region 1 (Jakarta)
}

Calling the MCP Service¶

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

Verification:

hermes mcp list
hermes mcp test guance

Tool Overview¶

Currently, a total of 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 contain 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 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 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 (logs), M (metrics)
• 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 style:

• For simple queries, prefer 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.
• Use PromQL to query the CPU usage trend over the last 30 minutes.
• 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 past 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): 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 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): 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, up to 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 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 chronologically.

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 colleague for handling.
• Append a note about the latest progress 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 infrastructure object lists, supporting three resource types: hosts, containers, and processes.

Parameters:

• resource_type (Required, string): Resource type, supports host, container, process
• limit (Optional, int): Maximum number of items to return, up to 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 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 emails contain alice.

Metric¶

owl.metric.list¶

Toolset: metric

Function: Query the discovery results of sources or fields in the metric domain, for use in 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, performs an 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 for monitor rul_xxx.
• Create a monitor of type OuterEventChecker and bind it to the 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, for use in 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. Currently, calling this returns a fixed result DEFERRED_TOOL.

Parameters:

• None

Example prompts:

• Validate a Pipeline rule.
• Try executing the Pipeline validation tool.

Profile¶

owl.profile.list¶

Toolset: profile

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

Parameters:

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

Example prompts:

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

RUM¶

owl.rum.list¶

Toolset: rum

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

Parameters:

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

Example prompts:

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

APM¶

owl.apm.list¶

Toolset: apm

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

Parameters:

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

Example prompts:

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

Catalog¶

owl.catalog.query¶

Toolset: catalog

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

Parameters:

• None

Example prompts:

• Query Catalog content.
• Try executing the Catalog query tool.

owl.catalog.update¶

Toolset: catalog

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

Parameters:

• None

Example prompts:

• Update an object in the Catalog.
• Try executing 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 sources, fields, and indexes required for the query.
3. Finally, call owl.data.query to execute the formal query.

Alerting 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.