Add MCP server monitoring metrics to the metrics reference lists

[IssacAX123]

Add MCP server monitoring metrics to the metrics reference lists

Problem description

The mcpServer-1.0 feature ships monitoring support via three auto-features that activate automatically when paired with existing monitoring features:

• io.openliberty.mcpServer-1.0-monitor-1.0.feature JMX/MXBean support (via monitor-1.0)
• io.openliberty.mcpServer-1.0-mpTelemetry-2.0.feature OpenTelemetry histograms (via mpTelemetry-2.0)

None of these metrics are documented in either:

• mptelemetry-metrics-list.adoc
• jmx-metrics-list.adoc

---

Changes needed mptelemetry-metrics-list.adoc

Add two rows to the MicroProfile Telemetry 2.0 and later metrics reference table:

mcp.server.operation.duration

• Type: DoubleHistogram / seconds
• Description: Duration of every MCP operation one data point per tools/call, tools/list, initialize, notifications/initialized, ping, and notifications/cancelled request.
• Monitoring component: MCP
• Features required: feature:mcpServer-1.0 and feature:mpTelemetry-2.0
• Bucket boundaries: [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0]
• Attributes:

Attribute	Present	Description
mcp.method.name	Always	Which MCP method was called, e.g. tools/call, initialize, tools/list, ping
rpc.response.status_code	Always	ok on success, error on failure
jsonrpc.protocol.version	Always	The JSON-RPC version used by the request, e.g. 2.0
network.protocol.name	Always	The HTTP protocol name, e.g. HTTP
network.protocol.version	Always	The HTTP protocol version, e.g. 1.1
network.transport	Always	The transport layer. Always tcp
mcp.protocol.version	After initialize	The MCP protocol version negotiated with the client, e.g. 2025-11-25
gen_ai.tool.name	tools/call only	The name of the tool that was called
error.type	On failure only	Why the operation failed: tool_error, internal_error, http_error, or a JSON-RPC error code such as INVALID_PARAMS

mcp.server.session.duration

• Type: DoubleHistogram / seconds
• Description: Duration of each MCP session from initialize to session end. Only emitted in stateful mode.
• Monitoring component: MCP
• Features required: feature:mcpServer-1.0 and feature:mpTelemetry-2.0
• Bucket boundaries: [0.01, 0.02, 0.05, 0.1, 0.2, 0.5, 1.0, 2.0, 5.0, 10.0, 30.0, 60.0, 120.0, 300.0]
• Attributes:

Attribute	Present	Description
jsonrpc.protocol.version	Always	The JSON-RPC version used when the session was created, e.g. 2.0
mcp.protocol.version	Always	The MCP protocol version negotiated during initialize, e.g. 2025-11-25
network.protocol.name	Always	The HTTP protocol name from when the session was created, e.g. HTTP
network.protocol.version	Always	The HTTP protocol version from when the session was created, e.g. 1.1
network.transport	Always	The transport layer. Always tcp
error.type	On abnormal end only	Why the session ended abnormally, e.g. timeout. Only present when the session did not close cleanly

Filter attribute update

Also update the filter attribute example to include MCP as a valid monitoring component value:

<monitor filter="ConnectionPool,ThreadPool,RequestTiming,Session,HTTP,MCP"/>

Both metrics are also emitted via mpMetrics-5.0 with the same metric names.

---

Changes needed jmx-metrics-list.adoc

Add a new MCP monitoring section. Both MXBeans activate automatically when mcpServer-1.0 and monitor-1.0 are both enabled. The monitoring component filter value is MCP. MXBean instances are created dynamically as operations and sessions are observed, and are removed when the associated application is unloaded.

McpOperationStatistics MXBean

Object name: WebSphere:type=McpOperationStatistics,name=*

MXBean attribute	Units	Description
McpMethodName	Not applicable	The MCP JSON-RPC method name e.g. tools/call, initialize, tools/list, ping. Always present.
GenAiToolName	Not applicable	The name of the tool that was called. Only present on tools/call data points.
GenAiPromptName	Not applicable	The prompt name for prompt operations. Null if not applicable.
GenAiOperationName	Not applicable	The GenAI operation name. Null if not applicable.
ErrorType	Not applicable	Why the operation failed. Null for successful operations. Values include tool_error, internal_error, http_error, or a JSON-RPC error code such as INVALID_PARAMS.
RpcResponseStatusCode	Not applicable	ok on success, error on failure.
JsonrpcProtocolVersion	Not applicable	The JSON-RPC protocol version e.g. 2.0.
McpProtocolVersion	Not applicable	The MCP protocol version negotiated with the client e.g. 2025-11-25.
NetworkProtocolName	Not applicable	The network protocol name e.g. HTTP.
NetworkProtocolVersion	Not applicable	The network protocol version e.g. 1.1.
NetworkTransport	Not applicable	The network transport. Always tcp.
McpResourceUri	Not applicable	The MCP resource URI for resource operations. Null if not applicable.
Count	Not applicable	The total number of times this operation has been recorded.
CountDetails	Not applicable	Detailed counter information including the last update timestamp.
Duration	Nanoseconds	The total cumulative duration of all recorded executions of this operation.
DurationDetails	Nanoseconds	Statistical details about operation duration including minimum, maximum, and total values.

