MCP server
Introduction
Section titled “Introduction”jvmguard includes an MCP server that exposes its monitoring data and diagnostic actions to MCP-compatible AI coding assistants, such as Claude Code, Codex, Antigravity, OpenCode, and Cursor. The assistant connects over the Model Context Protocol and calls tools that list the monitored fleet, read telemetries and transaction data, and trigger diagnostic captures.
The MCP server is served at the /mcp path on the same port as the web server and uses the same
protocol, either HTTP or HTTPS. It uses the streamable HTTP transport.
Enabling the MCP server
Section titled “Enabling the MCP server”The MCP server is controlled by the mcpEnabled property in config/application.yaml and is
enabled in the default configuration. You can set it to false to disable the endpoint. For the full list of
server properties, see the server configuration.
Authentication
Section titled “Authentication”Access to the MCP server is protected with a bearer token. The token is an API key that you generate
in the jvmguard UI, the same key that the REST export API uses. The assistant sends
it in the HTTP Authorization header:
Authorization: Bearer <API_KEY>You create an API key on the “External access” page, reached from “Account settings” in the user drop-down at the top of the jvmguard UI. You will only see the generated key once. If you save it, the new key becomes active and any previous key becomes invalid.
The access level of the user that owns the key governs what the assistant can do. Reading data is available to any user with an API key. The diagnostic tools that act on a VM, such as heap dumps and recordings, require profiler access.
The key is sent as a bearer token, so it is only encrypted in transit when you use HTTPS. Use HTTPS for any assistant that connects over a network.
Beyond access levels, what an assistant may do can be further restricted in two places. Server-wide settings are located the Network tab in the general settings: an MCP read-only mode and an IP allowlist. Per-VM-group toggles and limits for individual captures and mutating actions are available in the recording settings under Agent guardrails, so a “profiler” can manage them for their own groups. When a guardrail violation blocks a call, the assistant receives a message explaining the reason so it can adjust accordingly.
Connecting an assistant
Section titled “Connecting an assistant”The “External access” page in the jvmguard UI has an integration helper. When you select an assistant, it shows the command or configuration snippet, with your key filled in while the key is visible.
For a manual setup, register a remote MCP server with streamable HTTP transport, the endpoint URL, and the authorization header. For example, with the Claude Code command line and a web server port of 8020:
claude mcp add --transport http jvmguard http://localhost:8020/mcp\ --header "Authorization: Bearer <API_KEY>"For assistants that read a configuration file, use the endpoint URL and an Authorization header
with the same bearer token.
The assistant discovers the available tools when it connects. It can list the monitored groups and VMs, read telemetries and transaction data such as call trees, hot spots, and overdue transactions, inspect MBeans and log files, and read the trigger inbox.
It can also capture diagnostics on a VM, such as heap dumps, thread dumps, and JFR or JProfiler recordings. Beyond reading MBeans it can also set a writable MBean attribute and invoke an MBean operation.
In addition, it can read a VM group’s recording configuration as a JSON string and write it back after editing. The read result includes a generated schema that explains the fields, enums and polymorphic types, along with a fully worked example configuration. These mutating tools require profiler access and the capture tools additionally save their result in the list of snapshot files.
Analyzing captured artifacts
Section titled “Analyzing captured artifacts”The assistant can download a captured artifact and pass it to another tool for analysis. Binary artifact, such as a memory snapshots, JProfiler snapshots, or a JFR recordings, are returned as a download link that the assistant fetches to a local file.
Once the file is local, the assistant analyzes it with a tool that understands the format. A JProfiler CPU snapshot can be opened through the JProfiler MCP server, which lets the assistant inspect its call tree, hot spots, heap and probes. A JFR recording can be read with JProfiler or the JFR tools in the JDK.