Quarkus LangChain4j MCP Deployment

Quarkus build-time deployment extension for Model Context Protocol (MCP) client integration. This module handles build-time processing, configuration management, synthetic CDI bean generation, and integration with Quarkus ecosystem features including health checks, metrics, and DevUI.

Package Information

• Group ID: io.quarkiverse.langchain4j
• Artifact ID: quarkus-langchain4j-mcp-deployment
• Package Type: Quarkus Deployment Extension
• Language: Java
• Installation: Add the runtime dependency (deployment is included automatically):

<dependency>
    <groupId>io.quarkiverse.langchain4j</groupId>
    <artifactId>quarkus-langchain4j-mcp</artifactId>
</dependency>

Core Concepts

This is a Quarkus deployment module, which means it operates at build time to:

1. Parse Configuration - Reads MCP client configuration from application.properties and optional Claude Desktop config files
2. Generate Synthetic Beans - Creates CDI beans for MCP clients, registry clients, and tool providers
3. Register Integrations - Sets up health checks, metrics, DevUI components, and reflection for native compilation
4. Process Build Items - Produces and consumes Quarkus build items for extension integration

The deployment module works with the runtime module (quarkus-langchain4j-mcp) to provide complete MCP functionality.

Basic Usage

Application Configuration

Configure MCP clients in application.properties:

# Configure a GitHub MCP server using STDIO transport
quarkus.langchain4j.mcp.github.transport-type=stdio
quarkus.langchain4j.mcp.github.command=npm,exec,@modelcontextprotocol/server-github
quarkus.langchain4j.mcp.github.environment.GITHUB_PERSONAL_ACCESS_TOKEN=your_token

# Configure a remote MCP server using HTTP transport
quarkus.langchain4j.mcp.remote.transport-type=streamable-http
quarkus.langchain4j.mcp.remote.url=https://mcp-server.example.com/mcp

# Auto-generate ToolProvider (default: true)
quarkus.langchain4j.mcp.generate-tool-provider=true

Using Generated MCP Clients

MCP clients are automatically generated as CDI beans qualified with @McpClientName:

import dev.langchain4j.mcp.client.McpClient;
import io.quarkiverse.langchain4j.mcp.runtime.McpClientName;
import jakarta.inject.Inject;

@ApplicationScoped
public class McpService {
    @Inject
    @McpClientName("github")
    McpClient githubClient;

    public void useClient() {
        var tools = githubClient.listTools();
        // ... use tools
    }
}

Using MCP Tools in AI Services

Use the @McpToolBox annotation to enable MCP tools in AI service methods:

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

@RegisterAiService
public interface GitHubAssistant {
    @McpToolBox("github")
    String chat(@UserMessage String message);
}

Architecture

Build-Time vs Runtime

Build Time (This Module):

• Parses configuration and generates synthetic CDI beans
• Registers reflection for native compilation
• Sets up health checks and DevUI integration
• Processes Claude Desktop configuration files

Runtime (quarkus-langchain4j-mcp):

• Initializes MCP clients with configured transports
• Handles tool discovery and execution
• Manages authentication and observability
• Provides tool provider for AI services

Synthetic Bean Generation

The deployment module generates the following CDI beans:

1. MCP Client Beans - One per configured client, qualified with @McpClientName
2. Registry Client Beans - One per registry configuration, qualified with @McpRegistryClientName
3. ToolProvider Bean - Aggregates tools from all MCP clients (optional, generated when generate-tool-provider=true)

Transport Support

Supports multiple MCP transport types:

• STDIO - Local subprocess communication
• HTTP - Server-Sent Events (legacy)
• Streamable HTTP - Modern HTTP transport (recommended)
• WebSocket - For quarkus-mcp-server compatibility

Capabilities

Configuration Management

Complete configuration system for MCP clients, registry clients, and tool provider generation.

// Build-time configuration interface
@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
@ConfigRoot(phase = BUILD_AND_RUN_TIME_FIXED)
interface McpBuildTimeConfiguration {
    Map<String, McpClientBuildTimeConfig> clients();
    Map<String, Map<String, String>> registryClients();
    Optional<Boolean> generateToolProvider();
    Optional<String> configFile();
    boolean mpHealthEnabled();
}

// Runtime configuration interface
@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
@ConfigRoot(phase = RUN_TIME)
interface McpRuntimeConfiguration {
    Map<String, McpClientRuntimeConfig> clients();
    Map<String, McpRegistryClientRuntimeConfig> registryClients();
    Optional<Boolean> exposeResourcesAsTools();
}

Configuration Reference

Build-Time Processing

Build processors and build items for Quarkus extension integration.

// Main build processor
class McpProcessor {
    @BuildStep
    void generateMcpConfigFileContents(
        McpBuildTimeConfiguration config,
        BuildProducer<McpConfigFileContentsBuildItem> producer
    );

    @BuildStep
    @Record(ExecutionTime.RUNTIME_INIT)
    void registerMcpClients(
        McpBuildTimeConfiguration config,
        BuildProducer<SyntheticBeanBuildItem> beanProducer,
        BuildProducer<HealthBuildItem> healthProducer,
        McpRecorder recorder
    );
}