McpSessionStatistics MXBean

Object name: WebSphere:type=McpSessionStatistics,name=*

MXBean attribute	Units	Description
ErrorType	Not applicable	Why the session ended abnormally. Null for sessions that closed cleanly.
JsonrpcProtocolVersion	Not applicable	The JSON-RPC protocol version used when the session was created e.g. 2.0.
McpProtocolVersion	Not applicable	The MCP protocol version negotiated during initialize e.g. 2025-11-25.
NetworkProtocolName	Not applicable	The network protocol name e.g. HTTP.
NetworkProtocolVersion	Not applicable	The network protocol version e.g. 1.1.
NetworkTransport	Not applicable	The network transport. Always tcp.
Count	Not applicable	The total number of sessions recorded for this set of attributes.
CountDetails	Not applicable	Detailed counter information including the last update timestamp.
Duration	Nanoseconds	The total cumulative duration of all recorded sessions.
DurationDetails	Nanoseconds	Statistical details about session duration including minimum, maximum, and total values.

[ramkumar-k-9286]

Hi Issac @IssacAX123

Suggested changes have been made to the MicroProfile Telemetry metrics reference list and JMX metrics reference list pages.

Draft Links:

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/mptelemetry-metrics-list.html

https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/jmx-metrics-list.html#mcp-stats

Please review the changes and add the Developer Reviewed label, if you are satisfied with the changes.

Regards,
Ramkumar.

[IssacAX123]

Hi Ramkumar @ramkumar-k-9286

For https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/mptelemetry-metrics-list.html
can you remove the line This metric is also emitted when [MicroProfile Metrics 5.0](https://docs-draft-openlibertyio.mqj6zf7jocq.us-south.codeengine.appdomain.cloud/docs/latest/reference/feature/mpMetrics-5.0.html) is enabled. in both rows for operation and session

[IssacAX123]

Hi Ramkumar @ramkumar-k-9286

Apologies, the names are wrong for the mbeans here is the updates
# MCP MXBean Attribute Name Corrections
see last comment below

[Azquelt]

Hang on, that's not right.

I think the existing attribute names are right, but the name of the MBean itself is wrong.

[Azquelt]

@IssacAX123 the attribute names come from the MXBean interfaces. Each getFoo method defines an attribute named Foo.

The MBean name on the other hand is created from getAttributeMap() on the statistics object.

[Azquelt]

So I think the list of attributes was correct, the part that needs to be changed is this bit:

The object name of the MXBean for these attributes is WebSphere:type=McpSessionStatistics,name=*:

[IssacAX123]

@ramkumar-k-9286

Replace WebSphere:type=McpOperationStatistics,name=* with WebSphere:type=McpOperationStatistics,name="mcpMethod:<mcpMethod>;genAiTool:<genAiTool>;errorType:<errorType>;genAiPrompt:<genAiPrompt>;rpcStatus:<rpcStatus>;genAiOp:<genAiOp>;jsonrpcVer:<jsonrpcVer>;mcpVer:<mcpVer>;netProto:<netProto>;netProtoVer:<netProtoVer>;netTransport:<netTransport>;resourceUri:<resourceUri>"

Replace WebSphere:type=McpSessionStatistics,name=* with WebSphere:type=McpSessionStatistics,name="session;errorType:<errorType>;jsonrpcVer:<jsonrpcVer>;mcpVer:<mcpVer>;netProto:<netProto>;netProtoVer:<netProtoVer>;netTransport:<netTransport>"

[Azquelt]

That's still not quite right, it should be:

WebSphere:type=McpOperationStatistics,mcpMethod=<mcpMethod>,genAiTool=<genAiTool>,errorType=<errorType>,genAiPrompt=<genAiPrompt>,rpcStatus=<rpcStatus>,genAiOp=<genAiOp>,jsonrpcVer=<jsonrpcVer>,mcpVer=<mcpVer>,netProto=<netProto>,netProtoVer=<netProtoVer>,netTransport=<netTransport>,resourceUri=<resourceUri>

and

WebSphere:type=McpSessionStatistics,session=true,errorType=<errorType>,jsonrpcVer=<jsonrpcVer>,mcpVer=<mcpVer>,netProto=<netProto>,netProtoVer=<netProtoVer>,netTransport=<netTransport>

@IssacAX123:
We made a change to no longer put all the attributes within a name attribute. The attribute map is turned into the name in com.ibm.websphere.monitor.meters.MeterCollection.MXBeanHelperWithAttributes(String, Map<String, String>, int, Object)

Note:
Aside from mcpMethod and session, all the parts of the name are optional and only included if the corresponding attribute is set.

At the moment we never set getAiPrompt, genAiOp or resourceUri so they'll never actually appear in the name, but we may do in the future and the MXBean interface has corresponding methods.