Use CLS MCP Server to Query Logs with Natural Language from an LLM Client

Operations teams often know what they want to ask before they know the exact log query to write. They may need answers such as failed login counts for today, suspicious IP activity in the last 24 hours, or recent error patterns for a service. Tencent Cloud CLS MCP Server puts a Model Context Protocol interface in front of CLS so an LLM client can query logs, generate search statements from natural language, and resolve supporting context such as log topic IDs and region abbreviations.

The useful shift is not that log search becomes magical. The useful shift is that the assistant has a narrower, structured bridge into the log platform instead of trying to infer everything from free-form text.

What the CLS MCP Server adds

CLS MCP Server is a lightweight service based on the Model Context Protocol. It connects a large language model to external resources through a standardized interface. In this case, the resource is Tencent Cloud Log Service.

The implementation described here focuses on three capabilities:

Capability	What it does	Why it matters during operations
Log search	Runs a query against logs stored in a CLS log topic	Lets an assistant retrieve operational evidence instead of only giving generic advice
Natural-language query generation	Converts daily-language requests into CLS search statements	Helps less experienced users start from intent while keeping the query grounded in CLS syntax
Context helpers	Looks up topic IDs from topic names, region abbreviations from region names, and current timestamps	Reduces common LLM errors caused by missing IDs, wrong regions, or vague time windows

These helper abilities are especially important. Log search usually fails for boring reasons: the topic name was not mapped to the topic ID, the region was not normalized, or the time window was ambiguous. Giving the LLM tool-level access to that context lowers the chance of a plausible but wrong query.

Required CLS permissions

Create a Tencent Cloud sub-account and grant only the actions needed for this workflow. The permission policy used here allows log search, topic description, and CLS chat completion access:

{
  "version": "2.0",
  "statement": [
    {
      "effect": "allow",
      "action": [
        "cls:SearchLog",
        "cls:DescribeTopics",
        "cls:ChatCompletions"
      ],
      "resource": ["*"]
    }
  ]
}

After the policy is attached, keep the SecretId and SecretKey available for the MCP client configuration.

Configure an MCP client with stdio

The example client is Cherry Studio. The server runs through npx, and Tencent Cloud credentials are passed as environment variables.

Cherry Studio can run cls-mcp-server through a stdio MCP configuration with Tencent Cloud credentials in environment variables.

{
  "mcpServers": {
    "cls-mcp-server": {
      "isActive": true,
      "name": "cls-mcp-server",
      "type": "stdio",
      "registryUrl": "",
      "command": "npx",
      "args": [
        "-y",
        "cls-mcp-server"
      ],
      "env": {
        "TENCENTCLOUD_SECRET_ID": "YOUR_TENCENT_SECRET_ID",
        "TENCENTCLOUD_SECRET_KEY": "YOUR_TENCENT_SECRET_KEY",
        "TENCENTCLOUD_API_BASE_HOST": "tencentcloudapi.com",
        "TENCENTCLOUD_REGION": "ap-guangzhou",
        "MAX_LENGTH": "15000"
      }
    }
  }
}

The key fields are:

Field	Purpose
command	Starts the server with npx
args	Installs and runs cls-mcp-server with -y
TENCENTCLOUD_SECRET_ID and TENCENTCLOUD_SECRET_KEY	Tencent Cloud API credentials
TENCENTCLOUD_API_BASE_HOST	Tencent Cloud API host, set to tencentcloudapi.com
TENCENTCLOUD_REGION	Default CLS region, such as ap-guangzhou
MAX_LENGTH	Response length guardrail for returned log content

Where MCP is stronger than a single Dify Tool

CLS can also be connected through a Dify Tool. The distinction is that the MCP Server path includes more context-aware helpers around log search.

MCP Server adds context helpers that are not available in the Dify Tool path, including topic-name lookup, region-name lookup, and current timestamp support.

Function	Dify Tool	MCP Server
Query logs	Supported	Supported
Generate a log query from natural language	Not supported in the same reliable way	Supported
Find a log topic ID from a topic name	Not supported	Supported
Find a region abbreviation from a region name	Not supported	Supported
Get the current timestamp	Not supported	Supported

That makes MCP a better fit when the assistant needs to move from an operational question to a concrete CLS query without making the operator manually supply every ID and timestamp.

Good first queries to test

Start with questions where the expected result can be verified quickly:

• "Find recent error logs for this topic in the last 30 minutes."

• "Count failed login events today."

• "Check suspicious IP access records from the past 24 hours."

• "Show the newest logs for this service and summarize the most frequent error messages."

For production usage, keep the assistant's answer tied to retrieved log evidence. The assistant can summarize, but the underlying query result should remain inspectable.

Operational guardrails

Use the MCP connection as a production interface, not a demo shortcut.

Guardrail	Practical implementation
Scope credentials narrowly	Use a sub-account and grant only the CLS actions needed for log search and topic lookup
Confirm the default region	Set TENCENTCLOUD_REGION to the region where the log topics live
Keep response size bounded	Use MAX_LENGTH so accidental broad queries do not flood the client
Verify generated queries	Treat natural-language query generation as a starting point for high-risk investigations
Keep topic naming clean	Clear log topic names make topic-ID lookup more reliable

FAQ

Does the MCP Server replace the CLS console?

No. It gives an LLM client a structured way to query CLS and resolve context. The console remains useful for deeper inspection, dashboards, and manual query tuning.

What problem does topic-name lookup solve?

Humans usually remember service or topic names. APIs usually need exact topic IDs. Topic-name lookup bridges that gap so the assistant does not guess IDs.

Why pass the current timestamp through the tool layer?

Time-window mistakes are common in log search. A tool-provided timestamp gives the assistant a concrete anchor for questions like "today", "last hour", or "past 24 hours".

When should Dify Tool still be considered?

Use it when the workflow is already built around Dify and only needs the supported log-query capability. Use MCP when the assistant needs richer context helpers around the query.