microsoft--mcp-for-beginners/03-GettingStarted/02-client/solution/java/README.md

MCP Java Client - Calculator Demo

This project demonstrates how to create a Java client that connects to and interacts with an MCP (Model Context Protocol) server. In this example, we'll connect to the calculator server from Chapter 01 and perform various mathematical operations.

Prerequisites

Before running this client, you need to:

1. Start the Calculator Server from Chapter 01:

   • Navigate to the calculator server directory: 03-GettingStarted/01-first-server/solution/java/
   • Build and run the calculator server:

     cd ..\01-first-server\solution\java
     .\mvnw clean install -DskipTests
     java -jar target\calculator-server-0.0.1-SNAPSHOT.jar
     

   • The server should be running on http://localhost:8080

2. Java 21 or higher installed on your system

3. Maven (included via Maven Wrapper)

What is the SDKClient?

The SDKClient is a Java application that demonstrates how to:

• Connect to an MCP server using Server-Sent Events (SSE) transport
• List available tools from the server
• Call various calculator functions remotely
• Handle responses and display results

How It Works

The client uses the Spring AI MCP framework to:

1. Establish Connection: Creates a WebFlux SSE client transport to connect to the calculator server
2. Initialize Client: Sets up the MCP client and establishes the connection
3. Discover Tools: Lists all available calculator operations
4. Execute Operations: Calls various mathematical functions with sample data
5. Display Results: Shows the results of each calculation

Project Structure

src/
└── main/
    └── java/
        └── com/
            └── microsoft/
                └── mcp/
                    └── sample/
                        └── client/
                            └── SDKClient.java    # Main client implementation

Key Dependencies

The project uses the following key dependencies:

<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

This dependency provides:

• McpClient - The main client interface
• WebFluxSseClientTransport - SSE transport for web-based communication
• MCP protocol schemas and request/response types

Building the Project

Build the project using the Maven wrapper:

.\mvnw clean install

Running the Client

java -jar .\target\calculator-client-0.0.1-SNAPSHOT.jar

Note: Make sure the calculator server is running on http://localhost:8080 before executing any of these commands.

What the Client Does

When you run the client, it will:

1. Connect to the calculator server at http://localhost:8080
2. List Tools - Shows all available calculator operations
3. Perform Calculations:
   • Addition: 5 + 3 = 8
   • Subtraction: 10 - 4 = 6
   • Multiplication: 6 × 7 = 42
   • Division: 20 ÷ 4 = 5
   • Power: 2^8 = 256
   • Square Root: √16 = 4
   • Absolute Value: |-5.5| = 5.5
   • Help: Shows available operations

Expected Output

Available Tools = ListToolsResult[tools=[Tool[name=add, description=Add two numbers together, ...], ...]]
Add Result = CallToolResult[content=[TextContent[text="5,00 + 3,00 = 8,00"]], isError=false]
Subtract Result = CallToolResult[content=[TextContent[text="10,00 - 4,00 = 6,00"]], isError=false]
Multiply Result = CallToolResult[content=[TextContent[text="6,00 * 7,00 = 42,00"]], isError=false]
Divide Result = CallToolResult[content=[TextContent[text="20,00 / 4,00 = 5,00"]], isError=false]
Power Result = CallToolResult[content=[TextContent[text="2,00 ^ 8,00 = 256,00"]], isError=false]
Square Root Result = CallToolResult[content=[TextContent[text="√16,00 = 4,00"]], isError=false]
Absolute Result = CallToolResult[content=[TextContent[text="|-5,50| = 5,50"]], isError=false]
Help = CallToolResult[content=[TextContent[text="Basic Calculator MCP Service\n\nAvailable operations:\n1. add(a, b) - Adds two numbers\n2. subtract(a, b) - Subtracts the second number from the first\n..."]], isError=false]

Note: You may see Maven warnings about lingering threads at the end - this is normal for reactive applications and doesn't indicate an error.

Understanding the Code

1. Transport Setup

var transport = new WebFluxSseClientTransport(WebClient.builder().baseUrl("http://localhost:8080"));

This creates an SSE (Server-Sent Events) transport that connects to the calculator server.

2. Client Creation

var client = McpClient.sync(this.transport).build();
client.initialize();

Creates a synchronous MCP client and initializes the connection.

3. Calling Tools

CallToolResult resultAdd = client.callTool(new CallToolRequest("add", Map.of("a", 5.0, "b", 3.0)));

Calls the "add" tool with parameters a=5.0 and b=3.0.

Troubleshooting

Server Not Running

If you get connection errors, make sure the calculator server from Chapter 01 is running:

Error: Connection refused

Solution: Start the calculator server first.

Port Already in Use

If port 8080 is busy:

Error: Address already in use

Solution: Stop other applications using port 8080 or modify the server to use a different port.

Build Errors

If you encounter build errors:

.\mvnw clean install -DskipTests

Learn More

• Spring AI MCP Documentation
• Model Context Protocol Specification
• Spring WebFlux Documentation