KeelFramework

Keel Framework / Keel Framework/MCP / Java

Java 25 · Spring Boot 4 · Spring AI · MCP

Keel/MCP Java

A reference architecture for building MCP servers in Java.

Keel is the keel on which you build your MCP server: reusable technical modules, clear conventions and a Maven Archetype that generates a project ready to develop Tools, Resources and Prompts.

Get started in five minutes View on GitHub
mcp-architecture-framework Parent / BOM

Common

  • common-jwt
  • common-exceptions

Adapters

  • adapter-auth-idp
  • adapter-cache-caffeine
  • adapter-rest-client

Transport

  • transport-auth-service
  • transport-session-service
  • transport-streamable-service
  • transport-cors-service

Observability

  • observability-logging
Maven Archetype <project>-boot · -mcp · -model

Two ways of working with Keel/MCP Java

Choose depending on how much you need to adapt the architecture. In both cases the result is an MCP Server that follows the Keel conventions.

Mode 1 · Recommended

Generate the standard scaffolding

The Installer JAR creates an MCP Server with all the modules of the Keel architecture already integrated: boot, mcp, model, YAML configuration and deployment files. No need to clone or build the framework.

$ java -jar keel-mcp-archetype-installer.jar name-project version domain groupId
$ java -jar keel-mcp-archetype-installer-1.0.0.jar mcp-petstore-sample 1.0.0 petstore io.keelframework.sample
Get started in five minutes Download the installer

Mode 2 · For architects

Adapt the Keel/MCP architecture to your needs

Clone the framework, study the common-*, adapter-*, transport-* and observability-* modules, and adapt or extend the base architecture to your model before generating the scaffolding.



$ git clone https://github.com/Keel-Framework/keel-mcp-java.git
Guide to adapting the architecture Architecture on GitHub

From zero to MCP server

  1. Generate the scaffolding

    The Installer JAR creates the project with the boot, mcp and model modules, the YAML configuration and the deployment pipeline files.

    Quickstart

  2. Build and run

    mvn clean install and mvn spring-boot:run. The MCP endpoint is available at /mcp with authentication, session management and observability already configured.

    Running the server

  3. Develop your capabilities

    Implement Tools, Resources and Prompts with the Spring AI annotations, following the Keel conventions. The cross-cutting concerns are already solved.

    Developer guide

What Keel solves for you

Authentication and security

JWT validation against an OIDC provider (Keycloak / Red Hat SSO) with JWKS and token introspection.

MCP session management

Full Mcp-Session-Id lifecycle: creation, validation and expiration.

Streamable HTTP transport

Communication endpoint for MCP hosts according to the protocol specification.

CORS

Ready-made configuration for browser-based MCP clients.

Local cache

Caffeine with TTL and maximum size, aligned with the protocol's session state.

REST client

Preconfigured HTTP client (TLS, timeouts, pool) to call backends from Tools.

Observability

Structured JSON logs with technical, functional and security events.

Version management

A Maven BOM centralizes dependencies, plugins and compatibility across the whole stack.

Built with its own architecture


Keel MCP — Reference Implementation Live reference

Keel MCP — Reference Implementation provides a complete technical implementation of the Keel MCP Architecture, designed as a reference for developers and architects building MCP servers with Spring AI. This repository materializes the architectural principles, layers, components and conventions defined by Keel MCP in a working implementation.

  • Tools
  • Prompts
  • Resources
  • JWT auth
  • Zero-setup demo backends