Quickstart

Keel/MCP Framework ofrece dos formas de empezar a desarrollar un nuevo MCP Server, según el nivel de personalización requerido:

🚀 MCP Keel/Installer - JAR: genera rápidamente un nuevo MCP Server/scaffolding a partir de la arquitectura estándar de Keel, sin necesidad de clonar ni compilar el código fuente del framework. Recomendado
🏗️ MCP Keel/Framework - Codigo fuente: permite clonar el código fuente de Keel/framework MCP, estudiar la arquitectura y adaptar o extender sus módulos según las necesidades específicas de tu proyecto. Uso Avanzado

Opción A — Generar un MCP Server mediante el Installer JAR

Esta es la opción recomendada para equipos de desarrollo que quieren usar la arquitectura estándar de Keel y empezar rápidamente a implementar las capacidades funcionales del MCP Server.

El instalador keel-mcp-archetype-installer-X.X.X.jar agrupa los componentes necesarios para generar automáticamente el scaffolding inicial del proyecto.

(1-2) Obtener el Installer JAR

Descarga el artefacto:

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

(2-2) Generar el scaffolding

Ejecuta el instalador, indicando el nombre, versión y dominio del nuevo MCP Server:

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

Por ejemplo:

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

Parámetro	Descripción
`mcpName`	Nombre del proyecto MCP que se generará.
`mcpVersion`	Versión inicial del proyecto generado.
`projectDomain`	Dominio o área funcional a la que pertenece el MCP Server.
`groupId`	groupId Maven del proyecto generado (tu propio namespace en dominio inverso).

El instalador genera automáticamente la estructura base del MCP Server, incluyendo los módulos _boot, _mcp y _model, junto con la configuración necesaria para empezar a desarrollar.

El Installer JAR está diseñado como un mecanismo de scaffolding. Su objetivo es ofrecer una forma rápida y estandarizada de iniciar nuevos proyectos de MCP Server basados en la arquitectura Keel.

Opción B — Clonar y adaptar el Framework Keel

Esta opción está pensada para arquitectos y equipos que necesitan entender, personalizar o extender la arquitectura Keel.

El código fuente del framework da acceso directo a los módulos que componen la arquitectura, incluyendo:

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

(1-2) Clonar / compilar el framework

# Clonar
git clone https://github.com/Keel-Framework/keel-mcp-java.git
# Ir al framework y compilar sus modulos:
cd keel-mcp-java/
# Compilar:
mvn clean install

(2-2) Generar el scaffolding

Para generar un nuevo scaffolding Keel para un MCP Server, primero se necesita el siguiente artefacto: keel-mcp-archetype-installer-X.X.X.jar

# Ejecutar el instalador 
java -jar keel-mcp-archetype-installer-1.0.0.jar <mcpName> <mcpVersion> <projectDomain> <groupId>

Por ejemplo:

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

Resultado de la generación del scaffolding

Una vez ejecutado el Installer de Keel, el proceso de generación finaliza y crea el nuevo MCP Server en el directorio indicado.

La siguiente salida muestra un ejemplo de ejecución del Maven Archetype, incluyendo los parámetros usados durante la generación y la confirmación de la creación del proyecto con 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: \mcp-petstore-sample
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time:  1.554 s
[INFO] ------------------------------------------------------------------------

El resultado es un nuevo proyecto de MCP Server basado en la arquitectura Keel, listo para continuar con la configuración y el desarrollo de sus capacidades MCP.

Ejecución del MCP Server

Independientemente de la opción usada para obtener el scaffolding, una vez generado el proyecto:

# Navega al directorio raíz del proyecto
cd <directory-root-install-project-mcp>

# Compila el proyecto
mvn clean install

Ejemplo práctico:

# Navega al directorio raíz del proyecto
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] ------------------------------------------------------------------------

# Navega al modulo de Spring Boot
cd <project-boot>
# Ejecuta la aplicacion
mvn spring-boot:run
# Navega al modulo de Spring Boot
\mcp-petstore-sample\mcp-petstore-sample-boot>
# Ejecuta la aplicacion
mvn spring-boot:run

Ejemplo práctico:

[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)

Resumen del proceso de arranque

La aplicación debe arrancar correctamente y mostrar en los logs la inicialización exitosa del Spring Boot Application Context y de los componentes base de Keel/MCP, sin errores relacionados con la configuración, la resolución de dependencias o la inicialización de los módulos del framework.

A modo de referencia, durante el arranque deberían verse las siguientes evidencias:

