Artículo

Servidor y cliente MCP con Spring AI: tools de Spring Boot para tu LLM

Qué es el Model Context Protocol y cómo exponer tools desde un servidor Spring Boot con @McpTool y consumirlas desde un cliente Spring AI 2.0, probado.

Escrito contra Spring AI 2.0.2, Spring Boot 4.1.2 y Java 21 (SDK MCP 2.1.0, que llega como dependencia). Servidor probado con un cliente MCP real; el conjunto servidor + cliente + modelo se ejecutó contra un modelo local (Ollama, gpt-oss).

Tienes un servicio con datos útiles (pedidos, tickets, inventario) y quieres que un modelo de lenguaje los consulte. Podrías escribir las tools dentro de cada aplicación que usa el modelo, pero entonces las copias en todas. El Model Context Protocol (MCP) estandariza esa conexión: un servidor MCP publica herramientas, recursos y prompts, y cualquier cliente MCP (tu app Spring AI, un IDE, un asistente de escritorio) los descubre y los usa. Aquí construimos las dos mitades.

Vídeo explicativo

Qué es MCP, en lo que importa

Es un protocolo basado en JSON-RPC. El cliente se conecta, negocia capacidades y pide la lista de herramientas, cada una con su nombre, descripción y esquema JSON de parámetros. Cuando el modelo decide usar una, el cliente la invoca en el servidor y devuelve el resultado al modelo. El transporte puede ser STDIO (el servidor es un proceso hijo), o HTTP: Streamable-HTTP, que es el recomendado, y SSE, marcado como obsoleto en Spring AI 2.0. Aquí usamos Streamable-HTTP.

El servidor

Dependencia: spring-ai-starter-mcp-server-webmvc. Configuración mínima:

server.port=8081
spring.ai.mcp.server.name=pedidos
spring.ai.mcp.server.version=0.1.0
spring.ai.mcp.server.protocol=STREAMABLE
spring.ai.mcp.server.instructions=Consulta el estado de pedidos de la tienda.

Y una clase con una herramienta. Los datos son un mapa en memoria; lo importante es la anotación:

import org.springframework.ai.mcp.annotation.McpTool;
import org.springframework.ai.mcp.annotation.McpToolParam;

@Component
class OrderTools {

    record OrderStatus(String id, String status, LocalDate estimatedDelivery) {}

    private final Map<String, OrderStatus> orders = Map.of(
            "A-100", new OrderStatus("A-100", "ENVIADO", LocalDate.of(2026, 12, 2)),
            "A-101", new OrderStatus("A-101", "PREPARANDO", LocalDate.of(2026, 12, 9)));

    @McpTool(name = "order_status", description = "Devuelve el estado y la fecha estimada de entrega de un pedido")
    OrderStatus orderStatus(@McpToolParam(description = "Identificador del pedido, por ejemplo A-100", required = true) String orderId) {
        OrderStatus order = orders.get(orderId);
        if (order == null) {
            throw new IllegalArgumentException("No existe el pedido " + orderId);
        }
        return order;
    }
}

Cuidado con el paquete. En Spring AI 2.0 las anotaciones viven en org.springframework.ai.mcp.annotation. Muchos ejemplos antiguos importan org.springaicommunity.mcp.annotation, que ya no existe con esta versión: el error es de compilación, package ... does not exist, y nos pasó.

No hace falta registrar nada más: el starter escanea los beans con @McpTool, genera el esquema JSON a partir de la firma y la descripción, y sirve el endpoint en /mcp. La description del método y de los parámetros es lo que lee el modelo para decidir cuándo y cómo usar la herramienta: trátala como parte del prompt.

Probar el servidor sin ningún modelo

Un test arranca la aplicación en un puerto aleatorio y usa el cliente del SDK MCP:

@SpringBootTest(webEnvironment = SpringBootTest.WebEnvironment.RANDOM_PORT)
class OrderToolsTest {

    @LocalServerPort
    int port;

    @Test
    void serverListsAndCallsTheTool() {
        var transport = HttpClientStreamableHttpTransport.builder("http://localhost:" + port).build();
        try (McpSyncClient client = McpClient.sync(transport).build()) {
            client.initialize();
            assertThat(client.listTools().tools()).extracting(McpSchema.Tool::name).containsExactly("order_status");

            var ok = client.callTool(new McpSchema.CallToolRequest("order_status", Map.of("orderId", "A-100")));
            assertThat(ok.isError()).isFalse();

            var ko = client.callTool(new McpSchema.CallToolRequest("order_status", Map.of("orderId", "ZZZ")));
            assertThat(ko.isError()).isTrue();
        }
    }
}

El esquema que publicó el servidor fue: type=object, propiedad orderId de tipo string con nuestra descripción, y required=[orderId]. La llamada correcta devolvió el OrderStatus serializado como texto JSON; la excepción no tumbó nada: llegó como resultado con isError=true y el mensaje de la excepción. Ese mensaje lo verá el modelo, así que no metas en él detalles internos.

El cliente

Dependencias: spring-ai-starter-mcp-client, el starter del modelo y spring-boot-starter-webmvc. Configuración:

server.port=8082
spring.ai.ollama.chat.options.model=gpt-oss
spring.ai.mcp.client.streamable-http.connections.pedidos.url=http://localhost:8081

