vertx

This Vert.x-based MCP server provides a lightweight, non-blocking transport layer that integrates MCP servers with Vert.x applications. It exposes two transport options: a legacy HTTP+SSE transport and a newer Streamable HTTP transport, enabling real-time bidirectional communication and efficient streaming of MCP messages. You can deploy the provided McpVerticle to host your MCP server alongside your Vert.x application, enabling automatic session management and graceful shutdown for connected clients. Use the SSE transport if you want a straightforward, event-driven endpoint for MCP messaging, or opt for the Streamable HTTP transport if you need a more flexible, chunked HTTP interface that supports streaming of large tool data and results.

To use this server in your project, deploy the McpVerticle with a configured transport and an MCP server specification. The example in the repository shows how to wire a simple calculator tool and expose it via the MCP server. Once deployed, clients can interact with your MCP-enabled tools through the transport endpoints you choose (SSE endpoints or streamable HTTP endpoints), receive tool results, and manage sessions automatically through the Vert.x runtime.

Prerequisites:

• Java (JDK 11 or newer)
• Maven or Gradle for building the project
• Docker (optional, if using the provided container image)

Using Maven:

1. Install Maven and ensure mvn -version works.
2. Clone the repository and navigate to the project directory.
3. Build the project: mvn -B -DskipTests package
4. Run the application (example): java -jar target/vertx-mcp-server-<version>.jar

Using Gradle:

1. Ensure Gradle is installed or use the Gradle wrapper.
2. Build the project: ./gradlew build
3. Run the application (example): java -jar build/libs/vertx-mcp-server-<version>.jar

Using Docker (if a container image is available):

1. Pull the image: docker pull kinotic-ai-vertx-mcp
2. Run the container with appropriate ports and environment: docker run -p 8080:8080 kinotic-ai-vertx-mcp

Notes:

• The README indicates experimental status; ensure you test thoroughly in a non-production environment.
• If you plan to customize tools, follow the MCP Java SDK examples provided in the repository to register your tools and handlers.

Tips and considerations:

• This MCP server supports both SSE and Streamable HTTP transports; choose based on your client capabilities and data transfer needs.
• The project emphasizes non-blocking, event-driven operation with Vert.x; ensure your Vert.x event loop and worker threads are configured to handle your expected load.
• Session management is automatic with graceful shutdown support; verify your client reconnection strategy for long-lived sessions.
• Since the project is experimental, monitor for API changes and report any issues via the project's issue tracker.
• If you plan to deploy via Docker, ensure environment variables (if any) are set according to your deployment environment and that the container exposes the correct MCP endpoints.