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

Quarkus build-time deployment extension for Model Context Protocol (MCP) client integration, handling configuration processing, synthetic bean generation, and framework integration

Overview

Eval results

Files

Configuration Reference

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

Complete configuration API for the Quarkus LangChain4j MCP deployment extension.

Configuration Overview

The MCP extension uses two configuration phases:

Build-Time Fixed - Configuration that determines bean generation and cannot change at runtime
Runtime - Configuration that can be overridden at application startup

Build-Time Configuration

McpBuildTimeConfiguration

Root configuration interface for build-time settings.

package io.quarkiverse.langchain4j.mcp.runtime.config;

@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
@ConfigRoot(phase = BUILD_AND_RUN_TIME_FIXED)
interface McpBuildTimeConfiguration {
    /**
     * Named MCP client configurations.
     * Each key represents a client name used for @McpClientName qualifiers.
     */
    Map<String, McpClientBuildTimeConfig> clients();

    /**
     * Named MCP registry client configurations.
     * Each key represents a registry client name used for @McpRegistryClientName qualifiers.
     */
    Map<String, Map<String, String>> registryClients();

    /**
     * Whether to automatically generate a ToolProvider bean.
     * Default: true if any clients are configured, false otherwise.
     */
    Optional<Boolean> generateToolProvider();

    /**
     * Path to Claude Desktop configuration file (relative to classpath).
     * If specified, STDIO MCP servers from this file are automatically configured.
     */
    Optional<String> configFile();

    /**
     * Whether to enable MicroProfile Health integration.
     * Default: true
     */
    boolean mpHealthEnabled();
}

Configuration Example:

# Named client configurations
quarkus.langchain4j.mcp.github.transport-type=stdio
quarkus.langchain4j.mcp.remote.transport-type=streamable-http

# Registry clients
quarkus.langchain4j.mcp.registry-client.official.base-url=https://registry.modelcontextprotocol.io

# Auto-generate ToolProvider
quarkus.langchain4j.mcp.generate-tool-provider=true

# Claude Desktop config file
quarkus.langchain4j.mcp.config-file=claude_desktop_config.json

# Health check integration
quarkus.langchain4j.mcp.health.enabled=true

McpClientBuildTimeConfig

Per-client build-time configuration group.

package io.quarkiverse.langchain4j.mcp.runtime.config;

@ConfigGroup
interface McpClientBuildTimeConfig {
    /**
     * Transport protocol for this MCP client.
     * Default: STDIO
     */
    McpTransportType transportType();

    /**
     * Whether to enable Micrometer metrics for this client.
     * Only applies if Micrometer is available on the classpath.
     * Default: false
     */
    boolean metricsEnabled();
}

Configuration Example:

# Configure transport type
quarkus.langchain4j.mcp.github.transport-type=stdio
quarkus.langchain4j.mcp.remote.transport-type=streamable-http

# Enable metrics for specific client
quarkus.langchain4j.mcp.github.metrics.enabled=true

McpTransportType

Transport protocol enumeration.

package io.quarkiverse.langchain4j.mcp.runtime.config;

enum McpTransportType {
    /**
     * Standard input/output transport for local subprocess communication.
     * Most common for npm-based MCP servers.
     */
    STDIO,

    /**
     * HTTP with Server-Sent Events transport (legacy).
     * Use STREAMABLE_HTTP for new implementations.
     */
    HTTP,

    /**
     * Streamable HTTP transport (recommended for HTTP-based servers).
     * Implements modern MCP HTTP transport specification.
     */
    STREAMABLE_HTTP,

    /**
     * WebSocket transport (non-standard).
     * Supported for compatibility with quarkus-mcp-server.
     */
    WEBSOCKET
}

Runtime Configuration

McpRuntimeConfiguration

Root configuration interface for runtime settings.

package io.quarkiverse.langchain4j.mcp.runtime.config;

@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
@ConfigRoot(phase = RUN_TIME)
interface McpRuntimeConfiguration {
    /**
     * Runtime configuration for MCP clients.
     * Keys must match client names from build-time configuration.
     */
    Map<String, McpClientRuntimeConfig> clients();

    /**
     * Runtime configuration for MCP registry clients.
     * Keys must match registry names from build-time configuration.
     */
    Map<String, McpRegistryClientRuntimeConfig> registryClients();

    /**
     * Whether to expose MCP resources as callable tools.
     * When enabled, creates list_resources and get_resource tools.
     * Default: false
     */
    Optional<Boolean> exposeResourcesAsTools();
}

Configuration Example:

# Client runtime configuration
quarkus.langchain4j.mcp.github.command=npm,exec,@modelcontextprotocol/server-github
quarkus.langchain4j.mcp.remote.url=https://mcp-server.example.com/mcp

# Registry runtime configuration
quarkus.langchain4j.mcp.registry-client.official.base-url=https://registry.modelcontextprotocol.io

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

McpClientRuntimeConfig

