AJ-MCP

A Lightweight Java MCP SDK

---

AJ-MCP is a lightweight Model Context Protocol (MCP) SDK for Java. It provides a small, direct API for building MCP clients and servers, especially for existing systems that must remain on Java 8 or Spring Boot 2.x.

• Supports Java 8 and above, and supports Spring Boot 2.x.
• Lightweight and small, with Jackson JSON and OkHttp as its main runtime dependencies.
• Easy to use and extend, with examples and bilingual documentation.
• Supports STDIO, the legacy HTTP/SSE transport, and Streamable HTTP.
• Implements MCP protocol revisions 2024-11-05, 2025-03-26, and 2025-06-18 with version negotiation.
• Covers tools, resources, resource templates, prompts, completion, pagination, subscriptions, cancellation, logging, roots, sampling, and elicitation.

Check out these three projects of MCP SDK components:

• AJ MCP Common, Common library for AJ-MCP, it contains the implementation of the Model Context Protocol and some other common classes.
• AJ MCP Client, MCP Client SDK.
• AJ MCP Server, MCP Server SDK.
• Samples for both client and server.

For further information, please refer to the User Manual website.

When to use AJ-MCP

AJ-MCP is intended for Java applications that need to expose existing business capabilities to AI clients, or consume MCP servers without upgrading the entire application stack. Typical uses include:

• wrapping an existing Java service as MCP tools, resources, or prompts;
• connecting a Java desktop or server application to a local STDIO MCP process;
• integrating MCP into Spring Boot 2.x or a Servlet-based application;
• supporting clients that negotiate different MCP protocol revisions.

JSON-RPC batch messages are intentionally not supported.

Modules

Module	Purpose	Current version
aj-mcp-common	Shared JSON-RPC messages, MCP protocol models, content types, version metadata, and JSON utilities	1.7
aj-mcp-client	Synchronous client API and STDIO, HTTP/SSE, and Streamable HTTP transports	1.5
aj-mcp-server	Annotation-based feature discovery, request dispatch, errors, sessions, and server transports	1.4
samples	STDIO, Spring Boot/SSE, and embedded Tomcat examples	—

The client and server artifacts already depend on aj-mcp-common; applications normally add only the artifact they use.

Quick start

Expose a tool from a Java 8 server

Add the server dependency:

<dependency>
    <groupId>com.ajaxjs</groupId>
    <artifactId>aj-mcp-server</artifactId>
    <version>1.4</version>
</dependency>

Declare a service and start it over STDIO:

@McpService
public class GreetingTools {
    @Tool(description = "Greets a user")
    public String greet(@ToolArg("name") String name) {
        return "Hello, " + name;
    }
}

public static void main(String[] args) {
    FeatureMgr features = new FeatureMgr();
    features.init("com.example.mcp");

    McpServer server = new McpServer();
    server.setFeatureMgr(features);
    server.setServerConfig(new ServerConfig());
    server.setTransport(new ServerStdio(server));
    server.start();
}

Keep standard output reserved for JSON-RPC messages when using STDIO; send application logs to standard error or a log file. See the server README for tools, resources, prompts, and HTTP transports.

Connect from a Java client

<dependency>
    <groupId>com.ajaxjs</groupId>
    <artifactId>aj-mcp-client</artifactId>
    <version>1.5</version>
</dependency>

try (McpClient client = McpClient.createStdioMcpClient(
        "java", "-jar", "/path/to/mcp-server.jar")) {
    client.listTools().forEach(tool -> System.out.println(tool.getName()));
    String result = client.callTool("greet", "{\"name\":\"AJ-MCP\"}");
    System.out.println(result);
}

Always close a client so its streams, HTTP connections, pending requests, worker threads, and optional child process are released. See the client README for HTTP transports and additional APIs.

Build from source

Use Maven with JDK 8 or JDK 17:

mvn test

To build only one module and its dependencies:

mvn -pl aj-mcp-client -am test
mvn -pl aj-mcp-server -am test

Why MCP?

The Model Context Protocol opens up exciting possibilities for building intelligent applications using your application data with your favourite programming language and framework. With AJ MCP Servers, you have a powerful foundation to create your own Java based servers that can bridge AI with any data source or system you can imagine.

Whether you want to connect to your favorite database, integrate with your company’s internal systems, or build something completely new - the sky truly is the limit! The simplicity of implementing MCP servers with AJ means you can focus on the creative aspects rather than the plumbing.

So what are you waiting for? Grab the code, fire up your IDE, and start building your own MCP server today. The future of AI-powered applications is here, and you can be part of shaping it!

Have Fun!

Links

User Manual | Github | Gitcode

Helpful links for MCP

Awesome MCP Servers | TypeScript SDK | MCP Documentation