El starter se conecta al arrancar y publica un ToolCallbackProvider con las herramientas del servidor. Lo pasas al ChatClient como cualquier otra tool:

@RestController
class AskController {

    private final ChatClient chatClient;
    private final ToolCallbackProvider mcpTools;

    AskController(ChatClient.Builder builder, ToolCallbackProvider mcpTools) {
        this.mcpTools = mcpTools;
        this.chatClient = builder
                .defaultSystem("Eres el asistente de una tienda. Usa las herramientas para responder sobre pedidos.")
                .defaultToolCallbacks(mcpTools)
                .build();
    }

    @GetMapping("/tools")
    List<String> tools() {
        return Arrays.stream(mcpTools.getToolCallbacks())
                .map(t -> t.getToolDefinition().name())
                .toList();
    }

    @PostMapping("/ask")
    String ask(@RequestBody String question) {
        return chatClient.prompt().user(question).call().content();
    }
}

Arrancados los dos procesos:

GET  /tools → ["order_status"]
POST /ask "¿Cuándo llega el pedido A-100 y en qué estado está?"
→ El pedido A-100 está en estado ENVIADO y se espera que llegue el 2 de diciembre de 2026.
POST /ask "¿Qué pasa con el pedido ZZZ?"
→ Lo siento, pero no encontramos ningún pedido con el identificador ZZZ en nuestro sistema. ...

El segundo caso muestra el error de la herramienta llegando al modelo, que lo convierte en una respuesta educada. En el log del cliente apareció Error calling tool: [TextContent[... No existe el pedido ZZZ, que es donde mirar cuando una respuesta parece inventada. Más sobre cómo hablar con el modelo desde el ChatClient está en el primer artículo de esta serie.

Elegir el transporte

La documentación de Spring AI 2.0 distingue estas opciones de servidor, que se eligen con un starter y la propiedad spring.ai.mcp.server.protocol:

  • STDIO (spring-ai-starter-mcp-server, spring.ai.mcp.server.stdio=true): el servidor corre como proceso hijo de la aplicación que lo usa. No es accesible por red, lo que simplifica la seguridad.
  • STREAMABLE (starters -webmvc o -webflux): un servicio HTTP independiente con varios clientes a la vez. Es el que usamos.
  • STATELESS: sin estado de sesión entre peticiones, pensado para microservicios y despliegues cloud-native. Si necesitas que el servidor avise al cliente de cambios en sus herramientas, la documentación presenta Streamable-HTTP como la opción pensada para eso.
  • SSE: obsoleto desde 2.0; solo si tienes que hablar con clientes antiguos.

El starter -webmvc va con Spring MVC; el -webflux con el stack reactivo. Para el cliente, la documentación recomienda el starter basado en WebFlux en producción y el estándar (el que usamos aquí, basado en el HttpClient del JDK) para empezar.

Cómo ve el modelo tus herramientas

El modelo nunca habla con tu servidor: recibe del cliente un catálogo de funciones (nombre, descripción, esquema) y devuelve, cuando lo necesita, una petición de llamada a una de ellas. Tu aplicación cliente la ejecuta contra el servidor MCP y le devuelve el resultado, y el modelo redacta la respuesta final. Esto tiene dos consecuencias prácticas. Primero, cada herramienta que registras consume tokens de contexto en cada petición, así que expón las necesarias, no todas. Segundo, la llamada de ida y vuelta añade latencia: en nuestro caso, la primera pregunta con gpt-oss local tardó decenas de segundos, casi todo en el modelo y no en MCP.

Lo que falla en la práctica

  • Seguridad. Es lo más importante. La documentación avisa de que los transportes HTTP exponen un endpoint JSON-RPC sin autenticación por defecto: cualquiera que llegue a /mcp puede listar e invocar todas las herramientas. Antes de salir de localhost, ponle Spring Security u otra barrera delante. Cada @McpTool es una decisión de exponer esa operación; no publiques herramientas de escritura sin autorización.
  • Orden de arranque. El cliente se conecta al iniciar. No hemos probado qué ocurre si el servidor no está disponible en ese momento; compruébalo antes de desplegar.
  • Un transporte equivocado. Cliente y servidor deben hablar el mismo: Streamable-HTTP en ambos. En el cliente, la propiedad va bajo streamable-http, no sse.
  • Descripciones pobres. Si el modelo no usa tu herramienta o pasa mal los parámetros, empieza por mejorar description y los @McpToolParam.
  • Modelos sin soporte de tools. No todos los modelos locales llaman herramientas. Comprueba GET /tools primero (sin modelo) y luego el modelo.
  • Sync o async. Servidor y cliente son síncronos por defecto (type=SYNC); no se pueden mezclar clientes síncronos y asíncronos.

Dónde seguir

Además de tools, un servidor puede exponer recursos y prompts (@McpResource, @McpPrompt); no los hemos probado aquí. Si quieres construir agentes completos con MCP, el curso de Spring AI con Spring Boot cubre el tool calling desde cero, y el máster AI Engineer con Java y Spring AI lo integra con seguridad y despliegue.

Newsletter Semanal de Java

Cada viernes recibe lo más nuevo del ecosistema Java: frameworks, herramientas y mejores prácticas.

Sin spam. Cancela cuando quieras.

Compartir artículo