Keel Framework / Keel/MCP / Java

Quickstart

• 🚀 MCP Keel/Installer - JAR: quickly generates a new MCP Server/Scaffolding from the standard Keel architecture, with no need to clone or build the framework's source code.Recommended
• 🏗️ MCP Keel/Framework - Source: lets you clone the Keel/framework MCP source code, study the architecture and adapt or extend its modules according to the specific needs of your project. Advanced Use

Option A — Generate an MCP Server with the Installer JAR

This is the recommended option for development teams that want to use the standard Keel architecture and quickly start implementing the functional capabilities of the MCP Server.

The keel-mcp-archetype-installer-X.X.X.jar installer bundles the components needed to automatically generate the project's initial scaffolding.

(1-2) Get the Installer JAR

Download the artifact:

keel-mcp-archetype-installer-X.X.X.jar

(2-2) Generate the scaffolding

Run the installer, providing the name, version and domain of the new MCP Server:

java -jar keel-mcp-archetype-installer-X.X.X.jar <mcpName> <mcpVersion> <projectDomain> <groupId>

For example:

$ java -jar keel-mcp-archetype-installer-1.0.0.jar petstore-sample 1.0.0 petstore io.keelframework.sample

The installer automatically generates the base structure of the MCP Server, including the _boot, _mcp and _model modules and the configuration needed to start developing.

Option B — Clone and adapt the Keel Framework

This option is aimed at architects and teams that need to understand, customize or extend the Keel architecture.

The framework's source code gives direct access to the modules that make up the architecture, including:

• common-*
• adapter-*
• transport-*
• observability-*

(1-2) Clone / build the framework

# Clone
git clone https://github.com/Keel-Framework/keel-mcp-java.git
# Go to the framework and build its modules:
cd keel-mcp-java/
# Build:
mvn clean install

(2-2) Generate the scaffolding

To generate a new Keel scaffolding for an MCP Server, the following artifact is required first: keel-mcp-archetype-installer-X.X.X.jar

# Run the installer
java -jar keel-mcp-archetype-installer-1.0.0.jar <mcpName> <mcpVersion> <projectDomain> <groupId>

For example:

java -jar keel-mcp-archetype-installer-1.0.0.jar  mcp-petstore-sample 1.0.0 petstore io.keelframework.samples

Result of the scaffolding generation

Once the Keel Installer has run, the generation process completes and creates the new MCP Server in the specified directory.

The following output shows an example run of the Maven Archetype, including the parameters used during generation and the confirmation of project creation with BUILD SUCCESS.

[INFO] --- maven-archetype-plugin:3.4.1:generate (default-cli) @ standalone-pom ---
[INFO] Generating project in Batch mode
[INFO] Archetype repository not defined. Using the one from [io.keelframework.mcp:keel-mcp-archetype:1.0.0] found in catalog local
[INFO] ----------------------------------------------------------------------------
[INFO] Using following parameters for creating project from Archetype: keel-mcp-archetype:1.0.0
[INFO] ----------------------------------------------------------------------------
[INFO] Parameter: groupId, Value: io.keelframework.samples
[INFO] Parameter: artifactId, Value: mcp-petstore-sample
[INFO] Parameter: version, Value: 1.0.0
[INFO] Parameter: package, Value: io.keelframework.samples
[INFO] Parameter: packageInPathFormat, Value: io/keelframework/samples
[INFO] Parameter: package, Value: io.keelframework.samples
[INFO] Parameter: micro, Value: mcppetstoresample
[INFO] Parameter: domain, Value: petstore
[INFO] Parameter: domainName, Value: petstore
[INFO] Parameter: groupId, Value: io.keelframework.samples
[INFO] Parameter: artifactId, Value: mcp-petstore-sample
[INFO] Parameter: transport, Value: mvc
[INFO] Parameter: version, Value: 1.0.0
[INFO] Parameter: microName, Value: mcp-petstore-sample
[INFO] Parameter: architectureVersion, Value: 1.0.0
[INFO] Project created from Archetype in dir: \Keel-Framework\keel-mcp-sample\mcp-petstore-sample
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.554 s
[INFO] ------------------------------------------------------------------------

The result is a new MCP Server project based on the Keel architecture, ready to continue with the configuration and development of its MCP capabilities.

Running the MCP Server

Regardless of the option used to obtain the scaffolding, once the project has been generated:

# Navigate to the project root directory
cd <directory-root-install-project-mcp>

# Build the project
mvn clean install

Practical example:

