Skip to content
Back to search

spring-ai-mcp-server-tutorial

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/samo0892--spring-ai-mcp-server-tutorial/badge.svg)](/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
  1. # Spring AI MCP Server Tutorial
  2. Lauffähiger Begleitcode zum Artikel
  3. **[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)**.
  4. Die Anwendung ist ein MCP-Server für ein fiktives Bestellsystem. Sie stellt über das
  5. Model Context Protocol bereit:
  6. - zwei Tools: `find_order` (Bestellung nachschlagen) und `check_refund` (Erstattung prüfen),
  7. - eine Resource: die Rückgaberichtlinie unter `policy://rueckgabe`,
  8. - einen Prompt: `reklamation_beantworten`.
  9. Der Server ist als OAuth Resource Server abgesichert. Die Kundennummer kommt aus dem
  10. geprüften Token und gelangt über den `McpTransportContext` ins Tool, nie über die
  11. Tool-Argumente des Modells.
  12. ```text
  13. MCP-Client ──HTTP + Bearer Token──▶ Spring Security (OAuth Resource Server)
  14. │ Kundennummer → McpTransportContext
  15. ▼
  16. /mcp (Streamable HTTP oder MCP 2026-07-28)
  17. │
  18. OrderTools / SupportResources
  19. │
  20. OrderService (prüft, wem die Bestellung gehört)
  21. ```
  22. ## Projektstruktur
  23. | Datei | Abschnitt im Artikel |
  24. | --- | --- |
  25. | [`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) |
  26. | [`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) |
  27. | [`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) |
  28. | [`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) |
  29. | [`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) |
  30. | [`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) |
  31. Der Artikel zeigt `OrderTools` zuerst ohne Anmeldung und erweitert die Tools dann um den
  32. `McpTransportContext`. Im Repository steht der abgesicherte Endstand.
  33. ## Voraussetzungen
  34. - Java 25 (z. B. Eclipse Temurin). Maven musst du nicht installieren, das Projekt bringt
  35. den Maven Wrapper (`./mvnw`) mit.
  36. - Kein API-Key: Der MCP-Server ruft selbst kein Sprachmodell auf, das tut der Client.
  37. - Zum Aufrufen der Tools ein Authorization Server, der JWTs ausstellt, etwa Keycloak.
  38. Für die Tests ist er nicht nötig.
  39. ## Tests
  40. ```bash
  41. ./mvnw verify
  42. ```
  43. Die Tests starten den Server auf einem zufälligen Port. Den Authorization Server ersetzt
  44. ein Test-`JwtDecoder` ([`TestJwtConfig`](src/test/java/de/samcodes/bestellungen/TestJwtConfig.java)),
  45. der den Token-Wert als Kundennummer übernimmt. Es wird kein Sprachmodell aufgerufen.
  46. [`OrderToolsIntegrationTest`](src/test/java/de/samcodes/bestellungen/OrderToolsIntegrationTest.java)
  47. nutzt den MCP-Client des Java SDK über Streamable HTTP und prüft:
  48. - ein Kunde sieht seine eigene Bestellung, das Ergebnis enthält `structuredContent`,
  49. - ein anderer Kunde bekommt für dieselbe Bestellung „nicht gefunden“,
  50. - der Kontext-Parameter taucht nicht im Tool-Schema auf, `destructiveHint` ist `false` und es gibt ein Ausgabeschema,
  51. - ohne Token antwortet der Server mit `401` und einem `WWW-Authenticate`-Header mit `resource_metadata`,
  52. - ein Request mit fremdem `Origin`-Header wird mit `403` abgelehnt.
  53. [`ModernProtocolTest`](src/test/java/de/samcodes/bestellungen/ModernProtocolTest.java)
  54. startet denselben Server mit `spring.ai.mcp.server.protocol=MODERN` (MCP-Revision 2026-07-28)
  55. und schickt die Requests mit dem `HttpClient` des JDK: Tool-Aufruf ohne Handshake, fremde
  56. Bestellung, und `initialize` wird abgelehnt.
  57. ## Server starten
  58. ```bash
  59. ./mvnw spring-boot:run
  60. ```
  61. Der Server lauscht auf `http://localhost:8080/mcp` und spricht Streamable HTTP
  62. (`protocol: STREAMABLE` in der [`application.yaml`](src/main/resources/application.yaml)).
  63. Ohne Token antwortet er mit `401` und verweist auf seine Metadaten:
  64. ```bash
  65. curl -i -X POST http://localhost:8080/mcp -H 'Content-Type: application/json' -d '{}'
  66. ```
  67. ```text
  68. HTTP/1.1 401
  69. WWW-Authenticate: Bearer resource_metadata="http://localhost:8080/.well-known/oauth-protected-resource"
  70. ```
  71. ```bash
  72. curl http://localhost:8080/.well-known/oauth-protected-resource
  73. ```
  74. ```json
  75. {
  76. "resource": "http://localhost:8080",
  77. "bearer_methods_supported": ["header"],
  78. "tls_client_certificate_bound_access_tokens": false,
  79. "authorization_servers": ["https://auth.example.com/realms/shop"],
  80. "scopes_supported": ["bestellungen.read"],
  81. "resource_name": "Bestellungen MCP-Server"
  82. }
  83. ```
  84. Um die Tools mit echten Tokens aufzurufen, trägst du deinen Authorization Server ein,
  85. zum Beispiel über Umgebungsvariablen:
  86. ```bash
  87. export SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_ISSUER_URI=https://dein-idp.example.com/realms/shop
  88. export SPRING_SECURITY_OAUTH2_RESOURCESERVER_JWT_AUDIENCES=http://localhost:8080
  89. ./mvnw spring-boot:run
  90. ```
  91. Das Token braucht den Scope `bestellungen.read`. Der Claim `sub` ist die Kundennummer;
  92. die Beispieldaten in [`OrderService`](src/main/java/de/samcodes/bestellungen/OrderService.java)
  93. gehören `kunde-1` und `kunde-2`.
  94. ### MCP 2026-07-28 statt Streamable HTTP
  95. ```bash
  96. SPRING_AI_MCP_SERVER_PROTOCOL=MODERN ./mvnw spring-boot:run
  97. ```
  98. Der Server lehnt dann den `initialize`-Handshake ab und erwartet die Header
  99. `MCP-Protocol-Version`, `Mcp-Method` und `Mcp-Name` sowie Protokollversion und
  100. Client-Fähigkeiten in `params._meta`. Ein Beispiel-Request steht im
  101. [Artikel](https://www.sam-codes.com/blog/mcp-server-java-spring-boot#mcp-2026-07-28-aktivieren)
  102. und in [`ModernProtocolTest`](src/test/java/de/samcodes/bestellungen/ModernProtocolTest.java).
  103. ## Ohne lokal installiertes Java
  104. Build und Tests laufen auch komplett im Container, etwa mit Podman:
  105. ```bash
  106. 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
  107. ```
  108. `--security-opt label=disable` ist nötig, weil SELinux in der Podman Machine sonst den
  109. Zugriff auf das Maven-Cache-Volume `mcp-m2` aus einem zweiten Container blockiert
  110. (`Permission denied` beim Start von Maven). Den Server startest du im Container genauso,
  111. mit `-p 8080:8080` und `./mvnw spring-boot:run` statt `./mvnw -B verify`.
  112. ## Getestet mit
  113. | Komponente | Version |
  114. | --- | --- |
  115. | Java | Eclipse Temurin 25.0.4.1 und 25.0.5.1 |
  116. | Spring Boot | 4.2.0 |
  117. | Spring AI | 2.1.0 |
  118. | MCP Java SDK | 2.2.0 (über Spring AI) |
  119. | Spring Security | 7.2.0 (über Spring Boot) |
  120. | Maven (Wrapper) | 3.9.16 |
  121. | Container-Runtime | Podman 6.0.2 (macOS) |
  122. Nicht getestet: der Server gegen Claude Code oder andere MCP-Clients und gegen einen echten
  123. Authorization Server.
  124. ## Lizenz
  125. [MIT](LICENSE) © Samed Baldede

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.