Arthas 4 Meets AI: Diagnose Java Apps with Natural Language via MCP

What Arthas Does

Arthas is Alibaba's open-source Java diagnostic tool. It attaches to a running JVM so you can inspect threads, memory, trace method execution, observe parameters and return values, and decompile classes that are actually loaded in production. Typical commands include dashboard, thread -n 3, trace com.example.order.OrderService createOrder,

watch com.example.order.OrderService createOrder '{params,returnObj,throwExp}' -x 2

, and jad com.example.order.OrderService. The challenge for newcomers is knowing which command to run first when a symptom appears.

Arthas 4 supports JDK 8 and above, including JDK 17 and 21.

How Arthas 4 Connects to AI

Version 4.x adds the Arthas MCP Server , an implementation of the Model Context Protocol (MCP) originally proposed by Anthropic. MCP lets AI assistants call external tools as functions. Arthas exposes its diagnostic commands over HTTP on port 8563 at the /mcp endpoint (protocol version 2025-06-18, Streamable HTTP transport). The official documentation lists 29 tools, and clients such as Claude Desktop, Cherry Studio, and Cline can be configured to use it.

Think of it as Arthas opening a dedicated door for AI. Behind that door the same familiar capabilities — dashboard, thread, trace, watch, etc. — are executed.

From Natural Language to JVM

When you ask, "This endpoint is occasionally slow," the AI first decides whether to look at threads or run a trace, then sends the tool call via MCP to Arthas. Arthas executes the command inside the target JVM process, returns the raw result, and the AI summarizes it into a readable conclusion. This round-trip often repeats: the AI may start with the busiest threads, spot a suspicious method, run a trace, and finally deliver the answer. Parameters are assembled by the AI, but you should review the tool it plans to invoke before execution.

Enabling the MCP Server

Add the following to arthas.properties:

# Enable MCP, access path /mcp
arthas.mcpEndpoint=/mcp
# HTTP port, default is 8563
arthas.httpPort=8563

After Arthas starts, verify the endpoint: curl http://localhost:8563/mcp The response should contain MCP protocol information.

Client Configuration (Cherry Studio / Cline)

{
  "mcpServers": {
    "arthas-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:8563/mcp"
    }
  }
}

Authentication

If arthas.password is set in the properties file, MCP requires a Bearer token that matches the password exactly: arthas.password=your-secure-password Client config with authentication:

{
  "mcpServers": {
    "arthas-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:8563/mcp",
      "headers": {
        "Authorization": "Bearer your-secure-password"
      }
    }
  }
}

Transport Modes

Two modes are configured via arthas.mcpProtocol:

STREAMABLE (default) — maintains a session, suitable for long-running commands like watch, trace, monitor.

STATELESS — each request is independent, suitable for one-off queries like checking heap memory or JVM info.

Example: Diagnosing a Slow Order Creation Endpoint

Manually you might run:

thread -n 5
trace com.example.order.OrderService createOrder '#cost > 500' -n 20
stack com.example.order.OrderService createOrder -n 5

With MCP, you can simply tell the AI:

"The order service's createOrder occasionally exceeds 2 seconds. Please first check the top 5 busiest threads, then trace createOrder on com.example.order.OrderService, keeping only calls over 500 ms, up to 20 invocations. If a particular layer stands out, run a stack trace. Finally, tell me in plain language where the time is spent."

The AI will likely invoke thread, then trace, then stack as needed. To verify the running class matches the repository, add "decompile OrderService" which maps to jad.

CPU Profiling Example

"Perform a CPU sampling on the current Java process and tell me the hottest methods; keep the sampling duration short."

This uses the profiler tool. Sampling adds overhead, so on a busy machine you should ask for a shorter duration.

29 Tools Organized by Category

You don't need to memorize every name; the official documentation groups them into four categories:

JVM (13 tools)

dashboard

, memory, thread, jvm, heapdump, and others for overall runtime visibility.

Class / ClassLoader (8 tools)

sc

, sm, jad, classloader, redefine, etc., for inspecting and modifying loaded classes.

Monitoring & Diagnosis (6 tools)

monitor

, stack, trace, tt, watch, profiler for dynamic observation and performance analysis.

Utility (2 tools)

viewfile

— reads files only from an allowlist (default: arthas-output under the working directory and ~/logs/). Extend with the environment variable ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS (comma-separated paths). On Windows, set the same variable via system environment variables. options — views and modifies Arthas global settings.

Practical Advice Before You Start

Do not expose port 8563 to the public internet. Always set arthas.password and ensure the Bearer token matches exactly.

Commands that mutate running state — ognl , vmtool , redefine , retransform — require manual confirmation. After the AI proposes the call, review the parameters before allowing execution.

Long-running watch and trace sessions add overhead. Use STREAMABLE mode and stop them as soon as you have the data.

Verify AI conclusions against raw output. The AI's summary is convenient, but thread stacks and trace trees are worth inspecting yourself.