Interface McpServerDiagnostics

@ThreadSafe public interface McpServerDiagnostics
An immutable point-in-time snapshot of MCP server diagnostics.

A retained snapshot never changes. Obtain a new snapshot to observe a later lifecycle state.

Lifecycle, handler-capacity, and stream values are captured together at one runtime linearization point. Protection and trace-correlation values are captured together at a separate security-control linearization point. No invariant spans those independently mutable domains.

Author:
Mark Allen

  • Method Details

    • getStatus

      @NonNull McpServerStatus getStatus()
      The lifecycle status captured by this snapshot.
      Returns:
      the server status

    • getBoundAddress

      @NonNull Optional<@NonNull InetSocketAddress> getBoundAddress()
      The effective bound address captured by this snapshot.

      The address is empty until binding succeeds and includes the operating-system-assigned port when ephemeral port 0 was configured. Once published, the effective address remains available as historical evidence in later shutdown and terminal snapshots.

      Returns:
      the effective or historically retained bound address, or empty when this server never bound

    • getRequestHandlerConcurrency

      @NonNull Integer getRequestHandlerConcurrency()
      The configured maximum number of application request handlers that may execute concurrently.

      This value is stable across the owner lifecycle.

      Returns:
      the configured request-handler concurrency

    • getRequestHandlerQueueCapacity

      @NonNull Integer getRequestHandlerQueueCapacity()
      The configured maximum number of admitted application requests that may wait for a request-handler execution slot.

      This value is stable across the owner lifecycle.

      Returns:
      the configured request-handler queue capacity

    • getActiveHandlerExecutions

      @NonNull Integer getActiveHandlerExecutions()
      The number of application request handlers occupying execution slots in this snapshot.

      The value includes residual handlers that continue running after server stop and is between zero and getRequestHandlerConcurrency().

      Returns:
      the active handler-execution count

    • getRequestHandlerQueueDepth

      @NonNull Integer getRequestHandlerQueueDepth()
      The number of admitted application requests waiting for a request-handler execution slot in this snapshot.

      The value is zero after a completed server stop transition and is between zero and getRequestHandlerQueueCapacity(). A transient residual snapshot captured while failure cleanup is draining work may remain nonzero.

      Returns:
      the queued-request count

    • getActiveRequestStreams

      @NonNull Integer getActiveRequestStreams()
      The number of active SSE streams in this snapshot.

      This count includes request-scoped streams, an MCP subscription once its acknowledgment stream has opened, and configured 2025 session GET bodies, including those awaiting physical cleanup. Opening a stream does not imply client receipt. The value is nonnegative and is zero when getStatus() is McpServerStatus.NOT_STARTED or McpServerStatus.TERMINATED. Residual cleanup can keep this count nonzero after publication of the owner's immutable shutdown result.

      Returns:
      the active request-stream count

    • getActiveSubscriptions

      @NonNull Integer getActiveSubscriptions()
      The number of active subscription streams in this snapshot.

      The count includes an MCP subscription once its acknowledgment stream has opened and configured 2025 session GET bodies, including those awaiting physical cleanup. Opening a stream does not imply client receipt. This value is nonnegative, never exceeds getActiveRequestStreams(), and is zero when getStatus() is McpServerStatus.NOT_STARTED or McpServerStatus.TERMINATED. Residual cleanup can keep this count nonzero after publication of the owner's immutable shutdown result.

      Returns:
      the active subscription count

    • getProtectionMode

      @NonNull McpProtectionMode getProtectionMode()
      The effective framework request-state protection mode in this snapshot.

      This value is fixed when the server is built and remains stable across the one-shot owner lifecycle.

      Returns:
      the effective protection mode

    • isApplicationRequestStateProtectorConfigured

      @NonNull Boolean isApplicationRequestStateProtectorConfigured()
      Whether an application-owned request-state protector is configured in this snapshot.

      This value is true exactly when getProtectionMode() is McpProtectionMode.CUSTOM_PROTECTOR. It reports provider selection without exposing the protector instance or its configuration. It does not report whether an operation declares McpRequestStateMode.APPLICATION_PROTECTED; it reports only custom- protector selection for canonical McpRequestStateMode.FRAMEWORK_PROTECTED state.

      Returns:
      whether a custom application request-state protector is configured

    • getProtectionKeyringFingerprint

      @NonNull Optional<@NonNull McpProtectionKeyringFingerprint> getProtectionKeyringFingerprint()
      The secret-free fingerprint of the complete live production protection key ring in this snapshot.

      The fingerprint is present exactly when getProtectionMode() is McpProtectionMode.PRODUCTION_KEYRING. Successful live ring mutations are reflected only in subsequently obtained snapshots. The value excludes trace-correlation configuration, request-state epochs, and cursors, and exposes neither raw keys nor per-key fingerprint tags. It is operational deployment-comparison metadata, not an authentication input.

      Returns:
      the live production keyring fingerprint, or the empty optional

    • getTraceCorrelationFingerprint

      @NonNull Optional<@NonNull McpTraceCorrelationFingerprint> getTraceCorrelationFingerprint()
      The secret-free fingerprint of the active trace-correlation configuration in this snapshot.

      The fingerprint is present exactly when trace correlation was enabled at server construction. Successful trace-key rotations are reflected only in subsequently obtained snapshots. This value is independent of the request- state protection mode, exposes no raw key material, and is operational deployment-comparison metadata rather than a token-derivation or authentication input.

      Returns:
      the active trace-correlation configuration fingerprint, or the empty optional when trace correlation is disabled