# Navigate to the project root directory
C:\mcp-petstore-sample>
# Build the project
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary for mcp-petstore-sample 1.0.0:
[INFO]
[INFO] mcp-petstore-sample ................................ SUCCESS [  1.496 s]
[INFO] mcp-petstore-sample-model .......................... SUCCESS [  6.400 s]
[INFO] mcp-petstore-sample-mcp ............................ SUCCESS [  6.397 s]
[INFO] mcp-petstore-sample-boot ........................... SUCCESS [ 11.801 s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  26.490 s
[INFO] ------------------------------------------------------------------------

# Navigate to the Spring Boot module
cd <project-boot>
# Run the application
mvn spring-boot:run
# Navigate to the Spring Boot module
\mcp-petstore-sample\mcp-petstore-sample-boot>
# Run the application
mvn spring-boot:run

Practical example:

[INFO] Attaching agents: []

  .   ____          _            __ _ _
 /\\ / ___'_ __ _ _(_)_ __  __ _ \ \ \ \
( ( )\___ | '_ | '_| | '_ \/ _` | \ \ \ \
 \\/  ___)| |_)| | | | | || (_| |  ) ) ) )
  '  |____| .__|_| |_|_| |_\__, | / / / /
 =========|_|==============|___/=/_/_/_/

 :: Spring Boot ::                (v4.0.6)
2026-09-21 19:35:53.756 INFO  [main] org.springframework.boot.tomcat.TomcatWebServer - Tomcat initialized with port 8080 (http)
2026-09-21 19:35:53.771 INFO  [main] org.apache.coyote.http11.Http11NioProtocol - Initializing ProtocolHandler ["http-nio-8080"]
2026-09-21 19:35:53.773 INFO  [main] org.apache.catalina.core.StandardService - Starting service [Tomcat]
2026-09-21 19:35:53.774 INFO  [main] org.apache.catalina.core.StandardEngine - Starting Servlet engine: [Apache Tomcat/11.0.21]
2026-09-21 19:35:53.844 INFO  [main] org.springframework.boot.web.context.servlet.WebApplicationContextInitializer - Root WebApplicationContext: initialization completed in 1401 ms
2026-09-21 19:35:54.176 INFO  [main] io.keelframework.mcp.adapters.rest.client.McpRestClientFactory - REST CLIENT FACTORY initialized socketTimeout=60000ms connectTimeout=60000ms requestTimeout=60000ms maxTotal=200 maxPerRoute=20 keepAlive=10000ms ssl=disabled
2026-09-21 19:35:54.728 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Enable tools capabilities, notification: true
2026-09-21 19:35:54.797 WARN  [main] org.springframework.ai.mcp.annotation.provider.tool.SyncMcpToolProvider - No tool methods found in the provided tool objects: []
2026-09-21 19:35:54.798 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Registered tools: 1
2026-09-21 19:35:54.798 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Enable resources capabilities, notification: true
2026-09-21 19:35:54.801 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Enable resources templates capabilities, notification: true
2026-09-21 19:35:54.802 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Enable prompts capabilities, notification: true
2026-09-21 19:35:54.805 INFO  [main] org.springframework.ai.mcp.server.common.autoconfigure.McpServerAutoConfiguration - Enable completions capabilities
2026-09-21 19:35:55.015 WARN  [main] org.springframework.boot.security.autoconfigure.UserDetailsServiceAutoConfiguration -

Using generated security password: 6eb261f0-afa2-4562-a234-3425de350b66

This generated password is for development use only. Your security configuration must be updated before running your application in production.

2026-09-21 19:35:55.042 INFO  [main] org.springframework.security.config.annotation.authentication.configuration.InitializeUserDetailsBeanManagerConfigurer$InitializeUserDetailsManagerConfigurer - Global AuthenticationManager configured with UserDetailsService bean with name inMemoryUserDetailsManager
2026-09-21 19:35:55.142 INFO  [main] org.springframework.boot.actuate.endpoint.web.EndpointLinksResolver - Exposing 3 endpoints beneath base path '/actuator'
2026-09-21 19:35:55.258 INFO  [main] org.apache.coyote.http11.Http11NioProtocol - Starting ProtocolHandler ["http-nio-8080"]
2026-09-21 19:35:55.291 INFO  [main] org.springframework.boot.tomcat.TomcatWebServer - Tomcat started on port 8080 (http) with context path '/'
2026-09-21 19:35:55.304 INFO  [main] io.keelframework.samples.Application - Started Application in 3.865 seconds (process running for 4.761)

Startup process summary

The application must start correctly and show in the logs the successful initialization of the Spring Boot Application Context and of the base Keel/MCP components, with no errors related to configuration, dependency resolution or initialization of the framework modules.

As a reference, the following evidence should be visible during startup:

The MCP server endpoint is available at http://localhost:8080/mcp

Methods and interaction with the MCP Server

A Keel-based MCP server provides the mechanisms needed to interact with the standard capabilities of the MCP protocol, from connection initialization to the discovery of Tools, Resources and Prompts.

This section describes the main MCP methods, their purpose and the corresponding invocation examples.

Health / Info

Purpose: check the status and availability of the MCP Server, providing basic information about the application and its execution.

initialize

Purpose: initialize the MCP session, letting client and server exchange information about their capabilities, protocol version and identification before the interaction begins.

Headers:

Request Body:

{
  "jsonrpc": "2.0",
  "method": "initialize",
  "id": 1,
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {
      "name": "test",
      "version": "1.0"
    }
  }
}

Response Header:

mcp-session-id  : 6ad4267c-1694-4718-9ebe-828d18b7076a

Response Body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-03-26",
    "capabilities": {
      "completions": {},
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": false,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "mcp-poc",
      "version": "1.0.0"
    }
  }
}

tools/list

Purpose: get the list of Tools available on the MCP Server, including their name, description and input schema, so that the client knows which capabilities it can invoke.

Headers:

Request Body:

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 2
}

Response Body:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
    ]
  }
}

tools/call

Purpose: invoke a specific Tool on the MCP Server, providing the input parameters needed to execute the requested operation.

Headers:

Request Body:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 6,
  "params": {
    "name": "suma",
    "arguments": {
      "a": 1,
      "b": 1
    }
  }
}

Response Body:

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "id": 6,
  "params": {
    "name": "suma",
    "arguments": {
      "a": 1,
      "b": 1
    }
  }
}

resources/list

Purpose: get the list of Resources available on the MCP Server, so that the client can discover the resources it can read.

Headers:

Request Body:

{
  "jsonrpc": "2.0",
  "method": "resources/list",
  "id": 1
}

Response Body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "resources": [
    ]
  }
}

prompts/list

Purpose: get the list of Prompts available on the MCP Server, so that the client can discover the prompts it can use.

Headers:

Request Body:

{
  "jsonrpc": "2.0",
  "method": "prompts/list",
  "id": 1
}

Response Body:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "prompts": []
  }
}