Vert.x MCP Example Project

This is a complete, working example of an MCP (Model Context Protocol) server built using the vertx-mcp framework.

Overview

This example demonstrates how to build a production-ready MCP server with:

• A calculator tool that performs basic mathematical operations
• Streamable HTTP transport for efficient communication
• Proper error handling and configuration management
• Integration testing

Prerequisites

• Java 21 or later
• Gradle 8.0 or later

Getting Started

1. Clone and Build

git clone <repository-url>
cd vertx-mcp-example
./gradlew build

2. Run the Server

# Run with default configuration (port 8080)
./gradlew run

# Or run with custom configuration
export MCP_PORT=9090
export MCP_BASE_URL=http://localhost:9090
./gradlew run

3. Test the Server

The server will start and display:

✅ MCP Server started successfully!
🌐 Endpoint: http://localhost:8080/mcp
🏥 Health check: http://localhost:8080/health
📚 Calculator tool available

Server is ready to accept MCP connections!

Project Structure

src/
├── main/
│   ├── java/
│   │   └── org/kinotic/example/
│   │       ├── McpServerApplication.java    # Main application class
│   │       └── CalculatorTool.java          # Calculator tool implementation
│   └── resources/
└── test/
    └── java/
        └── org/kinotic/example/
            └── McpServerApplicationTest.java # Basic tests

Calculator Tool

The example includes a calculator tool that supports:

• add: Addition of two numbers
• subtract: Subtraction of two numbers
• multiply: Multiplication of two numbers
• divide: Division of two numbers (with zero-division protection)

Example Usage

The calculator tool accepts JSON input like:

{
  "operation": "add",
  "a": 5,
  "b": 3
}

And returns:

{
  "textContent": ["8.0"],
  "isError": false
}

Configuration

The server can be configured using environment variables:

• MCP_PORT: Server port (default: 3001)
• MCP_BASE_URL: Base URL for the server (default: http://localhost:3001)

Testing

Run the tests to verify everything works:

./gradlew test

Related Resources

• Medium Article: Building a Model Context Protocol Server with Vert.x
• vertx-mcp Framework: GitHub Repository
• MCP Specification: Model Context Protocol

Contributing

This is an example project. For issues or contributions related to the vertx-mcp framework itself, please visit the main repository.

License

This example project is provided as-is for educational purposes. See the main vertx-mcp project for licensing information.