// Build item for Claude Desktop config
class McpConfigFileContentsBuildItem extends SimpleBuildItem {
    Map<String, LocalLaunchParams> getContents();
}

Build-Time API Reference

Qualifiers and Annotations

CDI qualifiers and functional annotations for MCP client selection and tool integration.

// Qualifier for selecting specific MCP client
@Qualifier
@Retention(RUNTIME)
@Target({TYPE, METHOD, FIELD, PARAMETER})
@Repeatable(McpClientNames.class)
@interface McpClientName {
    String value();
}

// Qualifier for selecting registry client
@Qualifier
@Retention(RUNTIME)
@Target({TYPE, METHOD, FIELD, PARAMETER})
@interface McpRegistryClientName {
    String value();
}

// Annotation for enabling MCP tools in AI service methods
@Retention(RUNTIME)
@Target(METHOD)
@interface McpToolBox {
    String[] value() default {};
}

Annotations Reference

Runtime Integration

Runtime classes for health checks, authentication, observability, and tool provision.

// Health check for MCP clients
@Readiness
class McpClientHealthCheck implements HealthCheck {
    HealthCheckResponse call();
}

// Authentication provider SPI
interface McpClientAuthProvider {
    String getAuthorization(Input input);

    interface Input {
        String method();
        URI uri();
        Map<String, List<Object>> headers();
    }
}

// Tool provider integrating MCP clients
class QuarkusMcpToolProvider extends McpToolProvider {
    // Automatically generated when generate-tool-provider=true
}

Runtime Integration Reference

DevUI Integration

Development UI components for testing and monitoring MCP clients.

// JSON-RPC service for DevUI
class McpClientsJsonRpcService {
    List<McpClientInfo> clientInfos();
    String executeTool(String clientName, String toolName, String arguments);
}

// DevUI data models (simplified)
class McpClientInfo {
    String getCdiName();
    List<McpToolInfo> getTools();
}
class McpToolInfo {
    String getName();
    String getDescription();
    List<McpToolArgInfo> getArgs();
}
class McpToolArgInfo {
    String getName();
    String getType();
    boolean isRequired();
}

Access DevUI at http://localhost:8080/q/dev-ui in development mode to explore and test MCP clients interactively.

Observability Support

Built-in integration with Quarkus observability stack:

Health Checks:

• Automatic registration with SmallRye Health
• Ping/pong verification for all MCP clients
• Optional MicroProfile health endpoint check for HTTP servers

Metrics (Micrometer):

• Tool execution duration and outcome
• Resource retrieval duration
• Prompt retrieval duration

Tracing (OpenTelemetry):

• Tool execution spans
• MCP protocol operation spans

Logging:

• Request/response logging (configurable per client)
• MCP server log messages (observable via CDI events)

Native Compilation Support

Automatic configuration for GraalVM native images:

• Reflection registration for MCP protocol classes
• Runtime initialization of optional dependencies (Micrometer)
• JSON serialization/deserialization support

Extension Points

For Application Developers

1. Custom Authentication: Implement McpClientAuthProvider interface

@ApplicationScoped
@McpClientName("private-server")
class CustomAuthProvider implements McpClientAuthProvider {
    String getAuthorization(Input input) {
        return "Bearer " + getCustomToken();
    }
}

2. Log Event Handling: Observe MCP log messages via CDI events

@ApplicationScoped
class McpLogObserver {
    void onGitHubLog(@Observes @McpClientName("github") McpLogMessage log) {
        // Custom log handling
    }
}

For Extension Developers

1. Consume Build Items: Access parsed configuration in custom build steps

@BuildStep
void customProcessing(Optional<McpConfigFileContentsBuildItem> configItem) {
    if (configItem.isPresent()) {
        var contents = configItem.get().getContents();
        // Custom processing
    }
}

2. Inject Generated Beans: Use generated MCP clients in custom extensions

@Inject
@McpClientName("github")
McpClient client;

Dependencies

Core Dependencies:

• io.quarkiverse.langchain4j:quarkus-langchain4j-mcp (runtime module)
• dev.langchain4j:langchain4j-mcp (MCP client implementation)
• io.quarkus:quarkus-rest-client-jackson (HTTP transport)

Optional Dependencies:

• io.quarkus:quarkus-smallrye-health - Health check integration
• io.quarkus:quarkus-micrometer-registry-* - Metrics integration
• io.quarkus:quarkus-opentelemetry - Tracing integration
• io.quarkiverse.langchain4j:quarkus-langchain4j-oidc-mcp-auth-provider - OIDC auth propagation

Related Documentation

• Official MCP Documentation: https://modelcontextprotocol.io/
• LangChain4j MCP Guide: https://docs.langchain4j.dev/tutorials/mcp
• Quarkus LangChain4j Docs: https://docs.quarkiverse.io/quarkus-langchain4j/dev/
• MCP Registry: https://registry.modelcontextprotocol.io/