Dice Roller

The way humans typically interact with AI is via a chat-style interface such as ChatGPT or Claude Desktop. In fact, the ability to converse with an AI in natural language is perhaps one of the most amazing things about this technology. It lets humans talk to computers in human terms, rather than requiring that the human work within the confines of an interface made up of buttons, lists, and text fields. Even though those traditional UIs aren’t as flexible and as fluid as a chat interface, they are sometimes the best and most natural way to communicate with an application. Clicking a location on a map, for example, is much more precise and natural than trying to describe where a specific location is in natural language. (That is, unless you just happen to know the latitude and longitude.) What if you could have the best of both worlds? What if you could chat with an AI, but then interact with a more traditional UI when it makes sense to do so? That’s precisely what MCP Apps brings to the conversation: The ability to embed rich UI elements in a chat interface. The result is a hybrid experience where chat and application blend together, allowing users to not just ask questions, but actively interact with tools and workflows without ever leaving the chat. Thanks to some contributions from the Spring AI community (shout out to Vadzim Shurmialiou and Alexandros Pappas for their pull-requests), it’s now easy to create rich UIs as part of an MCP server with Spring AI 2.0.0-M3. In this article, that’s exactly what we’ll do. ## MCP Apps in a Nutshell At its core, an MCP App has two primary elements: * A tool served by the MCP server that has metadata that references the HTML resource. * A resource served by the MCP server that is HTML (with JavaScript and CSS) that makes up the UI. The UI itself is a special kind of MCP client that can communicate with the MCP server, as well as its host assistant, using JSON-RPC. To make server-interaction easier, there’s an ext-apps.ts module that the UI can use to invoke tools, handle context changes, push messages to the host, and many other things. To demonstrate how to build MCP Apps with Spring AI, let’s create a simple, but fun dice-rolling example. ## Initializing the Project The first step in creating an MCP server that includes an MCP App is to create an MCP server. With Spring AI, that starts with using the Spring Boot Initializr (whether with your IDE or through https://start.spring.io) to initialize a new Spring Boot project that includes the Spring MVC and Model Context Protocol Server dependencies. * * * **⚠️ IMPORTANT** Once the project has been initialized, you’ll want to make sure that the Spring AI version is 2.0.0-M3 or higher. It’s with this version that MCP annotations were merged into Spring AI itself and that the ability to specify metadata on tools and resources—important for working with MCP Apps—was added. For a Gradle-built project, you should see this block in build.gradle: ext { set('springAiVersion', "2.0.0-M3") } If you’re using Maven, then look for a `` block that looks like this:

2.0.0-M3

* * * With the freshly initialized project, you’re ready to define the app’s user interface. ## Define the User Interface The user interface of an MCP App is a typical HTML file, plus any accompanying JavaScript and/or CSS. To demonstrate MCP Apps, let’s create a UI for rolling a pair of dice. The following HTML defines such a UI (src/main/resources/app/dice-app.html): Dice Roller

⚀ ⚀

That’s quite a lot of HTML! Most of it defines the visual elements of the UI as well as some JavaScript-driven animation for effect. But there are a few pieces of the HTML of particular interest to the subject of creating MCP Apps, all of which is contained within the first several lines of the `