Connect Claude AI with own Quarkus MCP-Server

1. Einführung

Anthropic hat ein neues offenes Protokoll namens Model Context Protocol (MCP) vorgestellt. Die Idee dahinter: KI-Assistenten sollen viel einfacher auf externe Datenquellen oder sogar komplette Apps zugreifen können – und zwar sicher, flexibel und effizient. Mit MCP können Entwickler entweder ihre Daten für KI-Systeme „bereitstellen“ (Zugriff auf Filesystem) oder Tools bauen (Zugriff über Applikation mit MCP-Interface), die diese Daten über standardisierte Schnittstellen abrufen. Anthropic’s Claude AI ist dabei das erste LLM, dass die Integration von MCP-Servern in deren Chatbot erlaubt. Ein MCP-Server kann unter anderem auch in Quarkus oder Spring Boot implementiert werden.

2. Wie funktioniert MCP?

Die Grundlage aller Datenbestände bildet eine zentrale Datenbank.
Eine spezialisierte Anwendung dient als Schnittstelle: Sie verfügt einerseits über Zugriff auf diese Datenbank und stellt andererseits die darin enthaltenen Informationen über das MCP-Protokoll zur Verfügung.
Der Nutzer interagiert über einen LLM-Client (z.B. Claude AI). Das LLM hat Zugriff auf die verschiedenen MCP-Interfaces (die sogennanten Tools) der Anwendungen und identifiziert anhand der gestellten Anfrage das am besten geeignete Tool.
Anschließend stellt es eine Abfrage an dieses Tool – gegebenenfalls unter Angabe von Parametern.
Je nach implementierter Logik liefert das aufgerufene MCP-Tool die angeforderten Daten an den LLM-Client zurück.
Auf Basis dieser Daten generiert das LLM eine passende Antwort.

Das MCP-Protokoll basiert auf JSON-RPC. Die Kommunikation kann dabei auf zwei Arten erfolgen:

STDIO (Standard Input/Output): Der MCP-Client nutzt die STDIO-Konsole des MCP-Servers zur Übertragung der JSON-RPC-Anfragen.
- eher für den Entwicklungsprozess geeignet
SSE (Server-Sent Events): Der MCP-Client kommuniziert über ein Webinterface mit dem Server und sendet die JSON-RPC-Aufrufe darüber.
- für Produktivbetrieb geeignet

3. Implementierung mit Quarkus

3.1. Motivation

Es soll ein MCP-Server gebaut werden, welcher Auskunft über die Sprechstunden der Lehrerinnen und Lehrer der HTL Leonding geben kann. Als Datenbasis wird die Sprechstundenliste als CSV-Datei von https://mese.webuntis.com/timetable-contact-hours genommen.

3.2. Voraussetzungen

Java-IDE wie IntelliJ IDEA von großem Vorteil
Maven 3.9.9 oder Maven-Wrapper
Java 21 (Temurin 21 LTS)
Claude Desktop
- Download für Windows/macOS
- Inoffizieller Repackaging-Download für Debian

Claude Desktop installieren und sich registrieren. Beim Repackaging-Download unter Debian-Systemen kann es sein, dass die App nicht gestartet wird. Dann im Terminal mit claude-desktop --no-sandbox starten.

3.3. Basisprojekt

Als Basisprojekt wird ein Quarkus-Projekt genommen, welches mittels JDBC und Panache an eine PostgreSQL-Datenbank angebunden ist. Die in der CSV-Datei liegende Sprechstundenliste wird normalisiert und in die Datenbank gespielt. Mehr dazu: Basisprojekt des MCP-Servers für die Sprechstundenliste

3.4. Maven-Dependency

Nun folgt die Entscheidung, ob die Kommunikation über STDIO oder SSE ablaufen soll. Für beide Fälle gibt es die passende Dependency.

STDIO:

Details

pom.xml

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-stdio</artifactId>
    <version>1.0.0</version>
</dependency>

SSE:

Details

pom.xml

<dependency>
    <groupId>io.quarkiverse.mcp</groupId>
    <artifactId>quarkus-mcp-server-sse</artifactId>
    <version>1.0.0</version>
</dependency>

3.5. Implementierung der Tools

Die Tools sind unsere "Endpoints", wo das LLM später drauf zugreifen wird. Tools sind Methoden mit der @Tool-Annotation. Deren Implementierung ist einfacher als die Implementierung von REST-Endpoints, da die Endpoints nicht mit Pfaden oder HTTP-Verben, sondern mit natürlicher Sprache definiert werden.

public class McpTools{
    @Inject
    TeacherRepository teacherRepository;

    @Inject
    OfficeHourRepository officeHourRepository;

    @Tool(description = "Alle Lehrerinnen und Lehrer der HTL Leonding anzeigen")
    @Transactional
    public String getAllTeachers(){
        return teacherRepository.getAllTeachersAsString();
    }