Comprobación	Evidencia esperada
✅ Perfil local de Spring	`profile is active: "local"`
✅ JKS / SSL Truststore	`SSL TRUSTSTORE loading path=classpath:user-truststore.jks type=JKS`
✅ Instancia de Tomcat	`Tomcat initialized with port 8080 (http)`
✅ Inicialización del REST Client	`REST CLIENT FACTORY initialized socketTimeout=60000ms connectTimeout=60000ms requestTimeout=60000ms maxTotal=200 maxPerRoute=20 keepAlive=10000ms ssl=enabled`
✅ Actuator	`Exposing 3 endpoints beneath base path '/actuator'`
✅ Capacidades MCP	`Enable tools capabilities, notification: true`
✅ Registro de Tools	`Registered tools: 1`
✅ Aplicación iniciada	`Started Application in 12.536 seconds`

El endpoint del servidor MCP está disponible en http://localhost:8080/mcp

Métodos e interacción con el MCP Server

Un servidor MCP basado en Keel proporciona los mecanismos necesarios para interactuar con las capacidades estándar del protocolo MCP, desde la inicialización de la conexión hasta el descubrimiento de Tools, Resources y Prompts.

Esta sección describe los principales métodos MCP, su propósito y los ejemplos de invocación correspondientes.

Método MCP	Propósito	Invocación
❤️ `health`	Comprobar la disponibilidad y el estado del MCP Server.	`GET /health`
🚀 `initialize`	Inicializar la sesión MCP y negociar las capacidades soportadas por cliente y servidor.	`POST /mcp`
🧩 `tools/list`	Obtener la lista de Tools disponibles en el MCP Server.	`POST /mcp`
⚙️ `tools/call`	Invocar una Tool concreta en el MCP Server.	`POST /mcp`
📚 `resources/list`	Obtener la lista de Resources disponibles.	`POST /mcp`
📖 `resources/read`	Leer el contenido de un Resource concreto.	`POST /mcp`
💬 `prompts/list`	Obtener la lista de Prompts disponibles.	`POST /mcp`
📝 `prompts/get`	Obtener un Prompt concreto y sus mensajes asociados.	`POST /mcp`
---

Health / Info

Propósito: comprobar el estado y la disponibilidad del MCP Server, proporcionando información básica sobre la aplicación y su ejecución.

Método	Endpoint
`GET`	`http://localhost:8080/actuator/health`
`GET`	`http://localhost:8080/actuator/info`

`initialize`

Propósito: inicializar la sesión MCP, permitiendo que cliente y servidor intercambien información sobre sus capacidades, versión del protocolo e identificación antes de que comience la interacción.

Método	Endpoint
`POST`	`http://localhost:8080/mcp`

Cabeceras:

Cabecera	Valor
`Content-Type`	`application/json`
`Accept`	`text/event-stream, application/json`
`Authorization`	`Bearer <jwt>`

Cuerpo de la petición:

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

Header de la respuesta:

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

Cuerpo de la respuesta:

{
  "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`

Propósito: obtener la lista de Tools disponibles en el MCP Server, incluyendo su nombre, descripción y esquema de entrada, para que el cliente sepa qué capacidades puede invocar.

Método	Endpoint
`POST`	`http://localhost:8080/mcp`

Cabeceras:

Cabecera	Valor
`Content-Type`	`application/json`
`Accept`	`text/event-stream, application/json`
`Authorization`	`Bearer <jwt>`
`Mcp-Session-Id`	`<session-id>`

Cuerpo de la petición:

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

Cuerpo de la respuesta:

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

`tools/call`

Propósito: invocar una Tool concreta en el MCP Server, proporcionando los parámetros de entrada necesarios para ejecutar la operación solicitada.

Método	Endpoint
`POST`	`http://localhost:8080/mcp`

Cabeceras:

Cabecera	Valor
`Content-Type`	`application/json`
`Accept`	`text/event-stream, application/json`
`Authorization`	`Bearer <jwt>`
`Mcp-Session-Id`	`<session-id>`

Cuerpo de la petición:

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

Cuerpo de la respuesta:

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

`resources/list`

Propósito: obtener la lista de Resources disponibles en el MCP Server, para que el cliente pueda descubrir los recursos que puede leer.

Método	Endpoint
`POST`	`http://localhost:8080/mcp`

Cabeceras:

Cabecera	Valor
`Content-Type`	`application/json`
`Accept`	`text/event-stream, application/json`
`Authorization`	`Bearer <jwt>`
`Mcp-Session-Id`	`<session-id>`

Cuerpo de la petición:

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

Cuerpo de la respuesta:

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

`prompts/list`

Propósito: obtener la lista de Prompts disponibles en el MCP Server, para que el cliente pueda descubrir los prompts que puede usar.

Método	Endpoint
`POST`	`http://localhost:8080/mcp`

Cabeceras:

Cabecera	Valor
`Content-Type`	`application/json`
`Accept`	`text/event-stream, application/json`
`Authorization`	`Bearer <jwt>`
`Mcp-Session-Id`	`<session-id>`

Cuerpo de la petición:

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

Cuerpo de la respuesta:

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