JProfiler MCP Server: Tool and Resource Reference

JProfiler is a Java profiler whose MCP (Model Context Protocol) server gives AI coding agents direct access to its profiling and analysis capabilities: recording CPU, allocation and probe data from running JVMs, analyzing heap dumps and snapshots, and drilling into the recorded data with a jq-based query interface.

This document is generated from the running server and lists all tools and resources exactly as an agent sees them after connecting. It is intended both for developers who want to understand what the integration can do and for AI agents that evaluate whether to install it.

The quickest way to connect an agent is the npm wrapper, which downloads and provisions JProfiler automatically and offers to start a free evaluation license on first use:

{
  "mcpServers": {
    "JProfiler": {
      "command": "npx",
      "args": ["-y", "@ej-technologies/jprofiler-mcp@latest"]
    }
  }
}

For other installation options, see https://www.ej-technologies.com/jprofiler/mcp.

Generated from JProfiler 16.3.

Contents

Tools: prepare_profiling, load_snapshot, attach, check_status, query, create_heap_dump, attached_action, list_jvms

Resources: jprofiler://datasets, jprofiler://config/session, jprofiler://config/probes, jprofiler://probes/custom, jprofiler://api/method-scripts, jprofiler://api/heap-scripts, jprofiler://api/controller, jprofiler://api/probe-embedded, jprofiler://api/probe-injected

Tools

prepare_profiling

Prepare a profiling session by retrieving a JVM parameter to be added to a Java process call to record performance data with stack traces for the following subsystems: cpu, jdbc, jpa, mongo_db, cassandra, http_server, http_client, ws, jndi, jms, kafka_consumer, rmi, grpc, ai, process. The result is a JSON object containing a 'jvmParameter' to be added (quoted) to the Java process at startup. Add it verbatim and do not create or modify any files; the configuration is already set up for you. If the result contains 'additionalJvmParameters' (discovery of injected custom probes), add each element as a separate VM argument as well. Keep this MCP server running and run the Java process. It waits for the server to connect before application startup. During recording, attached_action can perform live actions. The recording is saved automatically when the JVM terminates, after the optional maximum duration, or when check_status is called with 'stopRecording: true'. Then call check_status to access the data - do not load the saved snapshot file yourself. Saving disconnects from the JVM. Use attach with its PID for another recording if it is still running.

Properties of recordingConfig

Properties of recordingConfig.advanced

Properties of recordingConfig.advanced.splitMethods entries

Properties of recordingConfig.advanced.complexityMethods entries

Properties of recordingConfig.advanced.scriptProbes entries

Properties of recordingConfig.advanced.scriptProbes.methods entries

Properties of recordingConfig.triggers entries

Properties of recordingConfig.triggers.actions entries

load_snapshot

Load an existing .jps, .hprof, or .jfr file for analysis. You must call check_status to check the loading progress and - after this returns 'data_ready' - retrieve data with the query tool. To compare two performance snapshots, load both in a single call: set filePath to the run to analyze and baselineFilePath to the baseline; the differences are then reported in the hotspots and call trees of that run.

attach

Attach to a running JVM by PID or to a JVM inside a Docker container. Records performance data for the following subsystems: cpu, jdbc, jpa, mongo_db, cassandra, http_server, http_client, ws, jndi, jms, kafka_consumer, rmi, grpc, ai, process until check_status is called with 'stopRecording: true', or allocation data when "recordingConfig": {"recordAllocations": true} is passed. Pass "recordingConfig": {"recordMonitors": true} to additionally record monitor and lock events. You can use list_jvms to discover JVMs.

Properties of recordingConfig

Properties of recordingConfig.advanced

Properties of recordingConfig.advanced.splitMethods entries

Properties of recordingConfig.advanced.complexityMethods entries

Properties of recordingConfig.advanced.scriptProbes entries

Properties of recordingConfig.advanced.scriptProbes.methods entries

Properties of recordingConfig.triggers entries

Properties of recordingConfig.triggers.actions entries

check_status

Check the status of a profiling session and discover which subsystems were recorded. Can be used to stop recording. When the data is ready provides information about the recorded subsystems (e.g. cpu, jdbc, http_client).

query

Query a performance or heap dataset with a jq expression and return the result. The dataset is materialized lazily and cached per session. Each query is independent, there is no current object: builtins take explicit ids bound from earlier results, e.g. .instances[0].id as $id | {value: preview($id), keptAliveBy: pathToRoot($id).paths[0].path | map(.class)}

Properties of args

create_heap_dump

Dump the heap of a locally running JVM or of a JVM inside a Docker container and load it for analysis. If allocation data is recorded for the JVM, the heap dump includes per-object allocation data. A recording session delivers a single heap dump, for a later dump attach again. You must call check_status to check the loading progress and - after this returns 'data_ready' - retrieve data with the query tool. You can use list_jvms to discover JVMs.

attached_action

Perform a point-in-time action on the connected JVM: thread and monitor dumps, heap marking and heap dumps, MBean snapshots, and starting or stopping subsystem recording. Requires a recording session started with attach or prepare_profiling. The action names and parameters are the same as for the actions of recordingConfig.triggers.

list_jvms

List locally running JVMs or JVMs running in a Docker container with their command line and PID. Use the information to call attach or create_heap_dump.

Resources

Resources are read-only documents served by the MCP server. An agent reads them at runtime when it needs the details, for example the script API reference before writing a heap script or the probe configuration reference before tuning a recording. The full content of each resource is also published here:

• jprofiler://datasets: All datasets of the query tool and the jq builtins for the query expression, with arguments, row formats and examples. Static reference, check_status reports the session-specific catalog with availability flags. (full reference)
• jprofiler://config/session: All session settings usable as direct keys of recordingConfig.advanced of the prepare_profiling and attach tools, with types, defaults and explanations (full reference)
• jprofiler://config/probes: All probe attributes usable in recordingConfig.advanced.probeConfig of the prepare_profiling and attach tools, with types, defaults and explanations (full reference)
• jprofiler://probes/custom: Custom probes of the profiled application: what they are, embedded vs injected, when not to write one, build setup, deployment and recording as custom:<fully qualified probe class name> subsystems. Read this before recording or writing a custom probe. (full reference)
• jprofiler://api/method-scripts: Script API of recordingConfig.advanced.splitMethods and complexityMethods: the script contract, the available parameters and the ScriptContext state store. Read this before writing a split or complexity script. (full reference)
• jprofiler://api/heap-scripts: Java script API for the filterScript parameter of heap.instances and heap.sizes and the groupScript parameter of the custom_grouping inspection: script signatures, the heap object model and limitations. Read this before writing a heap script. (full reference)
• jprofiler://api/controller: API reference of com.jprofiler.api.controller.Controller: the profiled application drives profiling itself - start/stop recordings, save snapshots, heap dumps, heap marks and bookmarks from application code. Read this when the application knows better than the agent when to record. (full reference)
• jprofiler://api/probe-embedded: API reference of com.jprofiler.api.probe.embedded for embedded custom probes: the probe base classes PayloadProbe and SplitProbe, the measurement entry points Payload and Split and the telemetry annotations. Read this before writing an embedded probe. (full reference)
• jprofiler://api/probe-injected: API reference of com.jprofiler.api.probe.injected for injected custom probes: the @Probe annotation, the interception declarations, the injected parameter annotations and the telemetry annotations. Read this before writing an injected probe. (full reference)

Server instructions

When an agent connects to the MCP server, it receives the following instructions that describe the recommended workflows:

Workflow Rules for performance recording: Setup: For profiling a new Java process, call prepare_profiling to get the required JVM parameter. For attaching to a running JVM, call attach. Both create live sessions that support attached_action while recording. Finishing a recording saves a snapshot and disconnects. For another recording on the same JVM, call attach with its PID. prepare_profiling tokens are single-use startup parameters. If the user has a complex scenario, suggest they manually record a .jps file in JProfiler and use load_snapshot instead. If the application itself should drive recording (for example saving a snapshot when a rare error occurs), the Controller API for application code is documented in the jprofiler://api/controller resource. Use check_status to check for data availability.

Discovery and drill-down: Once data is available, call check_status to see the datasets list, then use query to retrieve and analyze them. Filtering, sorting, projection and aggregation belong in the jq expression, not in repeated tool calls. Keep results small by projecting fields and slicing with .[0:N], oversized results are truncated and marked as such. For back traces and call tree children, use the expand(expansionId) jq builtin inline in the expression.

Thread states: the default running view hides time spent waiting. When CPU usage is low but the app is slow, re-query with threadStatus "all" (wall clock time), or "net_io" for database and REST wait and "blocked"/"waiting" for lock and inter-thread analysis.

Threads: performance datasets merge all threads by default. When the question targets a specific thread or a thread pool, find it in the threads.list dataset (each row carries the per-state time breakdown), then pass its threadId as the thread parameter, a group name as threadGroup, or thread "virtual" for all virtual threads. To find out which threads contribute to a cpu hotspot or call tree node, pass its expansionId to the threads(expansionId) jq builtin. Combine with threadStatus to see where the selected threads spend waiting or blocked time.

Invocation counts: sampling produces no invocation counts. If the analysis needs call counts (how often a method was invoked), re-record with "recordingConfig": {"advanced": {"methodCallRecordingType": "instrumentation", "filter": "<application packages>"}}.

Exceptional invocations: when the question is why a call is occasionally slow, record with instrumentation, query performance.outliers for methods whose maxMicros deviates strongly from avgMicros, then re-record with the method copied into "recordingConfig": {"advanced": {"exceptionalMethods": [...]}} and expand the nodes marked exceptionalRun in performance.callTree to inspect single slow invocations. The outlier times are measured in the thread status reported as threadStatus in the result (all = wall clock), set "recordingConfig": {"advanced": {"exceptionalTimeType": "waiting"}} when re-recording to analyze a different thread state.

Workflow Rules for heap dump analysis: Setup: Use load_snapshot to load an existing HPROF or JPS snapshot or use create_heap_dump to dump the heap of a running JVM. Use check_status to check for data availability.