Comprehensive runtime configuration for individual MCP clients.

package io.quarkiverse.langchain4j.mcp.runtime.config;

@ConfigGroup
interface McpClientRuntimeConfig {
    /**
     * HTTP/SSE endpoint URL for HTTP-based transports.
     * Required for HTTP, STREAMABLE_HTTP, and WEBSOCKET transports.
     */
    Optional<String> url();

    /**
     * Command to spawn STDIO server (command and arguments as comma-separated list).
     * Required for STDIO transport.
     * Example: npm,exec,@modelcontextprotocol/server-filesystem,/path/to/dir
     */
    Optional<List<String>> command();

    /**
     * Environment variables for STDIO subprocess.
     * Example: GITHUB_PERSONAL_ACCESS_TOKEN=token
     */
    Map<String, String> environment();

    /**
     * Whether to log HTTP requests.
     * Inherits from quarkus.langchain4j.log-requests if not specified.
     */
    Optional<Boolean> logRequests();

    /**
     * Whether to log HTTP responses.
     * Inherits from quarkus.langchain4j.log-responses if not specified.
     */
    Optional<Boolean> logResponses();

    /**
     * Use MicroProfile health endpoint instead of MCP ping for health checks.
     * Only applies to HTTP-based transports.
     * Default: false
     */
    boolean microprofileHealthCheck();

    /**
     * MicroProfile health endpoint path.
     * Default: /q/health
     */
    String microprofileHealthCheckPath();

    /**
     * Timeout for tool execution operations.
     * Default: 60s
     */
    Duration toolExecutionTimeout();

    /**
     * Timeout for resource operations (list and read).
     * Default: 60s
     */
    Duration resourcesTimeout();

    /**
     * Timeout for MCP ping operations during health checks.
     * Default: 10s
     */
    Duration pingTimeout();

    /**
     * Initial MCP workspace roots in key=value format.
     * Example: workspace1=/path/to/workspace1,workspace2=/path/to/workspace2
     */
    Optional<List<String>> roots();

    /**
     * TLS configuration name from Quarkus TLS registry.
     * Only applies to HTTP-based transports.
     */
    Optional<String> tlsConfigurationName();

    /**
     * Whether to cache the tool list and update on server notifications.
     * Disable for servers that don't support change notifications.
     * Default: true
     */
    Optional<Boolean> cacheToolList();
}

Configuration Example:

# STDIO transport configuration
quarkus.langchain4j.mcp.github.command=npm,exec,@modelcontextprotocol/server-github
quarkus.langchain4j.mcp.github.environment.GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}
quarkus.langchain4j.mcp.github.environment.GITHUB_API_URL=https://api.github.com

# HTTP transport configuration
quarkus.langchain4j.mcp.remote.url=https://mcp-server.example.com/mcp
quarkus.langchain4j.mcp.remote.tls-configuration-name=my-tls-config

# Logging configuration
quarkus.langchain4j.mcp.github.log-requests=true
quarkus.langchain4j.mcp.github.log-responses=true

# Health check configuration
quarkus.langchain4j.mcp.remote.microprofile-health-check=true
quarkus.langchain4j.mcp.remote.microprofile-health-check-path=/q/health

# Timeout configuration
quarkus.langchain4j.mcp.github.tool-execution-timeout=30s
quarkus.langchain4j.mcp.github.resources-timeout=60s
quarkus.langchain4j.mcp.github.ping-timeout=5s

# Workspace roots
quarkus.langchain4j.mcp.filesystem.roots=docs=/path/to/docs,src=/path/to/src

# Tool list caching
quarkus.langchain4j.mcp.github.cache-tool-list=true

McpRegistryClientRuntimeConfig

Runtime configuration for MCP registry clients.

package io.quarkiverse.langchain4j.mcp.runtime.config;

@ConfigGroup
interface McpRegistryClientRuntimeConfig {
    /**
     * Base URL of the MCP registry.
     * Default: https://registry.modelcontextprotocol.io
     */
    String baseUrl();

    /**
     * Whether to log HTTP requests to the registry.
     * Inherits from quarkus.langchain4j.log-requests if not specified.
     */
    Optional<Boolean> logRequests();

    /**
     * Whether to log HTTP responses from the registry.
     * Inherits from quarkus.langchain4j.log-responses if not specified.
     */
    Optional<Boolean> logResponses();

    /**
     * TLS configuration name from Quarkus TLS registry.
     */
    Optional<String> tlsConfigurationName();

    /**
     * HTTP read timeout.
     * Default: 10s
     */
    Optional<Duration> readTimeout();

    /**
     * HTTP connect timeout.
     * Default: 10s
     */
    Optional<Duration> connectTimeout();
}

Configuration Example:

# Registry client configuration
quarkus.langchain4j.mcp.registry-client.official.base-url=https://registry.modelcontextprotocol.io
quarkus.langchain4j.mcp.registry-client.official.read-timeout=10s
quarkus.langchain4j.mcp.registry-client.official.connect-timeout=5s
quarkus.langchain4j.mcp.registry-client.official.log-requests=true

