Machai MCP Server 1.2.0-SNAPSHOT API

Machai MCP Server

Machai MCP Server is a server implementation for the Model Context Protocol (MCP) built on the Machai AI framework. It integrates Machai GenAI tools with MCP clients and supports both HTTP and STDIO interfaces for AI-powered tool execution, prompt delivery, and orchestration.

Purpose

The project exposes dynamically loaded GenAI functions as MCP tools and prompts. It is intended for applications and development environments that need a protocol-compatible bridge between MCP clients and Machai tool providers. The server can run as a local process using standard input and output, or as a remote HTTP service backed by Jetty.

Package Structure

The primary package, org.machanism.machai.mcp.server, contains the entry point, transport-specific server implementations, and the generic adapter that converts Machai tool metadata into MCP tool and prompt specifications.

  • Server entry point: McpServer parses command-line options and starts the appropriate server mode. Without a port it starts the STDIO server; with a port it starts an HTTP server. The --session option selects streamable HTTP mode.
  • Common server base: AbstractMcpServer defines shared server metadata, project directory handling, and the tool specification builder contract used by transport-specific implementations.
  • HTTP infrastructure: AbstractHttpMcpServer configures the Jetty server, connector, servlet context, and HTTP transport servlet used by remote MCP deployments.
  • HTTP server modes: HttpStatelessMcpServer provides a stateless synchronous HTTP MCP server, while HttpStreamableMcpServer provides a streamable session-oriented HTTP MCP server.
  • STDIO server mode: StdioMcpServer exposes MCP over standard input and output for local integrations and process-based clients.
  • Tool integration: GenericGenaiAdapter registers Machai GenAI tools, builds JSON schemas from parameter descriptors, routes MCP tool calls to Machai ToolFunction instances, and serializes results for MCP clients.

Runtime Behavior

During startup, the selected server creates MCP capabilities for tools and prompts, initializes a FunctionToolsLoader, and applies available Machai tools through GenericGenaiAdapter. Tool parameter metadata is converted into MCP-compatible JSON schema properties. When a client invokes a tool, the adapter converts the request arguments to JSON, adds session context when available, executes the underlying function, and returns a text content result. Execution failures are reported as MCP error results.

Usage

Start the application through McpServer. Common command-line options are:

  • -h, --help: display command-line help.
  • -d, --projectDir: specify the project directory used by loaded tools.
  • -n, --name: set the MCP server name.
  • -v, --version: set the MCP server version.
  • -p, --port: run as an HTTP MCP server on the given port.
  • -s, --session: use streamable HTTP server mode when running over HTTP.

If no port is provided, the server uses STDIO mode. If a port is provided, the server uses HTTP mode; stateless HTTP is the default and streamable HTTP is enabled with --session.

Class Diagram

The following diagram summarizes the main classes and their relationships in the server package.

Machai MCP Server class diagram

Extensibility

The implementation separates transport concerns from tool registration. New transport modes can extend AbstractMcpServer or AbstractHttpMcpServer and provide a suitable tool specification builder. Additional GenAI tools can be supplied through Machai's tool loading mechanism and are exposed to MCP clients without changing the server entry point.

Packages
Package
Description
org.machanism.machai.mcp.server
Provides the executable Model Context Protocol (MCP) server layer for Machai.