Arthas 4 + AI: 29 JVM Diagnostic Commands Now Automated via MCP

Arthas 4 adds an official experimental module — Arthas MCP Server — that exposes the tool’s 29 diagnostic commands as AI-callable tools through the Model Context Protocol (MCP). The module is not a third-party wrapper; it runs inside Arthas, uses HTTP/Netty to serve a standard JSON-RPC 2.0 endpoint aligned with MCP 2025-06-18, and communicates via StreamableHTTP.

Underlying diagnostic engine unchanged

The core bytecode-enhancement mechanism remains the same: Instrumentation API plus ASM bytecode weaving. When you invoke trace com.example.Service getOrder, Arthas inserts probes at method entry/exit to measure latency and restores the original bytecode on exit — zero code change, zero restart. The difference is the entry point: instead of a human typing commands, an AI agent drives the tools according to a troubleshooting playbook.

Enabling the MCP endpoint

Add three lines to arthas.properties:

# Enable MCP endpoint, default port 8563
arthas.mcpEndpoint=/mcp
# Transport mode: STREAMABLE (stateful) or STATELESS (stateless), default STREAMABLE
arthas.mcpProtocol=STREAMABLE
# Setting a password enables mandatory Bearer Token auth
arthas.password=your-secure-password

After startup, verify with: curl http://localhost:8563/mcp A valid MCP protocol response confirms the server is alive.

Connecting AI clients

Register the server in your AI client (Cherry Studio, Cline, Claude Desktop, etc.) using a StreamableHTTP configuration with the Bearer token:

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

29 tools, four categories

JVM & runtime (13) : dashboard, thread, heapdump, memory, jvm, sysprop, sysenv, vmoption, perfcounter, vmtool, getstatic, ognl, mbean — inspect resources, threads, heap, memory, system properties, environment, VM options, performance counters, and MBeans.

Class & ClassLoader (8) : sc (search class), sm (search method), jad (decompile), mc (memory compile), redefine, retransform (hot-reload), dump (export bytecode), classloader — resolve class conflicts, view source, modify code on the fly.

Monitoring & profiling (6) : monitor (call stats), stack (caller stack), trace (method latency), tt (time-tunnel: record/replay args & returns), watch (observe args/return/exceptions), profiler (flame graphs).

Auxiliary (2) : options (global switches), viewfile (read files via whitelist — default arthas-output and ~/logs/; extend via ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS).

Real-world walkthrough: CPU 98% on order service

Symptom : Nightly peak, order service CPU at 98%, all requests timing out, not reproducible locally.

Old manual flow : Run dashboard → note high-CPU thread ID → run thread <id> → visually scan stack → locate suspicious code → fix → redeploy. Any forgotten command or OGNL expression caused delays.

New AI-driven flow : Tell the AI client: "Order service CPU hit 98%, find the offending thread and where it's stuck."

AI calls dashboard → returns thread table showing thread 29 (http-nio-8080-exec-8) at 89.2% CPU , RUNNABLE.

AI calls thread 29 → returns stack trace:

"http-nio-8080-exec-8" #29 runnable
  at java.util.regex.Pattern$GroupHead.match(Pattern.java:4660)
  at java.util.regex.Pattern$GroupTail.match(Pattern.java:4719)
  at java.util.regex.Pattern$Curly.match(Pattern.java:4238)
  at com.example.logging.LogAspect.logAround(LogAspect.java:47)
  at com.example.order.service.OrderService.getOrder(OrderService.java:123)

AI analyzes: thread stuck in regex matching inside LogAspect.java:47. The desensitization regex uses a greedy .* with backtracking; request bodies >10 KB trigger catastrophic backtracking, consuming CPU.

AI proposes fix: disable the aspect temporarily for mitigation; permanently replace .* with [^"]* to avoid backtracking, or switch to indexOf plus a 2000-character length limit.

Throughout, dashboard located the thread, thread fetched the stack, AI performed analysis and suggestion. The human shifts from command recall to conversational validation.

Critical caveats

STREAMABLE vs STATELESS : Default STREAMABLE maintains long-lived HTTP/SSE connections required by streaming tools ( watch, trace, monitor). STATELESS is per-request only; using it with streaming tools yields no real-time data.

Power demands responsibility : Tools like redefine (hot-reload production bytecode) and heapdump (full heap export) hand JVM life-and-death control to AI. Always set a strong password, protect the Bearer token, and restrict endpoint access in production.

viewfile whitelist : By design, viewfile only reads from arthas-output and ~/logs/. Extending requires the env var ARTHAS_MCP_VIEWFILE_ALLOWED_DIRS — not a bug, a safeguard against AI scanning sensitive configs.

Experimental status : The module is officially marked experimental; feedback welcomed. Great for daily troubleshooting, onboarding, building internal AI ops assistants. Do not let AI conclusions execute unattended in production without human review.

Closing thought

Arthas’s strength is its 29-tool coverage of the entire JVM troubleshooting chain. The hardness was memorizing which tool for which scenario, parameter combos, and OGNL syntax. MCP moves the decision to AI — the commands and bytecode tech stay identical. The AI’s playbook (evidence → converge → verify) encodes years of Alibaba production experience. Today my workflow: describe symptom → let AI run dashboard, thread, trace → review its analysis → I make the final call. Commands no longer need memorizing, but the responsibility for production changes remains mine — AI doesn’t carry the pager.