Discovery: Once data is available, call check_status to see the datasets list, then use query to retrieve and analyze the heap dump (class histogram, biggest objects, instances). Use the retained(id), incoming(id), outgoing(id), pathToRoot(id), preview(id), referrersByClass(id) and referencesByClass(id) jq builtins with object ids to follow the object graph. Heap datasets are not available for snapshot comparisons.

Heap scripts: filtering beyond the value filter and grouping by computed keys are done with Java scripts - the filterScript parameter of heap.instances and heap.sizes and the custom_grouping inspection of heap.inspectionResult. Read the jprofiler://api/heap-scripts resource for the script API before writing a heap script.

Workflow rules for probe events: Probe subsystems (jdbc, http_server, ...) record aggregated hot spots by default; individual events (single SQL statements, HTTP requests, ...) require event recording: "recordingConfig": {"advanced": {"probeConfig": {"<subsystem>": {"events": true}}}}, or a snapshot recorded with events. The probeEvents section of check_status lists the subsystems with recorded events. probe.events serves the individual events: its arguments filter and select globally over the full event set, the jq expression only sees the returned page - use matchedCount to judge selectivity and narrow with from/to, minMicros, types or text. probe.eventTimeline localizes bursts in time, probe.eventHistogram estimates the duration distribution and percentiles. Rows with an expansionId have a back trace for expand(expansionId). Probes with open/close resources (jdbc connections, files, sockets, processes) also record control objects: probe.controlObjects lists the still open objects oldest first, the leak analysis entry point - expand the openExpansionId of a leak candidate for the stack trace of the open call, the probeControlObjects section of check_status lists the subsystems with control objects, most probes have none. Beyond the fixed set of built-in probes, probes written for the profiled application are recorded as custom:<fully qualified probe class name> subsystems - read the jprofiler://probes/custom resource first. Probes declared as scripts in recordingConfig.advanced.scriptProbes need no deployment and appear as script:<name>.

Workflow rules for GC data: The gc subsystem records JFR garbage collection data. Recordings started through this server include it by default; in snapshots recorded elsewhere it depends on the source - the JProfiler UI only collects GC data while GC recording was active, JFR files carry GC events in most configurations. The snapshotInfo.gcInfo block of check_status appears when GC data exists and holds the aggregate pause and collection statistics and the collector configuration, the gc.collections dataset serves the individual collections: cause, pause times, phases, reference counts and heap/metaspace usage before and after each GC, plus the GC flags and the full configuration in the header. Find pause outliers with sort_by(-.longestPauseMicros), explain a long pause with its cause and phases, follow the leak slope in heapUsedAfterBytes. GC collections carry no back traces, correlate causes like "G1 Humongous Allocation" with the allocation datasets.

Workflow rules for lock and monitor analysis: Lock contention is invisible in CPU data, threads blocked on a lock burn no CPU. Record monitors by passing "recordingConfig": {"recordMonitors": true} on attach or prepare_profiling, or load a snapshot that contains monitor recording. Start with the monitor.stats dataset to find the monitors, threads or classes with the most lost time, use monitor.timeline to locate contention bursts in time, then drill into monitor.history for individual locking situations with stack traces and monitor.graph for lock-order inversions. When the question is whether a live JVM is deadlocked right now, call attached_action with action monitorDump in a live session; attach-mode dumps show java.util.concurrent locks only, not intrinsic (synchronized) monitors.

Workflow rules for thread dumps: A thread dump captures the state and stack trace of every thread at one point in time. In a live session, call attached_action with action threadDump (with includeVirtualThreads for the virtual thread population and its container hierarchy). For recordings from JVM start or captures at events like CPU or heap thresholds, configure threadDump actions in recordingConfig.triggers. After the recording is stopped, the threads.dumps dataset lists the captured dumps and expand(expansionId) returns the grouped thread tree of a dump, where threads with identical stack traces collapse into one group. Sort groups by count to find where a large thread population is parked, compare two dumps to find threads stuck at the same stack trace. Thread dumps carry no lock ownership data, for deadlocks and lock analysis use attached_action with action monitorDump and the monitor datasets.

Workflow rules for MBean data: In a live session, call attached_action with action mbeanSnapshot to capture the current JMX MBean attribute values into the session snapshot, for exploration usually unfiltered, labeled when taking a series. For recordings from JVM start, periodic captures or captures at events like heap thresholds, configure mbeanSnapshot actions in recordingConfig.triggers of attach or prepare_profiling instead. After the recording is stopped, the mbean.snapshots dataset serves the captured snapshots: catalog, MBean names per snapshot, attribute values per MBean. MBean values recorded continuously as custom telemetries are in the telemetry.list dataset.

Workflow rules for live actions: In a live session, the attached_action tool performs point-in-time actions on the live JVM. markHeap marks all current heap objects as old, so a heap dump taken later distinguishes objects allocated afterwards. heapDump takes a heap dump into the session snapshot without stopping the recording, use create_heap_dump instead to stop and analyze the heap immediately. startRecording and stopRecording start or stop the recording of subsystems like cpu or monitors in the running session, they do not end the session.