Table of Contents

Disk Space MCP Server with Streamable HTTP transport

Build a MCP Server with Streamable HTTP transport to expose your machine diskspace.

Authors: Sergio del Amo

Micronaut Version: 4.10.7

1. Getting Started

In this guide, we will create a Micronaut application written in Java.

2. What you will need

To complete this guide, you will need the following:

3. Solution

We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.

Create an application using the Micronaut Command Line Interface or with Micronaut Launch.

4. Dependency

Add the Micronaut MCP Server Java SDK dependency to your build file:

build.gradle
implementation("io.micronaut.mcp:micronaut-mcp-server-java-sdk")

5. Configuration

src/main/resources/application.properties
micronaut.mcp.server.info.name=Disk Space
micronaut.mcp.server.info.version=0.0.1
(1)
micronaut.mcp.server.transport=HTTP
1 To use Streamable HTTP

6. Disk Utils

Create a utility class to get the disk space information of the computer.

src/main/java/example/micronaut/DiskUtils.java
package example.micronaut;

import java.io.File;

public final class DiskUtils {
    private DiskUtils() {}

    public static String freeDiskSpace() {
        File root = new File("/");
        long freeBytes = root.getFreeSpace();
        double freeGB = freeBytes / (1024.0 * 1024 * 1024);
        return String.format("Free disk space: %.2f GB", freeGB);
    }
}

7. MCP Tool

Next, we are going to create an MCP Tool that exposes the disk space information.

Tools: Executable functions that allow models to perform actions or retrieve information

src/main/java/example/micronaut/MyTools.java
package example.micronaut;

import io.micronaut.mcp.annotations.Tool;
import jakarta.inject.Singleton;
import java.io.File;

@Singleton (1)
class MyTools {
    @Tool(title = "Free Disk Space",
          description = "Return the free disk space in the users computer")  (2)
    String freeDiskSpace() {
        return DiskUtils.freeDiskSpace();
    }
}
1 Use jakarta.inject.Singleton to designate a class as a singleton.
2 Annotate a method with @Tool to expose it as an MCP Tool.

8. Running the Application

To run the application, use the ./gradlew run command, which starts the application on port 8080.

8.1. MCP Inspector

To test the MCP Server, run the MCP inspector.

Select Streamable HTTP as Transport type.

Enter http://localhost:8080/mcp as the URL.

Click connect. You will be able to list tools and invoke the freeDiskSpace tool.

mcp diskspace http

9. Tests

9.1. Test Dependencies

Add the Micronaut Java SDK MCP Client dependency to your build file:

build.gradle
testImplementation("io.micronaut.mcp:micronaut-mcp-client-java-sdk")

9.2. Test

The following test verifies the application exposes an invokable tool.

src/test/java/example/micronaut/MyToolsTest.java
package example.micronaut;

import io.micronaut.test.extensions.junit5.annotation.MicronautTest;
import io.modelcontextprotocol.client.McpSyncClient;
import io.modelcontextprotocol.spec.McpSchema;
import org.junit.jupiter.api.Test;
import org.junit.platform.commons.util.CollectionUtils;

import java.util.Collections;

import static org.junit.jupiter.api.Assertions.*;

@MicronautTest
class MyToolsTest {

    @Test
    void mcpCallTool(McpSyncClient mcpClient) {
        McpSchema.CallToolResult callToolResult = assertDoesNotThrow(() ->
                mcpClient.callTool(new McpSchema.CallToolRequest("freeDiskSpace", Collections.emptyMap())));
        assertEquals(1, callToolResult.content().size());
        assertInstanceOf(McpSchema.TextContent.class, callToolResult.content().get(0));
        McpSchema.TextContent textContent = (McpSchema.TextContent) callToolResult.content().get(0);
        String response = textContent.text();
        assertTrue(response.contains("Free disk space"));
    }

    @Test
    void mcpListTools(McpSyncClient mcpClient) {
        McpSchema.ListToolsResult listToolsResult = assertDoesNotThrow(() ->
                mcpClient.listTools());

        assertEquals(1, listToolsResult.tools().size());
        McpSchema.Tool tool = listToolsResult.tools().get(0);
        assertEquals("freeDiskSpace", tool.name());
        assertEquals("Free Disk Space", tool.title());
        assertEquals("Return the free disk space in the users computer", tool.description());
    }
}

10. Testing the Application

To run the tests:

./gradlew test

Then open build/reports/tests/test/index.html in a browser to see the results.

11. Next Steps

Explore more features with Micronaut Guides.

Check the Micronaut MCP documentation and the Micronaut MCP Guides

12. License

All guides are released with an Apache license 2.0 license for the code and a Creative Commons Attribution 4.0 license for the writing and media (images…​).