# TLS configuration
quarkus.langchain4j.mcp.registry-client.official.tls-configuration-name=registry-tls

LocalLaunchParams

Data transfer object for STDIO launch parameters.

package io.quarkiverse.langchain4j.mcp.runtime.config;

/**
 * Launch parameters for STDIO MCP servers.
 * Parsed from Claude Desktop configuration files.
 */
record LocalLaunchParams(
    /**
     * Command and arguments to execute.
     */
    List<String> command,

    /**
     * Environment variables for subprocess.
     */
    Map<String, String> envVars
) {}

Note: The parsing of Claude Desktop configuration files is handled internally by ClaudeDesktopConfigSourceProvider, a Quarkus ConfigSourceProvider implementation that reads the config file and converts it to Quarkus configuration properties. This is an internal implementation detail not exposed in the public API.

Configuration Patterns

Multiple MCP Clients

Configure multiple MCP clients with different transports:

# GitHub MCP server (STDIO)
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=${GITHUB_TOKEN}

# Filesystem MCP server (STDIO)
quarkus.langchain4j.mcp.filesystem.transport-type=stdio
quarkus.langchain4j.mcp.filesystem.command=npm,exec,@modelcontextprotocol/server-filesystem,/home/user/docs

# Remote MCP server (HTTP)
quarkus.langchain4j.mcp.remote.transport-type=streamable-http
quarkus.langchain4j.mcp.remote.url=https://mcp-server.example.com/mcp

Claude Desktop Configuration File

Reuse existing Claude Desktop configuration:

# Reference Claude Desktop config file
quarkus.langchain4j.mcp.config-file=${user.home}/.config/claude/config.json

# Override runtime properties for servers from config file
quarkus.langchain4j.mcp.github.environment.GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}

Environment-Specific Configuration

Use profiles for different environments:

# Development
%dev.quarkus.langchain4j.mcp.github.log-requests=true
%dev.quarkus.langchain4j.mcp.github.log-responses=true

# Production
%prod.quarkus.langchain4j.mcp.github.tool-execution-timeout=120s
%prod.quarkus.langchain4j.mcp.github.ping-timeout=5s

TLS Configuration

Configure TLS for secure HTTP connections:

# MCP client TLS
quarkus.langchain4j.mcp.secure-server.tls-configuration-name=mcp-tls

# TLS configuration in Quarkus TLS registry
quarkus.tls.mcp-tls.trust-store.pem.certs=server-ca.pem
quarkus.tls.mcp-tls.key-store.pem.0.cert=client-cert.pem
quarkus.tls.mcp-tls.key-store.pem.0.key=client-key.pem

Configuration Resolution

Precedence Order

System properties (-Dquarkus.langchain4j.mcp.github.command=...)
Environment variables (QUARKUS_LANGCHAIN4J_MCP_GITHUB_COMMAND=...)
application.properties / application.yaml
Claude Desktop config file (for STDIO clients only)
Default values

Claude Desktop Config Integration

When config-file is specified:

STDIO MCP servers are automatically configured from the file
Runtime properties can override individual settings
Only mcpServers section is processed
Server names become MCP client names

Example Claude Desktop config:

{
  "mcpServers": {
    "github": {
      "command": "npm",
      "args": ["exec", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "token_here"
      }
    }
  }
}

Equivalent Quarkus configuration:

quarkus.langchain4j.mcp.config-file=claude_config.json
quarkus.langchain4j.mcp.github.environment.GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_TOKEN}

Configuration Validation

The deployment module validates configuration at build time:

Transport type: Must be specified for each client
URL requirement: HTTP/WebSocket transports require url property
Command requirement: STDIO transport requires command property
Client names: Must match between build-time and runtime configuration
Registry clients: Registry names must match between build-time and runtime

Build failures occur if required configuration is missing or invalid.

Install with Tessl CLI

npx tessl i tessl/maven-io-quarkiverse-langchain4j--quarkus-langchain4j-mcp-deployment@1.7.0

docs

runtime-integration.md

tile.json

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

configuration.md.css-3qkkll{font-size:var(--chakra-font-sizes-sm);font-weight:var(--chakra-font-weights-normal);color:var(--chakra-colors-gray-300);}docs/

Configuration Reference

Configuration Overview

Build-Time Configuration

McpBuildTimeConfiguration

McpClientBuildTimeConfig

McpTransportType

Runtime Configuration

McpRuntimeConfiguration

McpClientRuntimeConfig

McpRegistryClientRuntimeConfig

LocalLaunchParams

Configuration Patterns

Multiple MCP Clients

Claude Desktop Configuration File

Environment-Specific Configuration

TLS Configuration

Configuration Resolution

Precedence Order

Claude Desktop Config Integration

Configuration Validation

configuration.mddocs/