    @Tool(description = "Sprechstunde einer Lehrerin oder eines Lehrers anzeigen")
    @Transactional
    public String getDetailsPerTeacher(
            @ToolArg(description = "Vor- oder Nachname des Lehrers") String name
    ){
        return officeHourRepository.getAllOfficeHoursByTeacherNameAsString(name);
    }

    @Tool(description = "Alle Lehrerinnen und Lehrer eines Raumes anzeigen")
    @Transactional
    public String getAllTeachersByRoom(
            @ToolArg(description = "Raum") String room
    ){
        return officeHourRepository.getTeachersByRoom(room);
    }
}

In der Klasse McpTools gibt es 3 Tools:

getAllTeachers: gibt Liste aller Lehrerinnen und Lehrer der HTL Leonding als String zurück
getDetailsPerTeacher: gibt die Sprechstunden-Daten einer einzelnen Lehrkraft als String zurück
getAllTeachersByRoom: gibt alle Lehrkräfte aus einem Raum als String zurück

@Tool(description = "…") ist dabei die Beschreibung des Tools als Fließtext. Das LLM vergleicht den vom User eingegebenen Prompt mit allen Beschreibungen und wählt jenes Tool, wo die Beschreibung mit dem Prompt zusammenpasst.

@ToolArg(description = "…") ist dabei ein Parameter, welcher vom LLM aus dem Prompt des Users extrahiert wird und in der Methode verwendet werden kann.

3.6. Claude AI mit MCP-Server verbinden (STDIO)

3.6.1. Packaging als Uber-JAR

Dafür wird application.properties um folgenden Eintrag erweitert:

quarkus.package.jar.type=uber-jar

und folgender Befehl ausgeführt:

mvn clean package

Pfad zum Uber-JAR notieren!

3.6.2. Claude-Konfigurationsdatei

Claude Desktop: Hamburger-Menu > File > Settings
Settings: Developer > Edit Config

Der File-Explorer öffnet sich und markiert die Konfigurationsdatei claude_desktop_config.json. Diese um folgende Einträge erweitern:

claude_desktop_config.json

{
  "mcpServers": {
    "quarkus-officehours-mcp": {
      "command": "java",
      "args": [
        "-jar",
        "<path-to-jar>/officehours-mcp-1.0-SNAPSHOT-runner.jar"
      ]
    }
  }
}

Beim Öffnen von Claude Desktop wird nun die JAR gestartet und der MCP-Client hängt sich in die STDIO-Console. Zusätzliche Dienste wie die Datenbank müssen extra gestartet werden, deshalb ist diese Art der Kommunikation (STDIO) eher zum Entwickeln gedacht.

3.7. Claude AI mit MCP-Server verbinden (SSE)

Voraussetzung ist ein über HTTP(S) erreichbarer Quarkus-MCP-Server.

3.7.1. Claude-Konfigurationsdatei

Claude Desktop: Hamburger-Menu > File > Settings
Settings: Developer > Edit Config

Der File-Explorer öffnet sich und markiert die Konfigurationsdatei claude_desktop_config.json. Diese um folgende Einträge erweitern:

claude_desktop_config.json

{
  "mcpServers": {
    "quarkus-officehours-mcp": {
      "command": "npx", (1)
      "args": [
        "mcp-remote", (2)
        "http://localhost:8080/mcp/sse" (3)
      ]
    }
  }
}

1	`npx` ist ein Tool, um Befehle eines npm-Packages direkt auszuführen, ohne dass das npm-Package initialisiert werden muss.
2	`mcp-remote` ist ein npm-Package, welches erlaubt, MCP-Protokolle über SSE laufen zu lassen.
3	Die Adresse des MCP-Servers muss angegeben werden. Der Pfad ist standardmäßig `/mcp/sse`.

Bei Linux wird trotz Beenden von Claude Desktop manchmal der npx-Prozess nicht beendet und die MCP-Schnittstelle blockiert, deswegen ist ein manuelles Beenden notwendig. Dies geschieht mit:

sudo lsof -i :3334
kill -9 <pid>

3.8. Wissen benutzen

Das Hammer-Symbol unter der Prompt-Eingabe in Claude Desktop öffnet ein Popup, wo alle verfügbaren Tools angezeigt werden.

Das Prompten kann nun losgehen :-)

Welcher Lehrkräfte arbeiten an der HTL Leonding?

Wann hat Herr Thomas Stütz Sprechstunde?

Wer sitzt gemeinsam mit Herrn Thomas Stütz noch im Büro?

4. Glossar

LLM: Large Language Model
- KI-Modell, das Sprache versteht und generiert
- z.B. für Chatbots, Textübersetzungen oder Code-Vervollständigung
- Beispiele: ChatGPT, Claude, Gemini.
Anthropic
- US-amerikanisches KI-Unternehmen, 2021 von ehemaligen OpenAI-Mitarbeitern gegründet
Claude AI
- von Anthropic entwickelter KI-Chatbot