Liberty’s FileService MBean provided by the restConnector-2.0 feature now includes an extra blocklist attribute. This attribute is configured by the <blockDir> config element in the server.xml file. The default value of this attribute is ${server.output.dir}/resources/security. This behavior change resolves the security vulnerability CVE-2025-14915, by restricting default FileTransfer access to ${server.output.dir}/resources/security.

If FileTransfer access to ${server.output.dir}/resources/security is required, the original behavior can be restored by setting an empty blocklist.

For more information, see the documentation.

To enable signature algorithm selection from the header, set the signatureAlgorithm attribute to FROM_HEADER and optionally configure the allowedSignatureAlgorithms attribute to specify which algorithms are permitted.

If allowedSignatureAlgorithms is not configured, the default list contains all Open Liberty-supported signature algorithms: RS256, RS384, RS512, HS256, HS384, HS512, ES256, ES384, and ES512.

When using FROM_HEADER with asymmetric algorithms and a trust store setup, the public keys must be prefixed with their corresponding algorithm (e.g., RS256_keyalias) for automatic selection. During validation, the server searches the trust store for an alias that begins with the algorithm specified in the JWT’s header. If no algorithm-prefixed alias is found, the client falls back to using the alias specified by the trustedAlias attribute (for jwtConsumer) or trustAliasName attribute (for openidConnectClient, oidcLogin and mpJwt), if configured.

See the following server.xml file configurations for examples on how to apply these settings to the supported elements:

Server configurations:

Documentation:

Java 26 is a recent Java release that introduces new features and enhancements over earlier versions that can be useful to review. This release is not a long-term support (LTS) release.

There are 10 new features (JEPs) in Java 26. Five are test features and five are fully delivered.

Test Features:

Delivered Features:

A new change JEP 500 ("Prepare to Make Final Mean Final") in Java 26 starts enforcing true immutability of final fields by restricting their mutation when using deep reflection. In Java 26, such mutations still work but trigger runtime warnings by default, preparing developers for stricter enforcement. Future releases would likely throw exceptions instead, making the final truly nonmutable.

Developers can opt in early to this stricter behavior by using a JVM flag (for example, --illegal-final-field-mutation=deny) to detect issues sooner. This change improves program correctness, security, and JVM optimizations.

Take advantage of these changes now to gain more time to evaluate how your applications and microservices behave on Java 26.

Get started today by downloading the latest release of IBM Semeru Runtime 26 or Temurin 26, then download and install the Open Liberty 26.0.0.4. Update your Liberty server’s server.env file with JAVA_HOME set to your Java 26 installation directory and start testing.

For more information on Java 26, see the Java 26 release notes page and API Javadoc page.

Before the introduction of the new identity store specification, Jakarta Security natively supported only two types of identity stores: database and LDAP, both of which are used for credential validation. While effective for production environments, these options were considered heavyweight for testing, debugging, and demonstration scenarios.

Developers can also implement custom identity stores, but doing so requires bespoke code to collect, validate, and manage credential information. This effort can divert attention from core application development. A built-in, in-memory identity store reduces this burden for non-production use cases such as testing, debugging, and demonstrations.

It is now possible for multiple authentication mechanisms to logically act as a single HTTP Authentication Mechanism (HAM), providing a more flexible, dynamic, and configurable approach to the authentication workflow.

Access to the HttpAuthenticationMechanism is now abstracted by an internal implementation of the new Jakarta HttpAuthenticationMechanismHandler interface. This implementation prioritizes custom‑defined HAMs first and then falls back to the built‑in (annotation‑defined) HAMs, in the following order: OpenID, custom form, form, and basic authentication mechanisms.

Developers are free to provide their own implementation of the HttpAuthenticationMechanismHandler, allowing them to define a custom prioritization strategy for selecting HAMs. They must supply such an implementation if any built‑in HAMs are defined with the optional qualifiers attribute set.

The SecurityContext interface implementation is updated to include a new method, getAllDeclaredCallerRoles(), which returns a list of the declared application roles for an authenticated caller. If the caller is not authenticated or has no declared roles, the method returns an empty list.

Enable Jakarta Security 4.0 features within the server.xml file by adding the appSecurity-6.0 feature as shown in the following example:

Further information can be found in the Jakarta Security Specification 4.0:

For more information about the securityUtility command, see the WAS Liberty base topic.

Tools can now be registered dynamically through an API. This capability allows the set of available tools on the server to be adjusted based on configuration or environment.

Tools can be registered by injecting ToolManager and calling its methods to add, remove, and list the available tools on the server. The full Javadoc for ToolManager can be found within the Liberty beta in dev/api/ibm/javadoc/io.openliberty.mcp_1.0-javadoc.zip.

