MCP Server Maven Plugin 1.2.0-SNAPSHOT API

MCP Server Maven Plugin

MCP Server Maven Plugin is a Maven plugin that starts the Machai MCP Server as part of a Maven build. It exposes Machai AI tools over the Model Context Protocol via HTTP, making the server available to MCP-compatible clients such as Claude Desktop during development, integration testing, or any workflow that requires a running MCP endpoint alongside a Maven build.

Overview

The plugin bridges Maven project context with the Machai MCP Server runtime. When a goal is invoked, the plugin resolves the project base directory and version from the active Maven project, constructs the appropriate server instance, registers available tools through Java SPI discovery, and starts the server on the configured port.

Two HTTP transport modes are provided as separate aggregator goals:

  • Stateless HTTP — each request is handled independently with no persistent session state, using HttpServletStatelessServerTransport from the MCP SDK.
  • Streamable HTTP — supports incremental result delivery over a persistent HTTP connection, using HttpServletStreamableServerTransportProvider from the MCP SDK.

Both modes expose the same SPI-discovered Machai tools, report server identity from the Maven project name and version, and accept the same mcp.port configuration parameter.

Primary responsibilities

  • Expose Maven goals for starting an MCP server in stateless or streamable HTTP mode.
  • Resolve Maven project metadata (name, version, base directory) and pass it to the server runtime.
  • Delegate tool registration to FunctionToolsLoader and GenericGenaiAdapter via SPI.
  • Manage Jetty server lifecycle for the duration of the Maven goal execution.

Goals

mcp-server:stateless
Aggregator goal that starts the Machai MCP Server in stateless HTTP mode. Constructs an HttpStatelessMcpServer, registers tools, and listens on the configured port until the process is stopped.
mcp-server:streamable
Aggregator goal that starts the Machai MCP Server in streamable HTTP mode. Constructs an HttpStreamableMcpServer, registers tools, and listens on the configured port until the process is stopped.

Shared configuration concepts

Port (mcp.port)
The network port the HTTP server binds to. Required for both goals. Can be supplied in the plugin configuration block or overridden with -Dmcp.port=... on the command line.
Base directory (basedir)
Resolved automatically from the Maven project. Passed to the server as the project directory so that SPI-loaded tools can resolve project-relative paths.
Project name and version
Taken from the active Maven project and reported in the MCP server identity block exposed to connecting clients.

Package structure

org.machanism.machai.mcp.server.maven

Contains the Maven mojos and their shared base class. The base class collects the common parameters (basedir, project, mcp.port) and is extended by the two concrete goal classes.

  • AbstractMCPServerMojo — shared base that declares basedir, project, and mcp.port parameters.
  • HttpStatelessServerMojo — implements the mcp-server:stateless goal using HttpStatelessMcpServer.
  • HttpStreamableMcpServerMojo — implements the mcp-server:streamable goal using HttpStreamableMcpServer.

Typical usage

Configure the plugin in pom.xml with the desired port, then invoke a goal directly:

  • mvn mcp-server:stateless
  • mvn mcp-server:streamable
  • mvn mcp-server:stateless -Dmcp.port=8080

Class diagram

The following diagram summarizes the main goals and supporting types in the plugin.

Class diagram for MCP Server Maven Plugin

Packages
Package
Description
org.machanism.machai.mcp.maven
Provides Maven plugin Mojos and utilities for managing MCP server lifecycle and configuration.
org.machanism.machai.mcp.maven.tools
Contains utility classes and tools for MCP server operations within Maven plugins.