Prerequisites

Before running Machai MCP Server, ensure you have:

• Java 17 or newer, matching the maven.compiler.release value in pom.xml
• Maven, if you plan to build the project from source
• at least one Machai-compatible functional tool jar available on the runtime classpath
• any environment variables required by the loaded tools or upstream AI providers, such as model names and provider credentials
• network access if you plan to run the HTTP server mode or connect to remote AI services

Build

To build the project from source:

mvn clean package

To create the packaged distribution jar with dependencies using the assembly profile:

mvn -Ppack install

Basic Usage

Run the server in STDIO mode by placing the server jar and your functional tool jar on the classpath:

java -cp /absolute/path/to/machai-mcp-server.jar:/absolute/path/to/functional-tool-container.jar org.machanism.machai.mcp.server.McpServer

Typical Workflow

1. Build or download the Machai MCP Server artifact.
2. Build your custom functional tool implementation jar with the required SPI registration.
3. Place both jars on the Java classpath.
4. Export any required environment variables for AI providers and tool configuration.
5. Start the server in STDIO mode for local desktop integrations, or pass a port to run it over HTTP.
6. Connect an MCP client and invoke the published tools and prompts.

Java Version

The project requires Java 17, as defined by the Maven compiler release. In practice, you also need a runtime environment that can access any configured AI backends and any custom tool dependencies present on the classpath.

Command-Line Options

The application entry point defines the following options:

• -h, --help: prints the available command-line options
• -d, --projectDir <path>: sets the project directory that tools can use as execution context
• -n, --name <value>: overrides the MCP server name reported to clients
• -v, --version <value>: overrides the MCP server version reported to clients
• -p, --port <number>: enables HTTP server mode and binds the server to the specified port
• -s, --session: enables streamable HTTP MCP mode; this only applies when HTTP mode is active

If --port is omitted, the application starts in STDIO mode. If --port is provided, the application starts an HTTP server. When --session is added together with --port, the HTTP server uses the streamable transport; otherwise it uses the stateless transport.

Options Table

Example

The following example starts the HTTP server on port 45000, sets a custom server identity, provides a project directory, and enables streamable sessions:

export gw_model=CodeMie:gpt-5.4-2026-03-05
export embedding_model=CodeMie:text-embedding-005
export GENAI_USERNAME=your_username
export GENAI_PASSWORD=your_password

java -cp /absolute/path/to/machai-mcp-server.jar:/absolute/path/to/functional-tool-container.jar org.machanism.machai.mcp.server.McpServer \
  --projectDir /absolute/path/to/project \
  --name my-mcp-server \
  --version 1.0.0 \
  --port 45000 \
  --session

Claude Desktop Configuration

{
  "mcpServers": {
    "stdio-mcp-server": {
      "command": "java",
      "args": [
        "-cp",
        "/absolute/path/to/your/machai-mcp-server.jar:/absolute/path/to/your/functional-tool-container.jar",
        "org.machanism.machai.mcp.server.McpServer"
      ],
      "env": {
        "gw_model": "CodeMie:gpt-5.4-2026-03-05",
        "embedding_model": "CodeMie:text-embedding-005",
        "GENAI_USERNAME": "your_username",
        "GENAI_PASSWORD": "your_password"
      }
    }
  }
}

Start MCP Server

export gw_model=CodeMie:gpt-5.4-2026-03-05
export embedding_model=CodeMie:text-embedding-005
export GENAI_USERNAME=your_username
export GENAI_PASSWORD=your_password
export BINDEX_REG_PASSWORD=your_bindex_password

java -cp /absolute/path/to/your/machai-mcp-server.jar:/absolute/path/to/your/functional-tool-container.jar org.machanism.machai.mcp.server.McpServer --port 45000

Claude Desktop Configuration

{
  "mcpServers": {
    "localMcpServer": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:45000/mcp"
      ]
    }
  }
}

MCP Inspector

The MCP Inspector is useful for validating tool registration, prompt exposure, and runtime behavior while developing or integrating the server. For long-running tool calls, you can increase the request timeout so the inspector does not fail early.

See: MCP Inspector

Example with a 5-minute timeout:

npx @modelcontextprotocol/inspector

Claude Desktop

Claude Desktop is a practical client for connecting to both STDIO and HTTP deployments of the server. It is especially useful for validating end-user MCP integration, tool availability, and desktop-driven workflows.

See more: Desktop application

CodeMie Code

CodeMie Code is a Unified AI Coding Assistant CLI that empowers you to manage Claude Code, OpenAI Codex, Google Gemini, OpenCode, and custom AI agents—all from a single, powerful command-line interface.

Key Features:

• Unified Multi-Provider Support: Seamlessly connect to OpenAI, Azure OpenAI, AWS Bedrock, LiteLLM, Ollama, and more. Supports advanced authentication methods including Enterprise SSO and JWT Bearer Auth.
• Built-in LangGraph Agent: Leverage file operations, command execution, and planning tools directly from the CLI.
• Flexible Integration: Easily register and interact with MCP-compatible servers and custom AI agents.
• Cross-Platform: Works on Windows, Linux, and macOS for maximum developer flexibility.
• End-to-End Workflow Validation: Test tool registration, prompt exposure, and agent workflows directly from your terminal or code editor.

Setup Example:

1. Register your MCP server with the CodeMie proxy:

   npx claude mcp add my-remote-server -- codemie-mcp-proxy "http://localhost:45000/mcp"
   

2. Launch CodeMie Code:

   npx codemie-code
   

3. Connect and interact:

   • Use the CLI to browse available tools, send prompts, and observe responses in real time across multiple AI providers.

Learn more: CodeMie Code documentation