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

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

Overview

Eval results

Files

Configuration

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

Comprehensive configuration options for MCP clients, including build-time and runtime settings, transport configuration, timeouts, logging, and health checks.

Capabilities

Runtime Configuration Root

Main runtime configuration interface for MCP extension.

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

@ConfigRoot(phase = ConfigPhase.RUN_TIME)
@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
public interface McpRuntimeConfiguration {
    /**
     * Configured MCP clients (map key is client name)
     */
    Map<String, McpClientRuntimeConfig> clients();

    /**
     * Configured MCP registry clients (map key is registry client name)
     */
    Map<String, McpRegistryClientRuntimeConfig> registryClients();

    /**
     * Whether resources should be exposed as MCP tools.
     * Default: false
     */
    Optional<Boolean> exposeResourcesAsTools();
}

Build-Time Configuration Root

Main build-time configuration interface for MCP extension.

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

@ConfigRoot(phase = ConfigPhase.BUILD_AND_RUN_TIME_FIXED)
@ConfigMapping(prefix = "quarkus.langchain4j.mcp")
public interface McpBuildTimeConfiguration {
    /**
     * Configured MCP clients (map key is client name)
     */
    Map<String, McpClientBuildTimeConfig> clients();

    /**
     * Configured MCP registry clients (map key is registry client name)
     */
    Map<String, Map<String, String>> registryClients();

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

    /**
     * Path to Claude Desktop config file for importing MCP server configurations.
     */
    Optional<String> configFile();

    /**
     * Whether MicroProfile health checks are enabled.
     * Default: true
     */
    boolean mpHealthEnabled();
}

Client Build-Time Configuration

Build-time configuration for individual MCP clients.

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

public interface McpClientBuildTimeConfig {
    /**
     * MCP transport type.
     * Default: STDIO
     */
    McpTransportType transportType();

    /**
     * Whether metrics are enabled for this client.
     * Default: false
     */
    boolean metricsEnabled();
}

Client Runtime Configuration

Runtime configuration for individual MCP clients.

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

public interface McpClientRuntimeConfig {
    /**
     * MCP server URL (for HTTP/WebSocket transports).
     */
    Optional<String> url();

    /**
     * Command to spawn MCP server process (for STDIO transport).
     * Example: ["npm", "exec", "@modelcontextprotocol/server-filesystem", "/path"]
     */
    Optional<List<String>> command();

    /**
     * Environment variables for spawned process.
     */
    Map<String, String> environment();

    /**
     * Whether to log MCP requests.
     */
    Optional<Boolean> logRequests();

    /**
     * Whether to log MCP responses.
     */
    Optional<Boolean> logResponses();

    /**
     * Whether to use MicroProfile health checks.
     * For HTTP-based transports, uses the MicroProfile health endpoint on the server.
     * Default: false
     */
    boolean microprofileHealthCheck();

    /**
     * Path to MicroProfile health check endpoint.
     * Default: /q/health
     */
    String microprofileHealthCheckPath();

    /**
     * Tool execution timeout.
     * Default: 60s
     */
    Duration toolExecutionTimeout();

    /**
     * Resource operations timeout.
     * Default: 60s
     */
    Duration resourcesTimeout();

    /**
     * Ping timeout.
     * Default: 10s
     */
    Duration pingTimeout();

    /**
     * Initial MCP roots (key=value pairs).
     */
    Optional<List<String>> roots();

    /**
     * Name of the TLS configuration bucket.
     */
    Optional<String> tlsConfigurationName();

    /**
     * Whether to cache the tool list from the MCP server.
     * When true, tools are retrieved once and cached.
     * When false, tools are fetched on every request.
     * Default: true
     */
    Optional<Boolean> cacheToolList();
}

Registry Client Configuration

Runtime configuration for MCP registry clients.

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

public interface McpRegistryClientRuntimeConfig {
    /**
     * Registry base URL.
     * Default: https://registry.modelcontextprotocol.io
     */
    String baseUrl();

    /**
     * Whether to log registry requests.
     */
    Optional<Boolean> logRequests();

    /**
     * Whether to log registry responses.
     */
    Optional<Boolean> logResponses();

    /**
     * Name of the TLS configuration bucket.
     */
    Optional<String> tlsConfigurationName();

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

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

Transport Type

Enumeration of supported MCP transport types.

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

public enum McpTransportType {
    /**
     * Local subprocess communication via stdin/stdout.
     */
    STDIO,

    /**
     * HTTP with separate SSE channel (dual-channel).
     */
    HTTP,

    /**
     * HTTP with inline SSE streaming (single-channel, recommended).
     */
    STREAMABLE_HTTP,

