# πŸ€– AI-enable existing Microservices by adding built-in MCP Server **URL:** \ **Category:** Knowledge Base\ **Tags:** microservices, mcp-server, MicroserviceSDK, ai, ai-agents, microservice\ **Created:** [September 19, 2025, 1:32pm UTC](https://community.cumulocity.com/t/ai-enable-existing-microservices-by-adding-built-in-mcp-server/12523 "2025-09-19T13:32:38Z")\ **Posts on this page:** 1\ **Page:** 1
**Author:** ![Stefan\_Witschel](https://dub1.discourse-cdn.com/flex005/user_avatar/community.cumulocity.com/stefan_witschel/32/31955_2.png) [@Stefan\_Witschel](https://community.cumulocity.com/u/Stefan_Witschel)\ **Post date:** [September 19, 2025, 1:32pm UTC](https://community.cumulocity.com/t/ai-enable-existing-microservices-by-adding-built-in-mcp-server/12523/1 "2025-09-19T13:32:38Z")
## Overview In this article, I will demonstrate how you can quickly extend your existing (or new) microservice, developed by using the Java Microservice SDK, with an MCP Server providing custom tools for your AI agent. [MCP (Model Context Protocol)](https://modelcontextprotocol.io/docs/getting-started/intro) is a standard that was developed to integrate external systems with an AI agent or application. While simple AI agents work pretty well by mainly using the LLM, some of them need special context. Just think about an AI agent that should help you to discover issues in your device fleet or requires any other data that is not known by the LLM. For that, attached to the AI trend, MCP rapidly became THE standard for providing additional context to AI agents. No wonder a lot of vendors, open-source components, and applications adopted it and developed MCP-Servers themselves to expose data and functionality to AI or provided tools to easily build your own MCP Server. So also Cumulocity did, by providing an open-source MCP-Server which covers most of the available REST API, as described by @Nikolaus_Neuerburg in the following article. > [@Supercharging IoT with Agentic Systems: The Model Context Protocol (MCP)](https://community.cumulocity.com/t/supercharging-iot-with-agentic-systems-the-model-context-protocol-mcp/12159): > > Supercharging IoT with Agentic Systems: The Model Context Protocol (MCP) TL;DR The Model Context Protocol (MCP) enables AI agents to directly interact with IoT platforms, transforming passive monitoring systems into autonomous decision-makers. You can try the Cumulocity IoT open-source MCP Server implementation, allowing LLMs like Claude and GPT to directly query and control your IoT devices. It’s early daysβ€”we want your feedback and contributions! The Problem: Smart Dev… You can also check out the MCP Server yourself directly - it’s open source. > **[GitHub - Cumulocity-IoT/cumulocity-mcp-server: A Python-based server that provides Cumulocity IoT...](https://github.com/Cumulocity-IoT/cumulocity-mcp-server)** > > A Python-based server that provides Cumulocity IoT platform functionality through the MCP (Model Control Protocol) interface. That’s a huge benefit because with that you can develop AI agents that use IoT context provided by Cumulocity in a harmonized way. ```auto β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” β”‚ LLM Agent │◄──── MCP Protocol │◄──── IoT Platform β”‚ β”‚ (e.g. Claude/GPT)β”‚ β”‚ Server β”‚ β”‚ (e.g. Cumulocity) β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ ``` (Source: [Supercharing IoT Article](https://community.cumulocity.com/t/supercharging-iot-with-agentic-systems-the-model-context-protocol-mcp/12159)) But there is more to do. As Cumulocity is an open platform by allowing you to develop your own extensions such as microservices or UI plugins, these custom functionalities & data might also be useful to be used in your AI agent. ## Spring AI The Java Microservice SDK uses Spring Boot as a core. Luckily, Spring also jumped on the AI-train and developed a comprehensive [AI suite](https://docs.spring.io/spring-ai/reference/index.html) including libs to build your own MCP Server: > **[MCP Server Boot Starter :: Spring AI Reference](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html)** There they provided mulitple variants of MCP Server that can be used: - **Standard MCP Server** - which mainly supports STDIO server transport, meaning it is designed to be executed in a terminal to communicate like we know from other command-line tools. - **WebMVC Server Transport** - which supports SSE (Server-Sent Events) and STDIO, meaning it contains a lightweight web server that pushes messages/events to the clients leveraging HTTP. MVC stands for a classic web framework. - **WebFlux Server Transport** - which covers the same functionality as the WebMVC Server but uses the WebFlux Framework instead of the MVC Framework. WebFlux, in short, is a reactive web framework, meaning it is designed to build non-blocking asynchronous web applications. Especially designed for high concurrency and high load applications. - **Streamable HTTP Server Transport** - still in development therefor considered unstable but is available in WebMVC and WebFlux variants to support streamable HTTP which is a successor of the plain SSE Server Transport. In this guide, I will use the classic WebMVC variant as it supports SSE which is currently supported by the AI Agent Manager, but you could also use the WebFlux or any streamable HTTP variant of course. ## Adapting the microservice Assuming you already have a microservice with existing functionality, you can easily add MCP-based tools by following the described steps. 1. Upgrade your Microservice SDK to at least Spring Boot 3.4 2. Adding Spring AI dependencies to pom.xml 3. Adding MCP Server configuration properties 4. Expose custom tools by using annotations If you don’t have an existing microservice but you are still interested in adding a MCP Server, check out this guide first: > [@Microservice Best Practices: Getting Started](https://community.cumulocity.com/t/microservice-best-practices-getting-started/4392): > > Overview This article is part of the [Article series on Microservices Best Practices for Cumulocity IoT](https://community.cumulocity.com/t/microservices-best-practices-article-series-for-cumulocity-iot/3013). The goal of this Tech Community article series is to address the need for Best Practices for Microservices Development. The article serves as a starting point and provides an introduction to the concept of microservices in Cumulocity IoT as well as pointers to the most important libraries and tools that help you when developing a microservice. To wrap things up, we will develop our first … ### Upgrade your used Microservice SDK First of all, you need to check if your used microservice SDK must be upgraded. You should use at least **2025.18.0** , which uses **Spring Boot 3.4** as a minimum. Better is to use a newer version like **2025.67.0** , for example. Follow the guide if migration is needed: > [@Java Microservice Development: Preparing for Spring Boot 3.X](https://community.cumulocity.com/t/java-microservice-development-preparing-for-spring-boot-3-x/2341): > > Introduction For a long time, the Java microservice SDK only supported Spring Boot 2.X. We are pleased to announce that starting with version 1020.150.1, the microservice SDK now uses Spring Boot 3. In this article, I will describe how you can prepare your existing Java microservice for Spring Boot 3.X. The effort required to upgrade to a new version depends on the libraries and technologies used in your project. If you explicitly use any of the Spring updated libraries, you will probably nee… ### Adding dependencies Next, we need to add the required dependency to the `pom.xml`. Adding dependency management block (please adapt the version if a newer one is available): ```xml org.springframework.ai spring-ai-bom 1.1.0-SNAPSHOT pom import ``` Adding the dependency: ```xml org.springframework.ai spring-ai-starter-mcp-server-webmvc ``` ### Adding configuration properties Next, we need to adapt our `application.properties`. As a minimum, you should add the following: ```properties #Spring AI spring.ai.mcp.server.enabled=true spring.ai.mcp.server.name= spring.ai.mcp.server.base-url=/service/ ``` Example assuming your microservice name and context path is `hello-world-service`: ```properties #Spring AI spring.ai.mcp.server.enabled=true spring.ai.mcp.server.name=hello-world-mcp-service spring.ai.mcp.server.base-url=/service/hello-world-service ``` Check out the list of available properties here: [MCP Server Boot Starter :: Spring AI Reference](https://docs.spring.io/spring-ai/reference/api/mcp/mcp-server-boot-starter-docs.html) ### Expose tools by using annotations The next step is to annotate your existing methods of services or components with the `@Tool(..)` annotation. [Read more](https://docs.spring.io/spring-ai/reference/api/tools.html) if you want to understand how this annotation works. Here is an example that exposes a method to evaluate an expression for JSONata (to transform a JSON document) where `expression` and a JSON document as `sourceJSON` is provided: ```java /** * Test a JSONata expression against a JSON string. * @param expression JSONata expression to be evaluated against the source JSON * @param sourceJSON JSON string to be used as source for the JSONata expression evaluation * @return The result of the JSONata expression evaluation as a pretty-printed JSON string * @throws RuntimeException if the evaluation fails * @throws IllegalArgumentException if the expression or source JSON is null or empty */ @Tool(description = "Evaluate a JSONata expression against a JSON object") public String evaluateJsonataExpression(String expression, String sourceJSON) { if(expression == null || expression.isEmpty()) throw new IllegalArgumentException("JSONata expression cannot be null"); if(sourceJSON == null || sourceJSON.isEmpty()) throw new IllegalArgumentException("Source JSON cannot be null"); try { var expr = jsonata(expression); Object parsedJson = Json.parseJson(sourceJSON); Object result = expr.evaluate(parsedJson); return toPrettyJsonString(result); } catch (Exception e) { log.error("Error evaluating JSONata expression: ", e); throw new RuntimeException(e); } } ``` Yep, it’s that simple. Just annotate your function with `Tool` with a meaningful description, and you are good to go. To get more examples, check out the [Spring AI example servers](https://github.com/spring-projects/spring-ai-examples/blob/19f6d59e3eb71c3596200538363779ce55ee4a93/model-context-protocol/weather/starter-webmvc-server/src/main/java/org/springframework/ai/mcp/sample/server/WeatherService.java#L93) ### Adding ToolCallbackProviders Finally, we need to point our microservice to all services that expose Tools by adding the bean `ToolCallbackProvider` to the `App.java` class: ```java @Bean public ToolCallbackProvider myTools(...) { return MethodToolCallbackProvider.builder() .toolObjects(...) .build(); } ``` Again, an example where `AIAgentService` is a service where we used the `@Tools(...)` annotation. ```java @Bean public ToolCallbackProvider tools(AIAgentService aiAgentService) { return MethodToolCallbackProvider.builder() .toolObjects(aiAgentService) .build(); } ``` You can add multiple beans where `@Tools(...)` has been used That’s it! Now you can already build, deploy & run your microservice. Ideally, you deploy it directly to your tenant. ## Test the MCP Server Now that everything is implemented, we want to check if the MCP Server with its provided tools work as expected. There are several ways to achieve that. - Using a tool like [MCP Inspector](https://modelcontextprotocol.io/legacy/tools/inspector) running locally. - Using Cumulocity provided tools like **AI Agent Manager** (currently in private preview). ### Using a MCP Inspector We can easily start MCP Inspector with ```bash npx @modelcontextprotocol/inspector ``` assuming nodeJS is installed on your computer. When installed & started, it will open a browser window: ![chrome_lIgc86vd2i](https://europe1.discourse-cdn.com/flex005/uploads/cumulocity/original/3X/3/e/3e4ecd01d1c57b7b0345e7a46f16cb1e9fd85287.png) Change the **Transport Type** to `SSE` **URL** : `https:///service//sse` **API Token Authentication** : `` To retrieve the bearer token, you can simply go to your browser, log in to your Cumulocity tenant, open the developer tools with F12, and check the `Application` tab. Under `cookies`, you’ll find an `authorization` cookie containing an encoded bearer token as value. Copy it. > **!! Caution !!** Do not share this token with anyone! Back in MCP Inspector, you can just paste the token and click on `Connect`. After a short time, you will be connected. On the right side, you can now request all resources, prompts, and tools. By clicking on **List Tools** , it will fetch all tools of your MCP Server: ![image](https://europe1.discourse-cdn.com/flex005/uploads/cumulocity/original/3X/2/0/20f3810f5b2fde8424fc6f5b4b56097131473dbf.png) You can directly test it by providing the required input parameters. ### Using AI Agent Manager Will be added when AI Agent Manager is available, but to spoil the surprise: It’s even simpler than using MCP Inspector. Basically, you just need to paste the URL `https:///service//sse` and click on **Test connection** , which will return the available tools already. ![image](https://europe1.discourse-cdn.com/flex005/uploads/cumulocity/original/3X/1/1/11221e15c0e26dd0e785851a0e4eee31ad8fd763.png) ## Summary In this article, I demonstrated the steps to easily extend your existing microservices with a full-fledged MCP Server including tools to be used by AI agents. As you saw, by leveraging the Microservice SDK, it’s quite simple. Of course, you can also build an MCP Server on top of any other microservice that has been developed in other programming languages. This will most probably require a little bit more effort to find the right libs and defining tools in your code. As an example for Python, you can check this repository: > **[GitHub - Cumulocity-IoT/cumulocity-mcp-server: A Python-based server that provides Cumulocity IoT...](https://github.com/Cumulocity-IoT/cumulocity-mcp-server)** > > A Python-based server that provides Cumulocity IoT platform functionality through the MCP (Model Control Protocol) interface. Leave a comment if you have feedback or questions.