Java Diag is an open-source MCP server for read-only Java production diagnostics. The probe (java-diag-probe) runs on the app host; an optional gateway (java-diag-gateway) provides registry and routing. Open-source package/repo remains java-diag.

Standalone probe or gateway cluster?

One host: run the probe only and point the agent at http://host:8765/mcp. Many hosts: start the gateway on 8787, register probes, and point the agent only at the gateway /mcp.

Download the GitHub Release package, set tokens, run the start scripts, then configure MCP in your agent. Requires JDK 17+.

Java Diag

Java production diagnostics MCP for AI agents

Read-only diagnostics on the app host via probe; optional gateway for cluster routing. Works with any MCP-compatible AI agent. MIT licensed — download a Release and go.

Java Diag is an open-source MCP server for read-only Java production diagnostics (probe + optional gateway). Open-source package/repo remains java-diag.

Download Release GitHub Docs

Why it exists

When production Java stalls, stop SSHing in to run jcmd by hand. Give your agent read-only access to thread dumps, GC, and allow-listed logs in one conversation.

How it works

Diagnostics run on the probe host. The gateway only handles registry discovery and MCP proxying — it does not run jcmd or read app logs itself.

java-diag-probe

On the app host: process discovery, allow-listed logs, jcmd, and related local tools.

java-diag-gateway

Optional cluster entry: heartbeat registry and tool routing by target.

Standalone

Agent → http://host:8765/mcp → Probe

Cluster

Agent → Gateway :8787/mcp → selected Probe

Java Diag Gateway Admin showing MCP config copy actions — Gateway Admin: list probes and copy MCP config

Capabilities

Exposed as MCP tools (full list in the repository README).

Logs

diag.log_paths — allow-list
diag.tail_log — tail
diag.grep_log — search
diag.cluster_errors — error rollup

JVM

diag.thread_dump — threads
diag.jstat / diag.gc_histo — GC
diag.heap_dump — heap
diag.cpu_sample — CPU sample

Quick Start (standalone)

Start with the probe only. Requires JDK 17+. Cluster mode and full detail live in the GitHub README.

Download the latest Release and extract (same layout as deploy/).
Edit java-diag-probe.properties and set auth.token (required).
Start: cd java-diag-probe && ./start.sh start
Configure MCP in your agent: URL http://127.0.0.1:8765/mcp, Bearer = that token; verify with diag.ping.

{
  "mcpServers": {
    "java-diag": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": { "Authorization": "Bearer YOUR_AUTH_TOKEN" }
    }
  }
}

Multi-host: start Gateway (8787) then probes; agents talk only to Gateway /mcp. See README section B.

Security & open source

MIT — probe and gateway are open source
Read-only posture — diagnostics-first, auditable
Tokens required — empty auth.token fails startup; probe register.token required only when register.url is set
No public exposure — keep /mcp, /sse, and /registry/* off the open internet

SECURITY.md

FAQ

What is Java Diag?

An open-source MCP server for read-only Java production diagnostics: java-diag-probe on the host, optional java-diag-gateway for clusters. Open-source package/repo remains java-diag.

How is it different from running jcmd yourself?

Same local tools underneath; MCP lets any compatible AI agent invoke them without repeated SSH.

Standalone or cluster?

Standalone: probe :8765/mcp. Cluster: gateway :8787/mcp with registered probes.

How do I install it?

Download the Release zip → set tokens → start scripts → configure MCP. JDK 17+.

Is it read-only and safe?

Designed for read-only, auditable use with required tokens. Do not expose ports publicly.