tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-mcp

Quarkus extension for integrating Model Context Protocol (MCP) client capabilities with LangChain4j

Overview

Eval results

Files

AI Service Integration

Name: tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-mcp
Author: tessl

Enable MCP tools in LangChain4j AI services using declarative annotations. The @McpToolBox annotation controls which MCP servers provide tools to specific AI service methods, allowing fine-grained control over tool availability.

Capabilities

McpToolBox Annotation

The @McpToolBox annotation is applied to methods in AI services annotated with @RegisterAiService. It specifies which MCP servers' tools should be available to that method.

package io.quarkiverse.langchain4j.mcp.runtime;

@Retention(RetentionPolicy.RUNTIME)
@Target({ ElementType.METHOD })
public @interface McpToolBox {
    /**
     * MCP servers to use. Empty array means use all configured MCP servers.
     */
    String[] value() default {};
}

Parameters:

value() - Array of MCP server names to enable. If empty or not specified, all configured MCP servers will be used.

Usage: Apply to methods in @RegisterAiService interfaces to enable MCP tools for that specific method.

Single MCP Server

Enable tools from a specific MCP server:

import io.quarkiverse.langchain4j.RegisterAiService;
import io.quarkiverse.langchain4j.mcp.runtime.McpToolBox;
import dev.langchain4j.service.UserMessage;

@RegisterAiService
public interface FileAssistant {
    @McpToolBox("filesystem")
    String manageFiles(@UserMessage String message);
}

Configuration:

quarkus.langchain4j.mcp.filesystem.transport-type=stdio
quarkus.langchain4j.mcp.filesystem.command=npm,exec,@modelcontextprotocol/server-filesystem,/path

Multiple MCP Servers

Enable tools from multiple specific MCP servers:

@RegisterAiService
public interface DevelopmentAssistant {
    @McpToolBox({"github", "filesystem", "database"})
    String developFeature(@UserMessage String request);
}

Configuration:

# GitHub MCP server
quarkus.langchain4j.mcp.github.transport-type=streamable-http
quarkus.langchain4j.mcp.github.url=https://github-mcp.example.com/mcp

# Filesystem MCP server
quarkus.langchain4j.mcp.filesystem.transport-type=stdio
quarkus.langchain4j.mcp.filesystem.command=npm,exec,@modelcontextprotocol/server-filesystem,/workspace

# Database MCP server
quarkus.langchain4j.mcp.database.transport-type=stdio
quarkus.langchain4j.mcp.database.command=python,mcp-server-postgres.py

All Configured Servers

Enable tools from all configured MCP servers (empty array):

@RegisterAiService
public interface UniversalAssistant {
    @McpToolBox  // Empty = all servers
    String handleAnyTask(@UserMessage String userMessage);
}

Different Tools Per Method

Use different MCP server combinations for different methods:

@RegisterAiService
public interface SmartAssistant {
    // Only filesystem tools
    @McpToolBox("filesystem")
    String readFiles(@UserMessage String message);

    // Only GitHub tools
    @McpToolBox("github")
    String manageRepositories(@UserMessage String message);

    // Both filesystem and GitHub tools
    @McpToolBox({"filesystem", "github"})
    String developCode(@UserMessage String message);

    // All configured tools
    @McpToolBox
    String handleAnything(@UserMessage String message);
}

Without McpToolBox

If no @McpToolBox annotation is present, the method will NOT use any MCP tools:

@RegisterAiService
public interface BasicAssistant {
    // No MCP tools available - only built-in capabilities
    String chat(@UserMessage String message);

    // MCP tools from "filesystem" server available
    @McpToolBox("filesystem")
    String chatWithFileAccess(@UserMessage String message);
}

Tool Provider Generation

The extension automatically generates a ToolProvider bean that integrates all configured MCP clients. This can be controlled via configuration:

# Enable automatic tool provider generation (default: true)
quarkus.langchain4j.mcp.generate-tool-provider=true

When generate-tool-provider is true:

The extension creates a QuarkusMcpToolProvider bean
@McpToolBox annotations filter which MCP clients are used per method
Tools are dynamically discovered from MCP servers at runtime

When generate-tool-provider is false:

No automatic tool provider is created
You must provide a custom ToolProvider implementation
@McpToolBox annotations have no effect
Custom provider must handle MCP client wiring

Integration with LangChain4j

The MCP extension integrates seamlessly with LangChain4j's AI service framework:

import io.quarkiverse.langchain4j.RegisterAiService;
import dev.langchain4j.service.SystemMessage;
import dev.langchain4j.service.UserMessage;
import dev.langchain4j.service.MemoryId;

@RegisterAiService
public interface CodeReviewAssistant {
    @SystemMessage("You are a code review assistant with access to GitHub and filesystem tools.")
    @McpToolBox({"github", "filesystem"})
    String reviewPullRequest(
        @MemoryId String userId,
        @UserMessage String reviewRequest
    );
}

The AI service can now:

Access the conversation through LangChain4j's memory system
Use tools from the specified MCP servers (github, filesystem)
Execute function calls against MCP servers as needed
Return results to the user

Resources as Tools

When expose-resources-as-tools is enabled, MCP resources are exposed as synthetic tools:

quarkus.langchain4j.mcp.expose-resources-as-tools=true

This creates two additional tools:

list_resources - Lists available resources from MCP servers
get_resource - Retrieves content of a specific resource

These tools are available to any method with @McpToolBox:

@RegisterAiService
public interface ResourceAssistant {
    @McpToolBox("content-server")
    String accessContent(@UserMessage String query);
    // Can now use list_resources and get_resource tools
}

OpenTelemetry Tracing

When OpenTelemetry is present, tool executions are automatically traced:

@RegisterAiService
public interface TracedAssistant {
    @McpToolBox("filesystem")
    String processFiles(@UserMessage String message);
    // Tool calls are automatically traced with spans
}

No additional configuration needed - tracing is automatic when OpenTelemetry is on the classpath.

Important Notes

@McpToolBox only works with the auto-generated ToolProvider (when generate-tool-provider=true)
MCP server names in @McpToolBox must match configuration keys (e.g., quarkus.langchain4j.mcp.<name>)
Empty @McpToolBox enables all configured servers
Methods without @McpToolBox have NO access to MCP tools
Tool discovery happens at runtime - servers must be available when the method is called
Tools are cached by default (configurable per client via cache-tool-list)

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-mcp

docs

ai-service-integration.md

tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-mcp