Tools can be registered when the application starts through the CDI Startup event. See the following example where the Startup event is used to register a weather forecast tool only if a WeatherClient bean is available.

Tool registration starts with newTool(), then the information about the tool is added, including its title, description, and arguments. The handler supplies the code to run when the tool is called. It has one parameter, which is a ToolArguments object, which provides access to the arguments and other information about the tool call request. The handler must always create and return a ToolResponse.

The mcpServer-1.0 feature now accepts version 2025-11-25 of the Model Context Protocol (MCP), although it does not support any new features introduced in this version of the protocol.

Supporting MCP 2025-11-25 introduces two notable behavior changes:

The result of a tools/list call is now paginated with a page size of 20. This means that if there are more than 20 tools deployed on the server, clients make several small calls to retrieve the list of tools, rather than one large call.

Customers who wish to place Jandex indexes at industry standard locations in their web modules.

This update applies to the scanning of classes within applications. Class scanning (which includes annotation scanning) is a general purpose function that is used by many features.

To gather information about application classes, including annotation data, the classes must be scanned. This scanning process is expensive because the entire application must be read and processed.

To improve performance, class scanning can be performed during application packaging, with the scan results stored in an index within the application. Jandex provides this capability.

Jandex scan results are typically written to META-INF/jandex.idx.

For JAR files, this path is relative to the root of the JAR. For WAR files, however, the META-INF/jandex.idx path can have two interpretations: it can be relative to the root of the WAR file, or relative to the WEB-INF/classes directory.

Before this update, Liberty used the location relative to the root of the WAR file. However, industry-standard practices place the location relative to the WEB-INF/classes directory. This update enables Liberty to also use the WEB-INF/classes location.

Support for reading Jandex indexes under WEB-INF/classes is enabled by a new property on the application and applicationManager elements:

Example: applicationManager

Example: application

When the new property is placed on an application manager element, it applies to all web modules of all applications. When the new property is placed on an application element, the property applies to only that application. If the property is set on both the application manager element and an application element, the value on the application element overrides the value on the application manager element for that application.

Jandex index support requires explicit enablement. See the useJandex property  on applicationManager and on application elements. The new useJandexUnderClasses property is meaningful only if the useJandex property is true.

For compatibility with earlier versions, reads of Jandex from the new location require explicit enablement. See the new useJandexUnderClasses property, as documented previously. Explicit enablement is required to prevent applications from accidentally reading an out of date Jandex index from the new location. An out of date Jandex index might cause application errors that are hard to detect.

The name of the new property, useJandexUnderClasses, is subject to revision.

To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. To enable the MCP server feature, follow the instructions from MCP standalone blog. The beta works with Java SE 25, Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package using:

You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs:

Or for Gradle:

Or if you’re using container images:

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools to enable effective development, testing, debugging and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.

Previously, the UserRegistry API supported only basic user lookups such as searching by userSecurityName or by using wildcard pattern matching. However, it did not allow applications to retrieve specific user attributes or search for users based on attribute values. These capabilities were available in traditional WebSphere through the VMM API. The introduction of these two new APIs now enables applications to search for users and retrieve attributes from LDAP and custom user registries.

With this enhancement, you can now retrieve specific attributes for a user by using the getAttributesForUser() method. This method supports retrieval of individual attributes such as email or phoneNumber, or "*" to retrieve all available attributes for a user.

You can also search for users based on attribute values by using the getUsersByAttribute() method, enabling applications to locate users by matching specific attribute criteria. These methods are supported for LDAP user registries. Custom user registry implementations can also implement and support these methods.

New API methods added to UserRegistry.java:

To learn more about the user registry, see the following resources:

With this update, Open Liberty supports Jandex index formats 11, 12, and 13. Jandex versions 3.1.0 through the current latest version, 3.5.3, generate indexes that use these formats.

Previously, Open Liberty supported Jandex index format versions only up to and including version 10. This index format limitation meant that applications packaged with Jandex indexes could not use index formats beyond version 10 while retaining the expected performance improvements. To preserve these performance benefits, build tooling had to continue using a Jandex version prior to 3.1.0, or explicitly configure Jandex index generation to produce indexes that use index format up to and including version 10.

The added support for Jandex index formats has several benefits:

When using Jandex indexes, ensure that the index files are kept up to date with the application classes. If a Jandex index is not synchronized with the application classes, it can contain incorrect annotation data, which can cause the application to function incorrectly. Out‑of‑date Jandex indexes cannot be reliably detected.

Open Liberty does not read index formats higher than index format 13. If a new version of Jandex adds a higher index format version, Open Liberty requires an update before it can read Jandex indexes that use the higher index format version.

The Open Liberty feature mpGraphQL, which is obtained from an external source, is limited to reading Jandex index formats no higher than index format 10. If the feature mpGraphQL is used, Jandex indexes should be generated by using index format 10. This limitation applies to all current versions of mpGraphQL, including the current highest version, mpGraphQL-2.0.

Previously, when Jandex usage was enabled and an application included Jandex indexes that used formats 11 through 13, Open Liberty displayed an error message and ignored those indexes. In such cases, annotation scanning was performed by using Liberty’s internal annotation scanning mechanism.

With the addition of support for Jandex index formats 11 through 13, Open Liberty now uses indexes that are generated in these formats. These indexes must be kept up to date with the application classes. Ensure that the Jandex indexes packaged with your application accurately reflect the current application classes.

No configuration changes are required in the server.xml file to enable support for the new Jandex index formats. Open Liberty automatically detects the Jandex index format and selects the appropriate index reader for that format. It reads indexes that use formats 11, 12, and 13, and continues to support indexes that use format up to version 10.

By default, Jandex usage is disabled. To enable Jandex, set the useJandex property to true in either an application element or the applicationManager element.

If you are generating Jandex indexes as part of your build process, you can now use the latest Jandex Maven plugin or Gradle plugin versions:

Maven Example:

Gradle Example:

Open Liberty automatically detects and recognizes the generated META-INF/jandex.idx file for any supported index format version.

For more information, see the Jandex Documentation

Consider a tool that does a search over some datastore:

In this scenario, the SearchResult object encapsulates a list of individual results. Each entry contains a summary, associated metadata, and a relevance score that indicates its relationship to the query.

By default, the SearchResult object that is returned is encoded as JSON by using JSON-B and placed into a TextContent. However, to return each search result summary as an individual TextContent and map the relevance score to a priority annotation, a ToolResponseEncoder is to be used.

Create a CDI bean that implements the ToolResponseEncoder interface and implement:

This encoder is used for any tools in the application that return a SearchResult

The following bugs have been fixed:

To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. To enable the MCP server feature, follow the instructions from MCP standalone blog. The beta works with Java SE 25, Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package using:

You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs:

Or for Gradle:

Or if you’re using container images:

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools to enable effective development, testing, debugging and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.

Apply the java plugin and define the desired Java version in your build.gradle file:

The Liberty build plugins now support the standard Java Toolchain mechanism. Previously, Liberty plugins were restricted to using the same Java version that was running Maven or Gradle. This prevented developers from using more recent JDK versions for their build process if their applications required a specific older JDK version.

With Java Toolchains, you can now run your build tool on a modern JDK (for example, Java 25). At the same time, Liberty servers and all server operations can execute using a different, configured JDK (for example, Java 8).

The Liberty Maven Plugin now integrates seamlessly with the maven-toolchain-plugin as of version 3.12.0. To use this feature, define your available JDKs in your ~/.m2/toolchains.xml file and then configure <jdkToolchain> tag in <configuration>. The plugin automatically detects and uses the toolchain specified in your project’s pom.xml file.

For detailed configuration steps and parameters, see the Liberty Maven Plugin Toolchain documentation.

The plugin acknowledges the JDK vendor and version constraints that are defined in your Maven profiles, helping to ensure that your server environment remains consistent across different developer machines and CI/CD pipelines.

The Liberty Gradle plugin now recognizes the native java { toolchain { …​ } } configuration block as of version 3.10.0. This configuration provides a unified way to manage Java versions across multi-project builds, where different services might have different runtime requirements.

For detailed configuration steps and parameters, see the Liberty Gradle Plugin Toolchain documentation.

When a toolchain is configured in your build.gradle, the Liberty plugin uses that specific Java runtime for all server-related tasks (for example, libertyDev and libertyStart).

To start using Java Toolchains, update your build tools to the latest versions of the Liberty Maven or Gradle plugins.

For Maven:

For Gradle:

To use the mcpServer-1.0 feature, Java 17 or later must be installed on the system.

The following new annotations allow you to restrict tool usage through authorization policies:

These security annotations are declared on two levels:

For complete reference documentation, see the Jakarta Security Annotations specification.

The mcpServer-1.0 feature does not currently implement all of the authorization-server-metadata-discovery requirements specified in the MCP specification. However, you can use any of Liberty’s authentication and authorization mechanisms to authenticate users and assign roles. The mcpServer-1.0 feature can then ensure that users can access only the tools that are permitted for their assigned roles.

The MCP specification reserves the _meta property or parameter so clients and servers can attach additional metadata to their interactions. Key name format: valid _meta key names have two segments:

The whole _meta key is seen as "example.com/myKey"

To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. To enable the MCP server feature, follow the instructions from MCP standalone blog. The beta works with Java SE 25, Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package using:

You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs:

Or for Gradle:

Or if you’re using container images:

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools to enable effective development, testing, debugging and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.

Consider the following example of a log event: TEST0111I: Hello World!.

When throttleType is set to messageID, throttling is exclusively applied based on the number of occurrences of the messageID. In this example, TEST0111I is used for throttling.

When throttleType is set to message, throttling is applied to the entire message. Any variation in the message content is tracked separately. In this example, TEST0111I: Hello World! is used for throttling.

Consider the following example of a log event: TEST0111I: Hello World!.

When throttleType is set to messageID, throttling is exclusively applied based on the number of occurrences of the messageID. In this example, TEST0111I is used for throttling.

When throttleType is set to message, throttling is applied to the entire message. Any variation in the message content is tracked separately. In this example, TEST0111I: Hello World! is used for throttling.

To use the mcpServer-1.0 feature, Java 17 must be installed on the system.

The MCP server JAR is located in a new directory, /dev/ibm/api, replacing the location used in the initial beta. For complete instructions on building an MCP server in Liberty, see the set up guide.

MCP tools can now run asynchronously by returning a CompletionStage. If a tool needs to wait for something, such as for data to be returned from a remote system, running asynchronously allows it to wait without occupying a thread.

The tool method can return a CompletionStage quickly, but the response is not returned to the client until the CompletionStage completes and provides the response data.

The following example illustrates how this approach would look for a tool that calls an asynchronous Jakarta REST client:

Parts of the Model Context Protocol require the server to store client information and reuse it for subsequent requests from the same client. This stateful behavior creates challenges when clustering MCP servers. When requests from the same client are handled by different servers, the stored information must be shared across all servers.

One way to address this problem is through session affinity. The ingress or load balancer in front of the MCP servers helps ensure that all requests from a single session are served by the same server. However, this approach requires special support for how MCP identifies sessions, and such support for MCP session affinity is not widely available yet.

This beta introduces another option, called stateless mode. This option disables MCP features that require state to be stored, allowing MCP servers to be clustered easily without any special logic for session affinity.

Currently, enabling stateless mode disables the client’s ability to cancel tool calls. As we add new features, we document which features are disabled or have limitations in stateless mode.

To enable stateless mode in your application, you need to add the following configuration in your server.xml file:

One of the main differences in stateless mode is that the server does not assign a session ID to clients. As a result, subsequent client requests do not include the Mcp-Session-Id header.

The MCP specification supports returning structured content from tools.

MCP protocol requires tools to declare schemas for their inputs and outputs. These schemas help clients to understand what to send and what to expect in return. Open Liberty generates these schemas automatically by inspecting your Java types - although you can customize them by using the @Schema annotation. The simplest use of @Schema is to add descriptions to your types. These descriptions help clients understand the purpose of each type or field.

If the default schemas do not meet your needs, you can provide a complete schema override. You might need to do an override if you use JSON-B annotations to customize the serialization of the object causing the generated schema to no longer match. A schema override is performed by providing a value to the @Schema annotation.

You usually also need to provide an output schema for a tool method that returns a ToolResponse. In this case, Open Liberty does not know what type your tool is going to return, so it cannot generate a detailed schema for it.

Use @Schema(description = "…​") when you want to add helpful context for clients, and @Schema(value = "{…​}") when you have more complex types and the auto-generated schema does not reflect your actual JSON output.

As specified in the MCP specification, MCP annotations can be added to Content objects returned from tool methods. These annotations are not Java annotations; instead, they are additional fields that provide hints to clients about how to use and display the content.

The annotation includes the following fields:

The following example shows how annotation fields can be added to tools.

Result:

To try out these features, update your build tools to pull the Open Liberty All Beta Features package instead of the main release. To enable the MCP server feature, follow the instructions from MCP standalone blog. The beta works with Java SE 25, Java SE 21, Java SE 17, Java SE 11, and Java SE 8.

If you’re using Maven, you can install the All Beta Features package using:

You must also add dependencies to your pom.xml file for the beta version of the APIs that are associated with the beta features that you want to try. For example, the following block adds dependencies for two example beta APIs:

Or for Gradle:

Or if you’re using container images:

Or take a look at our Downloads page.

If you’re using IntelliJ IDEA, Visual Studio Code or Eclipse IDE, you can also take advantage of our open source Liberty developer tools to enable effective development, testing, debugging and application management all from within your IDE.

For more information on using a beta release, refer to the Installing Open Liberty beta releases documentation.