🧩 Running the Helidon MCP Server in Docker: A Minimal Java Implementation for the Model Context Protocol

TL;DR:
Helidon 4.3 now supports the Model Context Protocol (MCP) — a new way to connect applications, tools, and LLMs through a unified, event-driven interface.
In this post, we’ll containerize a plain Helidon MCP Server, run it locally using Docker, and make it discoverable in the Docker MCP Hub.

🧠 What Is the Model Context Protocol (MCP)?

The Model Context Protocol (MCP) defines how large language models (LLMs), agents, and applications exchange structured data and “context.”
It allows tools to:

• Describe capabilities (called tools or resources),
• Send and receive streamed events, and
• Maintain stateful reasoning contexts between human and machine.

Think of MCP as an HTTP-based protocol that standardizes how AI systems talk to APIs, databases, and user-facing services.

☕ Why Helidon?

Helidon is Oracle’s lightweight, modern Java framework for building microservices.
With version 4.3, it introduced support for MCP annotations, making it easy to turn any Helidon service into a Model Context Protocol endpoint.

@Mcp.Server
@Path("/mcp/helidon")
public class McpServer {

    @Mcp.Tool(name = "hello.world")
    public String hello(@Mcp.Argument("name") String name) {
        return "Hello, " + name + " from Helidon MCP!";
    }
}

That’s all it takes to define a compliant MCP server — no extra plumbing.

🐳 Step 1: Dockerize the Helidon MCP Server

Let’s containerize this minimal MCP server so it can run anywhere (including the Docker MCP Toolkit).

Dockerfile:

FROM eclipse-temurin:21-jre-alpine
WORKDIR /app
COPY target/helidon-mcp-server.jar /app/app.jar
EXPOSE 8080
ENV MCP_PATH=/mcp/helidon
CMD ["java", "-jar", "/app/app.jar"]

Build and run:

docker build -t helidon-mcp-server:latest .
docker run --rm -p 8080:8080 helidon-mcp-server:latest

You now have a running MCP server listening on:

http://localhost:8080/mcp/helidon

⚙️ Step 2: Verify with Docker MCP Toolkit

The Docker MCP Toolkit allows you to plug your MCP server into any LLM runtime (like ChatGPT or Claude Desktop).

task build -- --tools helidon-mcp-server
task catalog -- helidon-mcp-server
docker mcp catalog import catalogs/helidon-mcp-server/catalog.yaml

Then open Docker Desktop → MCP Toolkit, enable Helidon MCP Server, and you’ll see hello.world listed as a callable tool.

Test it directly from the Toolkit UI or via an MCP client.

🔧 Step 3: Add Metadata for the MCP Hub

To publish the container in the Docker MCP Registry, add a simple metadata file:

server.yaml

name: helidon-mcp-server
type: local
meta:
  category: productivity
  tags: [java, helidon, microservice, mcp]
about:
  title: Helidon MCP Server (Dockerized)
  description: Minimal Helidon 4.3 MCP server container for the Docker MCP Hub.
  icon: https://helidon.io/img/helidon-logo.svg
source:
  project: https://github.com/helidon-io/helidon
transport:
  type: streamable-http

This tells Docker Desktop how to display and launch your server.

🧰 Step 4: (Optional) Predefine Your Tools

If your MCP server can’t list tools automatically at startup, include a small tools.json file:

[
  {
    "name": "hello.world",
    "description": "Example MCP tool returning a greeting.",
    "arguments": [
      { "name": "name", "type": "string", "desc": "Name to greet" }
    ]
  }
]

This ensures the registry’s CI passes even when secrets or configs aren’t available yet.

🧭 Folder Structure

servers/helidon-mcp-server/
 ├── Dockerfile
 ├── server.yaml
 ├── tools.json
 └── README.md

🧩 End Result

Once published, your entry appears in the Docker MCP Hub, where developers can enable it in the MCP Toolkit and start using your Helidon service directly — without writing adapters or SDKs.

It becomes part of a growing ecosystem of AI-ready microservices that follow the same open protocol.

💡 Why It Matters

By running the Helidon MCP Server in Docker, you:

• Provide a reusable Java MCP baseline for other frameworks.
• Enable instant interoperability with LLMs and agents.
• Contribute to the open-source MCP ecosystem.

For Java developers, this is the easiest way to experiment with LLM integrations using familiar Helidon APIs and standard Docker workflows.

📚 Resources

• Helidon MCP Documentation
• Model Context Protocol Specification
• Docker MCP Registry
• Docker Desktop MCP Toolkit

🧩 Helidon + MCP + Docker = a clean, composable future for AI-ready microservices.