Skip to content

Add MCP server monitoring metrics to the metrics reference lists #8508

Closed
Closed
Add MCP server monitoring metrics to the metrics reference lists#8508
Assignees
ramkumar-k-9286
Labels
Developer reviewed

Description

@IssacAX123
IssacAX123
opened on Aug 20, 2026

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.

Activity

  1. ramkumar-k-9286
    added a commit that references this issue on Aug 28, 2026

    8508-RK-Add MCP server monitoring metrics

    e9b9ff1
  2. ramkumar-k-9286
    self-assigned this
    on Aug 28, 2026

  3. ramkumar-k-9286 commented on Aug 28, 2026

    @ramkumar-k-9286
    ramkumar-k-9286
    on Aug 28, 2026
    Contributor

    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.

  4. IssacAX123 commented on Aug 28, 2026

    @IssacAX123
    IssacAX123
    on Aug 28, 2026
    MemberAuthor

    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

  5. IssacAX123 commented on Aug 28, 2026

    @IssacAX123
    IssacAX123
    on Aug 28, 2026
    MemberAuthor

    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

  6. Azquelt commented on Aug 28, 2026

    @Azquelt
    Azquelt
    on Aug 28, 2026
    Member

    Hang on, that's not right.

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

  7. Azquelt commented on Aug 28, 2026

    @Azquelt
    Azquelt
    on Aug 28, 2026
    Member

    @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.

  8. Azquelt commented on Aug 28, 2026

    @Azquelt
    Azquelt
    on Aug 28, 2026
    Member

    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=*:

  9. IssacAX123 commented on Aug 28, 2026

    @IssacAX123
    IssacAX123
    on Aug 28, 2026
    MemberAuthor

    @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>"

  10. ramkumar-k-9286
    added a commit that references this issue on Aug 28, 2026

    8508-RK-Add MCP server monitoring metrics-2

    572145b

  11. Azquelt commented on Aug 28, 2026

    @Azquelt
    Azquelt
    on Aug 28, 2026
    Member

    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.

  12. ramkumar-k-9286
    added a commit that references this issue on Aug 28, 2026

    8508-RK-Add MCP server monitoring metrics-3

    bb8211b

  13. ramkumar-k-9286 commented on Aug 28, 2026

    @ramkumar-k-9286
    ramkumar-k-9286
    on Aug 28, 2026
    Contributor

    Hi @Azquelt @IssacAX123

    Comments have been incorporated 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.

  14. IssacAX123
    added
    Developer reviewed
    on Sep 2, 2026

  15. ramkumar-k-9286 commented on Sep 11, 2026

    @ramkumar-k-9286
    ramkumar-k-9286
    on Sep 11, 2026
    Contributor

    Published [26.0.0.9 release].

  16. ramkumar-k-9286
    closed this as completedon Sep 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

Developer reviewed

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions