BETA BLOG - mcpServer-1.0 updates in 26.0.0.1-beta

[ttmunyunguma]

The information you provide here will be included in the Open Liberty beta blog post (example), which will be published on openliberty.io/blog/, and potentially elsewhere, to promote this beta feature/function of Open Liberty. For this post to be included in the beta issue please make sure that this is completed by the end of Friday following the GM (Tuesday). The beta and release blogs are created using automation and rely on you following the template's structure. DO NOT REMOVE/ALTER THE <GHA> TAGS THROUGHOUT THIS TEMPLATE.

<GHA-BLOG-SUMMARY>

The Model Context Protocol (MCP) has emerged as the standard for AI applications to access real-time information from external sources. The Liberty MCP Server feature mcpServer-1.0 allows developers to expose the business logic of their applications, allowing it to be integrated into agentic AI workflows.

This beta release of Liberty includes important updates to the mcpServer-1.0 feature, including asynchronous tool support, stateless mode support and a few bug fixes

Prerequisites

To use the mcpServer-1.0 feature, it is required to have Java 17 installed on your system.

Update on the MCP JAR location

The directory in which the MCP server jar will be located has been updated from the previous lib folder, to the new location /dev/ibm/api. You can view the set up guide for complete instructions on how to build an MCP server in Liberty.

Asynchronous Tool Execution Support

Although MCP is built around synchronous operations, we can now support asynchronous operations. With this feature, tool users can wrap their tool responses in a CompletionStage.

This enables a non-blocking execution pattern for the server to kick off long running tools, which clients can then check back later for results when the stage completes. Your MCP server stays responsive and can handle multiple requests concurrently, making better use of resources while time-consuming operations run in the background.

Here is an example how that would look like:

@Tool()
public CompletionStage<String> toolName() {
//return your Completable Future or Managed service
}

Stateless Mode

As required by the MCP Specification, we now can distinguish clearly between stateless and stateful requests to a server by enabling stateless mode.

This mode removes the need for session affinity in a clustered environment, allowing any server instance to handle any request, simplifying load balancing and horizontal scaling. This is essential for simple clustering if you are running your MCP server on multiple nodes.

To enable stateless mode in your application, you'll need to add this configuration in your server.xml file:

<mcpServer stateless="true"/>

When stateless mode is enabled, you will not be able to cancel ongoing requests, therefore any notifications to cancel a request will be ignored, and by extension, you will not be able to delete a session.

Requests made in stateless mode should NOT provide a Mcp-Session-Id header. The Liberty server will automatically pick up the stateless mode configuration at startup, and any requests made with a session Id will be rejected.

If the above configuration is not enabled, all requests are assumed to be stateful and must provide a session ID for each request

Input and Output Schema support

We added support for schemas as specified by the MCP protocol. We can now generate input and output schemas for tools.

This will allow users to annotate complex types with @Schema that should be used to interpret its JSON representation. This will ensure that the server provides tools with a predictable structure of parameters, and a definite structure the tool returns, therefore preventing ambiguity and allowing for a reliable interaction between the client and server.

You can add the annotation on the type itself, or on the parameters of a complex type

@Schema("{\"properties\": {  \"streetName\": { \"type\": \"string\" }, \"roadType\": { \"type\": \"string\" } }" )
public record Street(String streetName, String roadType) {}

public record Company(String name, Address address, 
                                @Schema(value = "{\"properties\": {\"key\":{ \"type\": \"integer\" }, \"value\":{ \"$ref\": \"#/$defs/person\" }},\"required\": [ ], \"type\": \"object\"}") Optional<Map<String, Person>> shareholderRegistry) {};

An input schema can be configured as follows, with the input parameter @Schema() Street which was defined above.

@Tool()
public boolean toolName(@ToolArg(name = "...") Street street) {
//do something with your street object
}

For an output Schema, you need to indicate that the tool returns structured content and provide a schema for the output structure. With this, a serializable response will be returned in a JSON with the structured content field

@Tool(name = "...", structuredContent = true)
public @Schema(value = "{... your json schema...}") ToolResponse toolName() {
//return your tool response with the json object
}

Result:

{
 "id": 2,
 "jsonrpc": "2.0",
 "result": {
     "isError": false,
     "structuredContent": [
        {
	"street": {
 	  "streetName": "Poles Ln",
  	  "roadType": "n/a"
           }
        } ] }}

Allowing annotations in MCP Content objects

As specified in the MCP specification we now allow annotations to be created and returned by tools as Content objects. This provides hints to clients on how to use and display the content. Included in the annotation is:

• audience field - indicating the intended audience for the content,
• priority field - indication the importance of the content object, and
• lastModified field - indicating when the content object was last modified.

This can be added to tools as represented below.

@Tool(name = "...")
public TextContent toolName(@ToolArg(name = "...", description = "...") String input) {
        Content.Annotations annotations = new Content.Annotations(Role, lastModified, priority)
	return new TextContent(text, _meta, annotations);
}

Result:

{
  "id": 1,
  "jsonrpc": "2.0",
  "result": {
    "content": [
     {
       "annotations": {
         "audience": "...",
         "lastModified": "...",
         "priority": 0.5
       },
       "text": "...",
       "type": "text"
       }
     ],
    "isError": false
    }
 }

</GHA-BLOG-SUMMARY>

What happens next?

• Add the label to the blog issue for the beta you're targeting (e.g. target:YY00X-beta).
• Make sure this blog post is linked back to the Epic for this feature/function.
• Your paragraph will be included in the beta blog post. It might be edited for style and consistency.
• You will be asked to review a draft before publication.
  • Once you've approved the code review, close this issue.
• If you would also like to write a standalone blog post about your update (highly recommended), raise an issue on the Open Liberty blogs repo. State in the issue that the blog post relates to a specific release so that we can ensure it is published on an appropriate date (it won't be the same day as the beta blog post).

[habiblawal1]

I've made mcpServer-1.0 a code block
I'm wondering if we need to mention it including bug fixes in the description - can ask @Azquelt for his opinion.

Could also add the following benefit for async tools: Your MCP server stays responsive and can handle multiple requests concurrently, making better use of resources while time-consuming operations run in the background.

For stateless mode we could maybe add to the benefit with "we now can distinguish clearly between stateless and stateful requests to a server by enabling stateless mode. This mode removes the need for session affinity in a clustered environment, allowing any server instance to handle any request, simplifying load balancing and horizontal scaling." This is from the improved description in Improve description of MCP stateless mode #33580

It maybe good to also add an example of an inline @Schema annotation where the type is being used as a tool argument. For the output schema you could add Result: before the json output example.

For the annotations section, I'd break up the explanation of each annotation into bullet point for easier reading

[Azquelt]

Although MCP is built around synchronous operations, we can now support asynchronous operations. With this feature, tool users can wrap their tool responses in a CompletionStage.

This enables a non-blocking execution pattern for the server to kick off long running tools, which clients can then check back later for results when the stage completes. Your MCP server stays responsive and can handle multiple requests concurrently, making better use of resources while time-consuming operations run in the background.

This isn't quite what asynchronous tools are for. Generally, asynchronous is used to consume less resources on the server while waiting for things to happen. (E.g. you call a remote service and need to wait for its response.)

I wouldn't say that MCP is built around synchronous operations and the server can still handle concurrent requests when using synchronous tools. Using async correctly may improve the number of concurrent requests your system can handle at once, depending on what you're doing.

Sync/async tools look exactly the same to the client and they call them in the same way. MCP 2025-11-25 added tasks which allow the client to fetch results of long running operations later, but that's not directly related to async and we don't support it yet.

I would change these paragraphs to this:

MCP tools can now run asynchronously by returning a CompletionStage. If a tool has to wait for something, such as for data to be returned from a remote system, running asynchronously means it doesn't have to consume a thread while waiting.

The tool method can return a CompletionStage quickly, but the response won't be returned to the client until the CompletionStage completes and provides the response data.

We should also update our example to show using Jakarta REST or MicroProfile REST Client to make an asynchronous request.

[Azquelt]

Stateless mode
As required by the MCP Specification, we now can distinguish clearly between stateless and stateful requests to a server by enabling stateless mode.

I wouldn't state it like this. Partly because the MCP Specification doesn't directly require it, it's just needed to implement the specification. Linking to this particular part also isn't helpful because we don't implement Elicitation. "we now can distinguish clearly between stateless and stateful requests" also isn't what this feature is about.

Let's try this:

Parts of the Model Context Protocol require the server to store some information about the client, and use that information when handling different requests from the same client. However, this makes clustering MCP servers difficult because different requests to the same client could be served by different servers so that information needs to be shared between all the servers.

One way to do this is called session affinity, where the ingress or load balancer in front of the MCP servers ensures that all requests from a single session are served by the same server. However, this requires special support for the way MCP indicates sessions and support for MCP session affinity isn't widely available currently.

This beta introduces another option called "stateless mode". This option disables the features of MCP which require storing state so that MCP servers can be clustered easily, without any special logic for session affinity, at the expense of some functionality.

At the moment enabling stateless mode disables the ability for a client to cancel tool calls. As we add new features, we will document which of those features are disabled or have limitations in stateless mode.

---

When stateless mode is enabled, you will not be able to cancel ongoing requests, therefore any notifications to cancel a request will be ignored, and by extension, you will not be able to delete a session.

Requests made in stateless mode should NOT provide a Mcp-Session-Id header. The Liberty server will automatically pick up the stateless mode configuration at startup, and any requests made with a session Id will be rejected.

If the above configuration is not enabled, all requests are assumed to be stateful and must provide a session ID for each request

This is all correct, but we've made it sound like something the user has to do, whereas it's likely going to be taken care of for them, either by their client or by a library. We can keep it, but let's make it sound informational rather than instructional:

One of the main differences when running in stateless mode is that the server won't assign clients a session ID, which means that later requests from the client won't include the Mcp-Session-Id header.

[Azquelt]

Input and Output Schema support

There are so many things that should be mentioned under this section and we should probably split it up a bit.

Although the issue that went into this release was about generating schemas, the functionality delivered to the user is being able to deal with structured content, so that should be the heading.

1. You can return structured content using Tool.structuredContent = true, document this and show an example
2. When using structured content, the output objects are serialized using Jsonb. It's important to state this so that users know how we'll serialize their objects and how they can change the defaults.
3. MCP requires a schema to be provided for the inputs and outputs of a tool. Usually we generate this for you based on the return type of the tool method.
   • Users can add descriptions to the schema using @Schema(description = " ... ")
   • Users can override the schema for an object completely using @Schema(" ... the whole schema here ... "), which they may need to do if they customize the serialization of their objects, or if we can't generate a schema for some other reason.
   • These two points only need a short example of each, but the example should use real values, not just placeholders. Also, use the """ syntax for multi-line strings and format the schema object nicely.