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
• one or more Machai-compatible functional tool or prompt libraries on the runtime classpath; the server does not publish built-in tools by itself
• environment variables, credentials, model names, or service settings required by the loaded tools and their AI providers
• network access and an available TCP port if you plan to run HTTP mode
• an MCP-compatible client such as Claude Desktop, MCP Inspector, CodeMie Code, or another client that can connect to STDIO or HTTP MCP servers

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 at least one functional tool container jar on the classpath:

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

Run the server in HTTP mode by providing a port:

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

Typical Workflow

1. Download a release package or build the server from source.
2. Prepare one or more Machai-compatible functional tool libraries with the required service-provider registration.
3. Add the server artifact and the tool libraries to the Java runtime classpath.
4. Export any environment variables or credentials required by the selected tools and AI providers.
5. Start the server in STDIO mode for local desktop integrations, or start it with --port for HTTP access.
6. Optionally pass --projectDir so tools have a known project context.
7. Connect an MCP client and verify that the expected tools and prompts are available.
8. Invoke tools through the MCP client and monitor logs when troubleshooting runtime behavior.

Java Version

The project requires Java 17, as defined by the Maven compiler release. Functional operation also depends on the additional tool libraries supplied at runtime and any services, credentials, model configuration, or project files those tools require.

Command-Line Options

The application entry point defines the following command-line options:

• -h, --help: shows the command-line help message and exits after printing the available options.
• -d, --projectDir <path>: specifies the project directory path. This value is passed to the MCP server and can be used by tools as execution context.
• -n, --name <value>: specifies the MCP server name exposed to clients.
• -v, --version <value>: specifies the MCP server version exposed to clients.
• -p, --port <number>: starts the application as an HTTP MCP server and listens on the specified port.
• -s, --session: uses streamable MCP server mode. This option is only meaningful for HTTP mode.

If --port is omitted, the application starts in STDIO mode. If --port is provided, the application starts an HTTP server. When --session is provided together with --port, the HTTP server uses streamable transport; otherwise it uses stateless HTTP transport. In HTTP mode, console logging is enabled at runtime. If no project directory is configured in HTTP mode, the server logs a warning and determines the project directory from the client request when possible.

Options Table

Example

The following example starts the HTTP server on port 45000, sets custom server metadata, 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 /path/to/machai-mcp-server.jar:/path/to/functional-tool-container.jar org.machanism.machai.mcp.server.McpServer \
  --projectDir /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",
        "/path/to/your/machai-mcp-server.jar:/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"
      }
    }
  }
}

Log File Location

When you run the STDIO MCP server, logs are written to a file for troubleshooting and monitoring. The default log file location for Claude Desktop on Windows is typically:

<user profile directory>\AppData\Local\AnthropicClaude\<app-version>\logs\machai-mcp-server.log

• Replace <user profile directory> with your Windows user folder, such as C:\Users\YourUsername.
• Replace <app-version> with the installed Claude Desktop application version, such as app-1.14271.0.
• The file can contain server startup details, tool registration information, command execution records, warnings, and errors.
• Check this log first when diagnosing STDIO client integration issues.

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 /path/to/your/machai-mcp-server.jar:/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, increase the request timeout in the inspector settings if needed.

See: MCP Inspector

Start the inspector with:

npx @modelcontextprotocol/inspector

Claude Desktop

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

See more: Desktop application

CodeMie Code

CodeMie Code is a unified AI coding assistant CLI that helps manage Claude Code, OpenAI Codex, Google Gemini, OpenCode, and custom AI agents from a single command-line interface.

npm install -g @codemieai/code

codemie mcp add --scope project mcp-remote-server "http://localhost:45000/mcp"

codemie mcp add mcp-remote-server "http://localhost:45000/mcp"

codemie-claude