MCPX4J

The MCP.RUN client library for Java!

Installation

MCPX4J is currently available on JitPack.

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.dylibso</groupId>
        <artifactId>mcpx4j</artifactId>
        <version>main-SNAPSHOT</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.