Connecting AI Agents to Axon Applications via MCP

This example demonstrates how an AI agent can interact with an MCP Server to send commands and queries to an Axon application via Axon Server.

Overview

This example is composed of the following components:

• Bike Rental

  An Axon application (Java/Spring) for a bike rental domain that will receive commands and queries from the agent.

• Axon Server

  The event store and message router that bridges the MCP Server with the Axon application.

  Axon Server as of v2025.x offers HTTP and RSocket APIs for integration purposes; the MCP Server - implemented in Python - uses (a small subset of) the HTTP APIs.

• MCP Server

  An application-specific MCP Server implementation that translates tool calls into commands and queries in the bike rental domain.

• Agent and MCP Client

  Interacts with the LLM and performs tool invocations in response to user prompts for bike rental operations, such as registering new bikes and getting a list of available bikes.

  Note: This example uses OpenAI. The agent framework used (Dapr Agents) supports swapping LLM providers.

Installation

The aforementioned components can be installed by following the steps below.

• Clone the solution branch of the Axon application repo:

  git clone -b solution https://github.com/AxonIQ/bike-rental-workshop
  

• The README.md in the repo, in the Installation section, details how to setup a JDK environment and the required Axon Server.

• Create an .env file in this project's root and add your OpenAI API key (used by the Dapr Agents framework to setup the corresponding LLM provider):

  OPENAI_API_KEY=<api_key>
  

• Install project dependencies:

  uv sync
  

  Note: Ensure that the uv Python package manager is installed on your system.

Running the Example

Ensure that the Axon application and Axon Server have started:

// Launch Axon Server; if using the JAR option:
java -jar axonserver.jar

// Navigate to the Axon Server Dashboard and complete the installation of Axon Server to run in "Standalone" mode if you haven't done so already.

// Launch the Axon application using Maven (or within your IDE).
//
// Specifically, run the RentalApplication.
mvn package
java -jar rental/target/rental-0.0.1-SNAPSHOT.jar

Run the agent:

// Connect to the MCP Server via stdio (a real deployment would use HTTP streaming transport).
uv run chainlit run client.py

In the (chainlit) chat UI, a session might look as follows:

user: 
Register a bike

assistant:
Please provide the bike type and location (if any) for the bike you'd like to register. If you don't have specific details, I can register it with default attributes.

user:
register with default attributes

assistant:
The bike has been successfully registered with default attributes. If you need further assistance, feel free to ask!

user:
Register a bike of type ebike and location Copenhagen

assistant:
The e-bike has been successfully registered with the location specified as Malmö. Let me know if you need further assistance!

user:
show me all bikes

assistant:
Here is the list of available bikes:

1. Bike ID: f5918f34-7f6f-4776-b042-d218fa8f5d31
- Type: Not specified
- Location: Not specified
- Status: Available

3. Bike ID: 7b2fffce-062b-4a46-9f2a-d383b7332842
- Type: Ebike
- Location: Copenhagen
- Status: Available

If you need more details or further assistance, feel free to ask!

By navigating to the Axon Server Dashboard and inspecting the event store, one will find the corresponding events (BikeRegisteredEvent) for the added bikes.