Java Samples

MCP server samples in Java using Spring AI and Spring Boot — from a basic calculator with SSE transport to an advanced content-safety application.

The Java samples use Spring AI’s MCP Server Boot Starter and WebFlux for reactive SSE transport. Tools are registered declaratively with the @Tool annotation.

Basic (SSE)

Basic calculator server

Located at 03-GettingStarted/samples/java/calculator, this Spring Boot application exposes a full-featured calculator through MCP over SSE.

1. Clone and navigate

   git clone https://github.com/microsoft/mcp-for-beginners.git
   cd mcp-for-beginners/03-GettingStarted/samples/java/calculator
   
2. Build the project

   ./mvnw clean install -DskipTests
   
3. Run the server

   java -jar target/calculator-server-0.0.1-SNAPSHOT.jar
   

   The server starts on http://localhost:8080. The SSE endpoint is at /sse.

Server code

McpServerApplication.java

package com.microsoft.mcp.sample.server;

import org.springframework.ai.tool.ToolCallbackProvider;
import org.springframework.ai.tool.method.MethodToolCallbackProvider;
import org.springframework.boot.SpringApplication;
import org.springframework.boot.autoconfigure.SpringBootApplication;
import org.springframework.context.annotation.Bean;

@SpringBootApplication
public class McpServerApplication {

    public static void main(String[] args) {
        SpringApplication.run(McpServerApplication.class, args);
    }

    @Bean
    public ToolCallbackProvider calculatorTools(CalculatorService calculator) {
        return MethodToolCallbackProvider.builder().toolObjects(calculator).build();
    }
}

Client code (MCP SDK)

SDKClient.java

import io.modelcontextprotocol.client.McpClient;
import io.modelcontextprotocol.client.transport.WebFluxSseClientTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolRequest;
import org.springframework.web.reactive.function.client.WebClient;

public class SDKClient {
    public static void main(String[] args) {
        var transport = new WebFluxSseClientTransport(
            WebClient.builder().baseUrl("http://localhost:8080")
        );
        var client = McpClient.sync(transport).build();
        client.initialize();

        // List available tools
        System.out.println(client.listTools());

        // Call the add tool
        var result = client.callTool(
            new CallToolRequest("add", Map.of("a", 5.0, "b", 3.0))
        );
        System.out.println("5 + 3 = " + result);

        // Call squareRoot
        var sqrt = client.callTool(
            new CallToolRequest("squareRoot", Map.of("number", 16.0))
        );
        System.out.println("√16 = " + sqrt);

        client.closeGracefully();
    }
}

LangChain4j client with GitHub models

The sample also includes a LangChain4jClient that connects an AI model to the calculator through MCP:

LangChain4jClient.java (excerpt)

ChatLanguageModel model = GitHubChatModel.builder()
    .apiKey(System.getenv("GITHUB_TOKEN"))
    .timeout(Duration.ofSeconds(60))
    .modelName("phi-4")
    .logRequests(true)
    .logResponses(true)
    .build();

Set your token before running:

export GITHUB_TOKEN=your-github-personal-access-token

Test with MCP Inspector

1. Start the Inspector

   npx @modelcontextprotocol/inspector
   
2. Connect via SSE

   • Transport type: SSE
   • URL: http://localhost:8080/sse
   • Click Connect, then List Tools

Run in Docker

docker build -t calculator-mcp-service .
docker run -p 8080:8080 calculator-mcp-service

The Dockerfile uses a multi-stage build with Maven 3.9.9 and Eclipse Temurin 24 JDK.

Key Maven dependencies

pom.xml (excerpt)

<!-- MCP Server over SSE -->
<dependency>
    <groupId>org.springframework.ai</groupId>
    <artifactId>spring-ai-starter-mcp-server-webflux</artifactId>
</dependency>

<!-- LangChain4j MCP integration -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-mcp</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

<!-- GitHub model support -->
<dependency>
    <groupId>dev.langchain4j</groupId>
    <artifactId>langchain4j-github</artifactId>
    <version>${langchain4j.version}</version>
</dependency>

Advanced (Container App)

Advanced: content safety + LangChain4j

Located at 04-PracticalImplementation/samples/java/containerapp, this Spring Boot web application wraps the calculator MCP server with dual-layer Azure Content Safety screening.

Architecture

1. User submits a calculation prompt via a web UI
2. Input screening — Azure Content Safety checks the prompt
3. If safe, LangChain4j sends the prompt to the calculator MCP server
4. Output screening — Azure Content Safety checks the model’s response
5. Safe responses are displayed; flagged responses are replaced with a warning

Setup

1. Create an Azure Content Safety resource

   In the Azure Portal, create a Content Safety resource and copy its endpoint and key.

2. Set environment variables

   export GITHUB_TOKEN=<your_github_token>
   export CONTENT_SAFETY_ENDPOINT=<your_endpoint>
   export CONTENT_SAFETY_KEY=<your_key>
   
3. Start the calculator MCP server

   Start the basic calculator server (see the Basic tab) on localhost:8080 before starting this app.

4. Run the container app

   mvn spring-boot:run
   

   Open http://localhost:8087 in your browser.

Features

• Dual-layer content safety (input + output)
• LangChain4j integration with GitHub’s gpt-4.1-nano model
• SSE transport to the calculator MCP server
• Color-coded safety indicators in the web UI