    /**
     * WebSocket transport (non-standard).
     */
    WEBSOCKET
}

Local Launch Parameters

Record holding launch parameters for local MCP servers.

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

public record LocalLaunchParams(
    /**
     * Command and arguments to execute.
     */
    List<String> command,

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

Configuration Examples

STDIO Transport (Local Server)

Spawn a local MCP server as a subprocess:

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

# With environment variables
quarkus.langchain4j.mcp.database.transport-type=stdio
quarkus.langchain4j.mcp.database.command=python,/opt/mcp/server.py
quarkus.langchain4j.mcp.database.environment.DB_HOST=localhost
quarkus.langchain4j.mcp.database.environment.DB_PORT=5432
quarkus.langchain4j.mcp.database.environment.DB_NAME=mydb

Streamable HTTP Transport (Recommended)

Single-connection HTTP with inline SSE:

quarkus.langchain4j.mcp.github.transport-type=streamable-http
quarkus.langchain4j.mcp.github.url=https://mcp.github.example.com/api/mcp

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

HTTP Transport (Dual-Channel)

HTTP with separate SSE channel:

quarkus.langchain4j.mcp.api.transport-type=http
quarkus.langchain4j.mcp.api.url=https://api.example.com/mcp/sse

WebSocket Transport

WebSocket-based transport:

quarkus.langchain4j.mcp.realtime.transport-type=websocket
quarkus.langchain4j.mcp.realtime.url=ws://localhost:8080/mcp

Authentication Headers

Static authentication headers:

quarkus.langchain4j.mcp.github.header.Authorization=Bearer ghp_xxxxxxxxx
quarkus.langchain4j.mcp.github.header.X-API-Key=my-api-key
quarkus.langchain4j.mcp.github.header.X-Custom-Header=value

TLS Configuration

Reference named TLS configuration:

quarkus.langchain4j.mcp.secure-api.transport-type=streamable-http
quarkus.langchain4j.mcp.secure-api.url=https://secure.example.com/mcp
quarkus.langchain4j.mcp.secure-api.tls-configuration-name=my-tls-config

# TLS configuration
quarkus.tls.my-tls-config.trust-store.p12.path=/certs/truststore.p12
quarkus.tls.my-tls-config.trust-store.p12.password=changeit

Logging Configuration

Enable request/response logging:

quarkus.langchain4j.mcp.github.log-requests=true
quarkus.langchain4j.mcp.github.log-responses=true

Health Check Configuration

Configure health checks:

# Disable health checks globally
quarkus.langchain4j.mcp.mp-health-enabled=false

# Disable for specific client
quarkus.langchain4j.mcp.github.microprofile-health-check=false

# Custom health check path
quarkus.langchain4j.mcp.github.microprofile-health-check-path=/health/ready

Metrics Configuration

Enable metrics for specific clients:

quarkus.langchain4j.mcp.github.metrics-enabled=true
quarkus.langchain4j.mcp.database.metrics-enabled=true

Tool Caching

Control tool list caching:

# Disable caching (fetch fresh on every use)
quarkus.langchain4j.mcp.github.cache-tool-list=false

Resources as Tools

Expose MCP resources as synthetic tools:

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

Creates list_resources and get_resource tools automatically.

Tool Provider Generation

Control automatic tool provider generation:

# Disable automatic generation (use custom ToolProvider)
quarkus.langchain4j.mcp.generate-tool-provider=false

Claude Desktop Config Import

Import MCP server configurations from Claude Desktop config file:

quarkus.langchain4j.mcp.config-file=/Users/username/Library/Application Support/Claude/claude_desktop_config.json

The extension will parse the config file and create MCP clients for all servers defined in it.

Claude Desktop Config Format:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/workspace"],
      "env": {
        "NODE_ENV": "production"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxx"
      }
    }
  }
}

Default Locations:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

What Gets Imported:

Server name becomes MCP client name
command becomes quarkus.langchain4j.mcp.<name>.command (with args appended)
env becomes quarkus.langchain4j.mcp.<name>.environment.*
Transport type is automatically set to stdio

Example Imported Configuration:

From the Claude Desktop config above, the extension automatically configures:

# Filesystem server (from Claude config)
quarkus.langchain4j.mcp.filesystem.transport-type=stdio
quarkus.langchain4j.mcp.filesystem.command=npx,-y,@modelcontextprotocol/server-filesystem,/Users/username/workspace
quarkus.langchain4j.mcp.filesystem.environment.NODE_ENV=production

