What is Mcpx4j

mcpx4j is a Java client library designed for interacting with the MCP.RUN service, enabling developers to call portable and secure tools for their AI agents and applications.

Use cases

Use cases for mcpx4j include building AI-driven applications, automating tasks with secure tool calls, and integrating various services within a Java application.

How to use

To use mcpx4j, create an instance of Mcpx with your API key, refresh the installations, and invoke tools using the provided methods. Detailed examples can be found in the examples directory.

Key features

Key features of mcpx4j include a thread-safe internal store, customizable JSON decoders, and the ability to specify an alternative base URL for the MCP.RUN service.

Where to use

mcpx4j can be used in various fields such as AI development, application integration, and any scenario requiring secure tool invocation for automated processes.

MCPX4J

The MCP.RUN client library for Java!

Installation

<dependencies>
    <dependency>
       <groupId>com.dylibso.mcpx4j</groupId>
        <artifactId>mcpx4j</artifactId>
        <version>${mcpx4j.version}</version>
    </dependency>
</dependencies>

Quick Start

Create a new Mcpx instance with your API key and start invoking your installed tools.

import com.github.dylibso.mcpx4j.Mcpx;

Mcpx mcpx = Mcpx.forApiKey(apiKey).build();
mcpx.refreshInstallations();
var servlet = mcpx.get("my-servlet-id");
var tool = servlet.get("my-tool-id");
var bytes = servlet.call("""
{
    "method": "tools/call",
    "params": {
        "name": "my-tool-id",
        "arguments": {
            ...
        }  
    }
}
""");

Detailed examples are available in the examples directory.

Plugin Updates

Mcpx keeps a cache of installations. You can refresh the cache by calling refreshInstallations().
The internal store is thread-safe, so you can schedule a refresh in a separate thread.

var scheduler = Executors.newSingleThreadScheduledExecutor();
scheduler.scheduleAtFixedRate(mcpx::refreshInstallations, 0, 5, TimeUnit.MINUTES);

Configuration

It is possible to provide an alternative base URL for the mcp.run service
(defaults to https://www.mcp.run).

var mcpx = Mcpx.forApiKey(apiKey)
    .withBaseUrl(jsonDecoder)
    ...
    .build();

The Mcpx builder allows to customize the JSON decoder and the HTTP client.

JSON Decoder

var mcpx = Mcpx.forApiKey(apiKey)
    .withBaseUrl("https://localhost:8080")
    ...
    .build();

The default JSON decoder is JacksonDecoder, using Jackson Databind. We also provide an alternative
implementation based on Jakarta JSON-P.

Both dependencies are optional, so you should make sure to include them in your project if you want to use them.

    <dependency>
        <groupId>com.fasterxml.jackson.core</groupId>
        <artifactId>jackson-databind</artifactId>
        <version>${jackson-databind.version}</version>
    </dependency>

    <!-- Eclipse Parsson is an implementation of the Jakarta JSON-P API  -->
    <dependency>
        <groupId>org.eclipse.parsson</groupId>
        <artifactId>parsson</artifactId>
        <version>${parsson.version}</version>
    </dependency>

HTTP Client

var mcpx = Mcpx.forApiKey(apiKey)
    .withHttpClientAdapter(httpClientAdapter)
    ...
    .build();

The default HTTP client is JdkHttpClientAdapter, using the JDK HTTP client,
there is also a lighter-weight implementation using an HttpURLConnection, called HttpUrlConnectionClientAdapter.

var mcpx = Mcpx.forApiKey(apiKey)
    .withHttpClientAdapter(new JdkHttpClientAdapter())
    .withHttpClientAdapter(new HttpUrlConnectionClientAdapter()) // alternatively
    ...
    .build();

The HttpClientAdapter interface is currently borrowed from the Chicory Extism SDK.
This might change in the future.

Servlet Options

It is also possible to provide predefined options for the Servlet implementation: these
config options are propagated to the Chicory Extism SDK upon creation of
each Servlet.

var mcpx = Mcpx.forApiKey(apiKey)
    .withServletOptions(McpxServletOptions.builder()
        .withChicoryHttpConfig(...)
        .withChicoryLogger(...)
        .withAoT() 
        .build())
    .build();

• ChicoryHttpConfig controls the HTTP client and Json decoder used by the Chicory SDK:
  usually these should match the ones used by the MCPX4J client.
• ChicoryLogger is a logger implementation for the Chicory SDK.
• AoT enables the Ahead-of-Time compilation for the Chicory SDK.