Back to search
spring-ai-mcp-server-tutorial
MCP serverGitHub
Begleitcode zum Tutorial: MCP-Server mit Java, Spring Boot und Spring AI
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/samo0892--spring-ai-mcp-server-tutorial)HTML
<a href="/listings/samo0892--spring-ai-mcp-server-tutorial"><img src="/api/listings/samo0892--spring-ai-mcp-server-tutorial/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 163 lines
- # Spring AI MCP Server Tutorial
- Lauffähiger Begleitcode zum Artikel
- **[MCP-Server mit Java und Spring Boot bauen: Tutorial mit Spring AI 2.1](https://www.sam-codes.com/blog/mcp-server-java-spring-boot)**.
- Die Anwendung ist ein MCP-Server für ein fiktives Bestellsystem. Sie stellt über das
- Model Context Protocol bereit:
- - zwei Tools: `find_order` (Bestellung nachschlagen) und `check_refund` (Erstattung prüfen),
- - eine Resource: die Rückgaberichtlinie unter `policy://rueckgabe`,
- - einen Prompt: `reklamation_beantworten`.
- Der Server ist als OAuth Resource Server abgesichert. Die Kundennummer kommt aus dem
- geprüften Token und gelangt über den `McpTransportContext` ins Tool, nie über die
- Tool-Argumente des Modells.
- ```text
- MCP-Client ──HTTP + Bearer Token──▶ Spring Security (OAuth Resource Server)
- │ Kundennummer → McpTransportContext
- ▼
- /mcp (Streamable HTTP oder MCP 2026-07-28)
- │
- OrderTools / SupportResources
- │
- OrderService (prüft, wem die Bestellung gehört)
- ```
- ## Projektstruktur
- | Datei | Abschnitt im Artikel |
- | --- | --- |
- | [`pom.xml`](pom.xml), [`application.yaml`](src/main/resources/application.yaml) | [Das Projekt aufsetzen](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#das-projekt-aufsetzen) |
- | [`OrderTools`](src/main/java/de/samcodes/bestellungen/OrderTools.java) | [Tools mit @McpTool definieren](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#tools-mit-mcptool-definieren) |
- | [`SupportResources`](src/main/java/de/samcodes/bestellungen/SupportResources.java) | [Resources und Prompts](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#resources-und-prompts) |
- | [`McpSecurityConfig`](src/main/java/de/samcodes/bestellungen/McpSecurityConfig.java), [`OrderService`](src/main/java/de/samcodes/bestellungen/OrderService.java) | [Den MCP-Server absichern](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#den-mcp-server-absichern) |
- | [`OrderToolsIntegrationTest`](src/test/java/de/samcodes/bestellungen/OrderToolsIntegrationTest.java), [`TestJwtConfig`](src/test/java/de/samcodes/bestellungen/TestJwtConfig.java) | [Den Server mit dem MCP-Client testen](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#den-server-mit-dem-mcp-client-testen) |
- | [`ModernProtocolTest`](src/test/java/de/samcodes/bestellungen/ModernProtocolTest.java) | [MCP 2026-07-28 aktivieren](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#mcp-2026-07-28-aktivieren) |
- Der Artikel zeigt `OrderTools` zuerst ohne Anmeldung und erweitert die Tools dann um den
- `McpTransportContext`. Im Repository steht der abgesicherte Endstand.
- ## Voraussetzungen
- - Java 25 (z. B. Eclipse Temurin). Maven musst du nicht installieren, das Projekt bringt
- den Maven Wrapper (`./mvnw`) mit.
- - Kein API-Key: Der MCP-Server ruft selbst kein Sprachmodell auf, das tut der Client.
- - Zum Aufrufen der Tools ein Authorization Server, der JWTs ausstellt, etwa Keycloak.
- Für die Tests ist er nicht nötig.
- ## Tests
- ```bash
- ./mvnw verify
- ```
- Die Tests starten den Server auf einem zufälligen Port. Den Authorization Server ersetzt
- ein Test-`JwtDecoder` ([`TestJwtConfig`](src/test/java/de/samcodes/bestellungen/TestJwtConfig.java)),
- der den Token-Wert als Kundennummer übernimmt. Es wird kein Sprachmodell aufgerufen.
- [`OrderToolsIntegrationTest`](src/test/java/de/samcodes/bestellungen/OrderToolsIntegrationTest.java)
- nutzt den MCP-Client des Java SDK über Streamable HTTP und prüft:
- - ein Kunde sieht seine eigene Bestellung, das Ergebnis enthält `structuredContent`,
- - ein anderer Kunde bekommt für dieselbe Bestellung „nicht gefunden“,
- - der Kontext-Parameter taucht nicht im Tool-Schema auf, `destructiveHint` ist `false` und es gibt ein Ausgabeschema,
- - ohne Token antwortet der Server mit `401` und einem `WWW-Authenticate`-Header mit `resource_metadata`,
- - ein Request mit fremdem `Origin`-Header wird mit `403` abgelehnt.
- [`ModernProtocolTest`](src/test/java/de/samcodes/bestellungen/ModernProtocolTest.java)
- startet denselben Server mit `spring.ai.mcp.server.protocol=MODERN` (MCP-Revision 2026-07-28)
- und schickt die Requests mit dem `HttpClient` des JDK: Tool-Aufruf ohne Handshake, fremde
- Bestellung, und `initialize` wird abgelehnt.
- ## Server starten
- ```bash
- ./mvnw spring-boot:run
- ```
- Der Server lauscht auf `http://localhost:8080/mcp` und spricht Streamable HTTP
- (`protocol: STREAMABLE` in der [`application.yaml`](src/main/resources/application.yaml)).
- Ohne Token antwortet er mit `401` und verweist auf seine Metadaten:
- ```bash
- curl -i -X POST http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{}'
- ```
- ```text
- HTTP/1.1 401
- WWW-Authenticate: Bearer resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource"
- ```
- ```bash
- curl http://localhost:8080/.well-known/oauth-protected-resource
- ```
- ```json
- {
- "resource": "http://localhost:8080",
- "bearer_methods_supported": ["header"],
- "tls_client_certificate_bound_access_tokens": false,
- "authorization_servers": ["https://auth.example.com/realms/shop"],
- "scopes_supported": ["bestellungen.read"],
- "resource_name": "Bestellungen MCP-Server"
- }
- ```
- Um die Tools mit echten Tokens aufzurufen, trägst du deinen Authorization Server ein,
- zum Beispiel über Umgebungsvariablen:
- ```bash
- export SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=https://dein-idp.example.com/realms/shop
- export SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_AUDIENCES=http://localhost:8080
- ./mvnw spring-boot:run
- ```
- Das Token braucht den Scope `bestellungen.read`. Der Claim `sub` ist die Kundennummer;
- die Beispieldaten in [`OrderService`](src/main/java/de/samcodes/bestellungen/OrderService.java)
- gehören `kunde-1` und `kunde-2`.
- ### MCP 2026-07-28 statt Streamable HTTP
- ```bash
- SPRING_AI_MCP_SERVER_PROTOCOL=MODERN ./mvnw spring-boot:run
- ```
- Der Server lehnt dann den `initialize`-Handshake ab und erwartet die Header
- `MCP-Protocol-Version`, `Mcp-Method` und `Mcp-Name` sowie Protokollversion und
- Client-Fähigkeiten in `params._meta`. Ein Beispiel-Request steht im
- [Artikel](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#mcp-2026-07-28-aktivieren)
- und in [`ModernProtocolTest`](src/test/java/de/samcodes/bestellungen/ModernProtocolTest.java).
- ## Ohne lokal installiertes Java
- Build und Tests laufen auch komplett im Container, etwa mit Podman:
- ```bash
- podman run --rm --security-opt label=disable -v "$PWD":/app -v mcp-m2:/root/.m2 -w /app docker.io/library/eclipse-temurin:25-jdk ./mvnw -B verify
- ```
- `--security-opt label=disable` ist nötig, weil SELinux in der Podman Machine sonst den
- Zugriff auf das Maven-Cache-Volume `mcp-m2` aus einem zweiten Container blockiert
- (`Permission denied` beim Start von Maven). Den Server startest du im Container genauso,
- mit `-p 8080:8080` und `./mvnw spring-boot:run` statt `./mvnw -B verify`.
- ## Getestet mit
- | Komponente | Version |
- | --- | --- |
- | Java | Eclipse Temurin 25.0.4.1 und 25.0.5.1 |
- | Spring Boot | 4.2.0 |
- | Spring AI | 2.1.0 |
- | MCP Java SDK | 2.2.0 (über Spring AI) |
- | Spring Security | 7.2.0 (über Spring Boot) |
- | Maven (Wrapper) | 3.9.16 |
- | Container-Runtime | Podman 6.0.2 (macOS) |
- Nicht getestet: der Server gegen Claude Code oder andere MCP-Clients und gegen einen echten
- Authorization Server.
- ## Lizenz
- [MIT](LICENSE) © Samed Baldede
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.