Expose your Liberty business logic as AI tools - a complete guide to MCP server

<!-- MCP Server API -->
<dependency>
    <groupId>org.mcpjava</groupId>
    <artifactId>mcp-server-api</artifactId>
    <version>1.0.0</version>
    <scope>provided</scope>
</dependency>

<properties>
    <wlp-dir-path>replace-with-path-to-wlp-dir</wlp-dir-path>
    <mcp-jar-version>replace-with-version-number</mcp-jar-version>
</properties>

<!-- Liberty MCP extensions (io.openliberty.mcp) -->
<dependency>
    <groupId>io.openliberty.mcp</groupId>
    <artifactId>mcp-core</artifactId>
    <version>${mcp-jar-version}</version>
    <scope>system</scope>
    <systemPath>${wlp-dir-path}/dev/api/ibm/io.openliberty.mcp_${mcp-jar-version}.jar</systemPath>
</dependency>

<featureManager>
    <feature>servlet-6.0</feature>
    <feature>cdi-4.0</feature>
    <feature>mcpServer-1.0</feature>
</featureManager>

CWMCM0008I: The MCP server endpoint: http://localhost:9080/myMcpApp/mcp

{
  "mcpServers": {
    "myApp": {
      "type": "streamable-http",
      "url": "http://localhost:9080/myMcpApp/mcp"
    }
  }
}

npx @modelcontextprotocol/inspector

package com.example.mcp;

import org.mcpjava.server.tools.Tool;
import org.mcpjava.server.tools.ToolArg;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.inject.Inject;

@ApplicationScoped
public class WeatherTools {

    @Inject
    private WeatherClient weatherClient;

    @Tool(name = "getForecast",
          title = "Weather Forecast Provider",
          description = "Get the weather forecast for a location.")
    public String getForecast(
            @ToolArg(name = "latitude",  description = "Latitude of the location")  String latitude,
            @ToolArg(name = "longitude", description = "Longitude of the location") String longitude) {
        return weatherClient.getForecast(
                Double.parseDouble(latitude),
                Double.parseDouble(longitude),
                4,
                "temperature_2m,snowfall,rain,precipitation,precipitation_probability");
    }
}

import org.mcpjava.server.tools.Tool;
import org.mcpjava.server.tools.ToolArg;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class CatalogueTools {

    @Tool(name = "search", description = "Search the product catalogue.")
    public String search(
            @ToolArg(name = "query",    description = "Search terms")    String query,
            @ToolArg(name = "maxItems", description = "Maximum results",
                     required = false,  defaultValue = "10")             int maxItems,
            @ToolArg(name = "category", description = "Product category") Optional<String> category) {
        // category is empty when not provided by the AI
        return catalogue.search(query, maxItems, category.orElse("all"));
    }
}

import io.openliberty.mcp.annotations.Schema;

@Schema(description = "A person with a home address and employer")
public record Person(String name, Address address, Company company) {}

import io.openliberty.mcp.annotations.DefaultValueConverter;
import jakarta.enterprise.context.ApplicationScoped;

public record DateRange(LocalDate start, LocalDate end) {}

@ApplicationScoped
public class DateRangeConverter implements DefaultValueConverter<DateRange> {
    @Override
    public DateRange convert(String defaultValue) {
        String[] parts = defaultValue.split("/");
        return new DateRange(LocalDate.parse(parts[0]), LocalDate.parse(parts[1]));
    }
}

import org.mcpjava.server.tools.Tool;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class ConfigTools {

    @Tool(name = "readConfig",
          description = "Read the application configuration.",
          annotations = @Tool.Annotations(
                  readOnlyHint    = true,
                  destructiveHint = false,
                  idempotentHint  = true,
                  openWorldHint   = false))
    public String readConfig() {
        return configService.getCurrentConfig();
    }
}

import org.mcpjava.server.tools.Tool;
import org.mcpjava.server.tools.ToolArg;
import org.mcpjava.server.tools.ToolResponse;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class CatalogueTools {

    @Tool(name = "lookup", description = "Lookup an item.")
    public ToolResponse lookup(@ToolArg(name = "id", description = "Item ID") String id) {
        try {
            String result = catalogue.findById(id);
            return ToolResponse.ofText(result);
        } catch (NotFoundException e) {
            return ToolResponse.ofError("Item not found: " + id);
        }
    }
}

import org.mcpjava.server.ContentEncoder;
import org.mcpjava.server.content.ContentBlock;
import org.mcpjava.server.content.TextContent;
import jakarta.enterprise.context.ApplicationScoped;
import jakarta.json.bind.Jsonb;
import jakarta.json.bind.JsonbBuilder;

@ApplicationScoped
public class PersonContentEncoder implements ContentEncoder<Person> {

    private static final Jsonb jsonb = JsonbBuilder.create();

    @Override
    public Class<Person> getType() {
        return Person.class;
    }

    @Override
    public ContentBlock encode(Person person) {
        // Custom formatting — e.g. redact sensitive fields before returning to the AI
        Person redacted = new Person(person.name(), "[REDACTED]", person.age());
        return TextContent.of(jsonb.toJson(redacted));
    }
}

import org.mcpjava.server.Cancellation;
import org.mcpjava.server.tools.Tool;
import org.mcpjava.server.tools.ToolArg;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class DataTools {

    @Tool(name = "processDataset",
          title = "Process Large Dataset",
          description = "Processes a dataset in chunks. Can be cancelled by the client.")
    public String processDataset(
            @ToolArg(name = "datasetId", description = "ID of the dataset to process") String datasetId,
            Cancellation cancellation) throws InterruptedException {

        List<String> results = new ArrayList<>();
        for (String chunk : dataService.getChunks(datasetId)) {
            // Check for cancellation before processing each chunk
            if (cancellation.check().isRequested()) {
                throw new Cancellation.OperationCancelledException();
            }
            results.add(process(chunk));
        }
        return results.toString();
    }
}

import org.mcpjava.server.McpRequest;
import org.mcpjava.server.tools.Tool;
import org.mcpjava.server.tools.ToolArg;
import jakarta.enterprise.context.ApplicationScoped;

@ApplicationScoped
public class AuditTools {

    @Tool(name = "auditedSearch", description = "Search with audit logging.")
    public String auditedSearch(
            @ToolArg(name = "query", description = "Search query") String query,
            McpRequest request) {

        logger.info("Tool call [" + request.id() + "] session=" + request.sessionId().orElse("stateless")
                + " protocol=" + request.protocolVersion());

        return searchService.search(query);
    }
}

<application location="myMcpApp.war">
    <mcpServer>
        <info name="Weather Service"
              version="2.0"
              description="Provides real-time weather forecast tools."/>
    </mcpServer>
</application>

<application location="myMcpApp.war">
    <mcpServer stateless="true"/>
</application>

<application location="myMcpApp.war">
    <mcpServer asyncTimeout="2m"/>
</application>