# GitHub server (from Claude config)
quarkus.langchain4j.mcp.github.transport-type=stdio
quarkus.langchain4j.mcp.github.command=npx,-y,@modelcontextprotocol/server-github
quarkus.langchain4j.mcp.github.environment.GITHUB_TOKEN=ghp_xxxxxxxxxxxxx

Combining with Manual Configuration:

You can combine Claude Desktop config import with manual configuration. Manual settings take precedence:

# Import from Claude Desktop
quarkus.langchain4j.mcp.config-file=/Users/username/Library/Application Support/Claude/claude_desktop_config.json

# Override specific settings
quarkus.langchain4j.mcp.filesystem.tool-execution-timeout=30s
quarkus.langchain4j.mcp.filesystem.metrics-enabled=true

Config Source Provider:

The extension uses ClaudeDesktopConfigSourceProvider to load and parse Claude Desktop config files at build time. This is a Quarkus ConfigSource that reads the JSON file and converts it to Quarkus configuration properties.

Registry Client Configuration

Configure MCP registry client:

# Default registry
quarkus.langchain4j.mcp.registry-client.default.base-url=https://registry.modelcontextprotocol.io
quarkus.langchain4j.mcp.registry-client.default.read-timeout=15s
quarkus.langchain4j.mcp.registry-client.default.connect-timeout=10s
quarkus.langchain4j.mcp.registry-client.default.log-requests=true

# Custom registry
quarkus.langchain4j.mcp.registry-client.custom.base-url=https://my-registry.example.com
quarkus.langchain4j.mcp.registry-client.custom.tls-configuration-name=custom-tls

Initial Roots

Provide initial MCP roots to servers:

quarkus.langchain4j.mcp.filesystem.roots=rootDir=/workspace,tempDir=/tmp

Complete Example

Full configuration for multiple MCP servers:

# Filesystem server (STDIO)
quarkus.langchain4j.mcp.filesystem.transport-type=stdio
quarkus.langchain4j.mcp.filesystem.command=npm,exec,@modelcontextprotocol/server-filesystem,/workspace
quarkus.langchain4j.mcp.filesystem.tool-execution-timeout=30s
quarkus.langchain4j.mcp.filesystem.log-requests=true
quarkus.langchain4j.mcp.filesystem.metrics-enabled=true

# GitHub server (Streamable HTTP)
quarkus.langchain4j.mcp.github.transport-type=streamable-http
quarkus.langchain4j.mcp.github.url=https://github-mcp.example.com/mcp
quarkus.langchain4j.mcp.github.tool-execution-timeout=60s
quarkus.langchain4j.mcp.github.header.Authorization=Bearer ${GITHUB_TOKEN}
quarkus.langchain4j.mcp.github.metrics-enabled=true

# Database server (STDIO with env vars)
quarkus.langchain4j.mcp.database.transport-type=stdio
quarkus.langchain4j.mcp.database.command=python,/opt/mcp-db/server.py
quarkus.langchain4j.mcp.database.environment.DB_HOST=localhost
quarkus.langchain4j.mcp.database.environment.DB_PORT=5432
quarkus.langchain4j.mcp.database.environment.DB_USER=admin
quarkus.langchain4j.mcp.database.environment.DB_PASSWORD=${DB_PASSWORD}

# Global settings
quarkus.langchain4j.mcp.expose-resources-as-tools=true
quarkus.langchain4j.mcp.generate-tool-provider=true
quarkus.langchain4j.mcp.mp-health-enabled=true

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

Configuration Property Naming

MCP client names in configuration must be used consistently:

# Client name is "my-client"
quarkus.langchain4j.mcp.my-client.transport-type=stdio
quarkus.langchain4j.mcp.my-client.command=...

Reference in code:

@McpToolBox("my-client")  // Must match config key
String chat(@UserMessage String message);

@Inject
@McpClientName("my-client")  // Must match config key
McpClient client;

For client names with dots, quote them in configuration:

quarkus.langchain4j.mcp."io.example.client".transport-type=stdio

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

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

Capabilities

Runtime Configuration Root

Build-Time Configuration Root

Client Build-Time Configuration

Client Runtime Configuration

Registry Client Configuration

Transport Type

Local Launch Parameters

Configuration Examples

STDIO Transport (Local Server)

Streamable HTTP Transport (Recommended)

HTTP Transport (Dual-Channel)

WebSocket Transport

Authentication Headers

TLS Configuration

Logging Configuration

Health Check Configuration

Metrics Configuration

Tool Caching

Resources as Tools

Tool Provider Generation

Claude Desktop Config Import

Registry Client Configuration

Initial Roots

Complete Example

Configuration Property Naming

configuration.mddocs/