synchronous mcp client with blocking request-response semantics
Implements a blocking MCP client that sends protocol messages and waits for responses using Java's traditional synchronous threading model. Built on Jackson JSON serialization and JSON Schema validation, it handles request correlation, timeout management, and error handling through standard Java exception mechanisms. Developers call methods directly and receive results immediately, with no reactive overhead.
Unique: Provides a pure blocking API without reactive abstractions, using traditional Java exception handling and thread-based concurrency — contrasts with async variant that uses Project Reactor Mono/Flux
vs alternatives: Simpler mental model than async/reactive alternatives for developers in non-concurrent scenarios, but trades throughput for ease of integration in legacy codebases
asynchronous mcp client with project reactor mono/flux composition
Implements a non-blocking MCP client using Project Reactor's reactive streams (Mono for single responses, Flux for streaming). Each protocol method returns a Mono<Response> that can be composed, chained, and transformed using reactive operators. Internally uses async I/O (HTTP async clients, non-blocking socket channels) to avoid thread blocking, enabling efficient multiplexing of thousands of concurrent requests with a small thread pool.
Unique: Uses Project Reactor's Mono/Flux abstraction for composable async operations, enabling functional reactive chains with backpressure and operator composition — standard in Spring ecosystem but requires reactive mindset
vs alternatives: Dramatically more efficient than synchronous blocking for high concurrency (handles 10,000+ concurrent connections with 10 threads vs 10,000 threads), but requires reactive expertise and adds complexity for simple use cases
json schema validation of mcp protocol messages
Validates all incoming MCP protocol messages against JSON Schema specifications using the JSON Schema Validator library (1.5.7). Validates request parameters, response structures, and streaming message formats before processing. Provides detailed validation error messages indicating which fields failed validation and why. Integrated into both client and server message processing pipelines.
Unique: Uses JSON Schema Validator library to validate all protocol messages against formal schema specifications, providing detailed error messages for debugging — ensures protocol compliance at message boundaries
vs alternatives: More thorough than type checking alone (validates structure, constraints, enums) but slower than runtime type checking; essential for protocol compliance, optional for internal APIs
session management with request correlation and timeout handling
Manages MCP client-server sessions by correlating requests with responses using unique message IDs. Tracks in-flight requests, enforces timeouts (default configurable), and cleans up abandoned sessions. Supports both stateful sessions (persistent connection) and stateless sessions (HTTP request-response). Handles connection lifecycle events (connect, disconnect, error) with callbacks.
Unique: Implements request correlation using message IDs and timeout enforcement via background cleanup, supporting both stateful and stateless session models — enables reliable request-response matching in concurrent scenarios
vs alternatives: More robust than simple request-response matching (handles out-of-order responses, timeouts) but adds complexity; essential for concurrent scenarios, optional for sequential use
stateless server features with request isolation and no cross-request context
Implements stateless MCP server design where each request is processed independently with no shared state between requests. Handlers receive request parameters and return responses without access to previous requests or session data. Enables horizontal scaling (multiple server instances) without session affinity. Supports request isolation via context variables (ThreadLocal or reactive context) for per-request metadata.
Unique: Enforces stateless server design with request isolation via context variables, enabling horizontal scaling without session affinity — standard pattern in cloud-native architectures
vs alternatives: Enables unlimited horizontal scaling and cloud-native deployment, but prevents cross-request optimizations (caching, connection pooling); essential for cloud, poor for stateful applications
jackson json serialization with custom type handling and polymorphism
Uses Jackson 2.17.0 for JSON serialization/deserialization of MCP protocol messages with support for custom type handling, polymorphic types (tool results, resource types), and streaming JSON parsing. Configures ObjectMapper with MCP-specific modules for handling protocol-specific types. Supports both eager deserialization (full message parsing) and streaming deserialization (incremental parsing for large responses).
Unique: Uses Jackson with custom type handling and polymorphic support for MCP protocol messages, enabling automatic serialization of complex nested structures and polymorphic types — standard approach in Java ecosystem
vs alternatives: More flexible than code generation (supports runtime polymorphism) but slower than hand-written serializers; standard choice for Java, good for complex types, poor for performance-critical paths
maven bill of materials (bom) for centralized dependency version management
Provides mcp-bom module that centralizes version management for all MCP SDK dependencies (Jackson, Project Reactor, Spring Framework, SLF4J, etc.). Projects import the BOM to inherit consistent versions across all modules without specifying individual versions. Prevents version conflicts and ensures all MCP components use compatible dependency versions.
Unique: Provides centralized BOM for consistent version management across all MCP SDK modules and dependencies — standard Maven practice for multi-module projects
vs alternatives: Eliminates version management boilerplate and prevents conflicts, but requires Maven; Gradle users must manually manage versions or use Gradle BOM support
synchronous mcp server with request handler registration and stateless processing
Implements a blocking MCP server that registers handler functions for protocol methods (tools, resources, prompts) and processes incoming requests synchronously. Handlers are registered as Java functions/lambdas that receive request parameters and return responses. The server validates incoming messages against JSON Schema, routes to appropriate handlers, and sends responses back through the transport layer. Supports both single-request and streaming response patterns.
Unique: Provides handler registration pattern where developers register Java functions for each MCP method, with automatic JSON Schema validation and routing — simpler than building raw protocol handlers but less flexible than custom transport implementations
vs alternatives: Easier to build than raw socket servers but less scalable than async alternatives; good for tool servers with <100 req/sec, poor for high-throughput scenarios
+7 more capabilities