Model Context Protocol

LangChain4j supports the Model Context Protocol (MCP) to communicate with MCP compliant servers that can provide and execute tools. General information about the protocol can be found at the MCP website. More detailed information can also be found in the LangChain4j documentation, this documentation focuses on features that Quarkus provides on top of the upstream module. For an example project that uses MCP, see mcp-tools project in the quarkus-langchain4j repository.

There is also a Quarkus extension for developing MCP servers. See GitHub repo and documentation.

Declaratively generating a tool provider backed by MCP

Quarkus offers a way to generate a tool provider backed by one or more MCP servers declaratively from the configuration model. When using this, all AI services that don’t explicitly declare to use a different tool provider will then be wired up to it, without having to write any MCP-specific code in the AI service. Example:

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>

With this configuration, Quarkus will generate a tool provider that talks to the server-github MCP server. The server will be started automatically as a subprocess using the provided command (npm exec @modelcontextprotocol/server-github). The environment.* properties define environment variables that will be passed to the subprocess. With this configuration, any AI Service that does not declare a specific tool provider will be wired to this one.

Logging

For declaratively defined MCP clients, Quarkus overrides the default handler for received MCP logging messages with a handler that, apart from simply logging them with an application logger, produces a CDI event for each message. So if you need your application to react to MCP logging messages, you can observe these events in a CDI bean like this:

public void onLogMessage(@Observes @McpClientName("KEY") McpLogMessage logMessage) {
    // ...
}

The McpLogMessage class’s fully qualified name is dev.langchain4j.mcp.client.logging.McpLogMessage and it contains the log message as a JsonNode, the log level and the logger name.

The optional @McpClientName qualifier is used to specify the name of the MCP client that the log message is related to. This is useful when you have multiple MCP clients in your application and you want to react to log messages from a specific one.

Configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property	Type	Default
`quarkus.langchain4j.mcp.generate-tool-provider` Whether the MCP extension should automatically generate a ToolProvider that is wired up to all the configured MCP clients. The default is true if at least one MCP client is configured, false otherwise. Environment variable: `QUARKUS_LANGCHAIN4J_MCP_GENERATE_TOOL_PROVIDER`	boolean	`true`
`quarkus.langchain4j.mcp.config-file` File containing the MCP servers configuration in the Claude Desktop format. This configuration can only be used to configure `stdio` transport type MCP servers. This file is read at build time which means that which MCP servers the client will use, is determined at build time. However, specific configuration of each MCP server can be overridden at runtime. Environment variable: `QUARKUS_LANGCHAIN4J_MCP_CONFIG_FILE`	string
`quarkus.langchain4j.mcp.health.enabled` Whether the MCP extension should automatically register a health check for configured MCP clients. The default is true if at least one MCP client is configured, false otherwise. Environment variable: `QUARKUS_LANGCHAIN4J_MCP_HEALTH_ENABLED`	boolean	`true`
Configured MCP clients	Type	Default
`quarkus.langchain4j.mcp."client-name".transport-type` Transport type Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__TRANSPORT_TYPE`	`stdio`, `http`	`stdio`
`quarkus.langchain4j.mcp."client-name".url` The URL of the SSE endpoint. This only applies to MCP clients using the HTTP transport. Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__URL`	string
`quarkus.langchain4j.mcp."client-name".command` The command to execute to spawn the MCP server process. This only applies to MCP clients using the STDIO transport. Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__COMMAND`	list of string
`quarkus.langchain4j.mcp."client-name".environment."env-var"` Environment variables for the spawned MCP server process. This only applies to MCP clients using the STDIO transport. Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__ENVIRONMENT__ENV_VAR_`	Map<String,String>
`quarkus.langchain4j.mcp."client-name".log-requests` Whether to log requests Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__LOG_REQUESTS`	boolean	`false`
`quarkus.langchain4j.mcp."client-name".log-responses` Whether to log responses Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__LOG_RESPONSES`	boolean	`false`
`quarkus.langchain4j.mcp."client-name".tool-execution-timeout` Timeout for tool executions performed by the MCP client Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__TOOL_EXECUTION_TIMEOUT`	Duration	`60S`
`quarkus.langchain4j.mcp."client-name".resources-timeout` Timeout for resource-related operations (retrieving a list of resources as well as the actual contents of resources). Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__RESOURCES_TIMEOUT`	Duration	`60S`
`quarkus.langchain4j.mcp."client-name".ping-timeout` Timeout for pinging the MCP server process to check if it’s still alive. If a ping times out, the client’s health check will start failing. Environment variable: `QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__PING_TIMEOUT`	Duration	`10S`

Configuration property

Type

Default

quarkus.langchain4j.mcp.generate-tool-provider

Whether the MCP extension should automatically generate a ToolProvider that is wired up to all the configured MCP clients. The default is true if at least one MCP client is configured, false otherwise.

Environment variable: QUARKUS_LANGCHAIN4J_MCP_GENERATE_TOOL_PROVIDER

boolean

true

quarkus.langchain4j.mcp.config-file

File containing the MCP servers configuration in the Claude Desktop format. This configuration can only be used to configure stdio transport type MCP servers.

This file is read at build time which means that which MCP servers the client will use, is determined at build time. However, specific configuration of each MCP server can be overridden at runtime.

Environment variable: QUARKUS_LANGCHAIN4J_MCP_CONFIG_FILE

string

quarkus.langchain4j.mcp.health.enabled

Whether the MCP extension should automatically register a health check for configured MCP clients. The default is true if at least one MCP client is configured, false otherwise.

Environment variable: QUARKUS_LANGCHAIN4J_MCP_HEALTH_ENABLED

boolean

true

Configured MCP clients

Type

Default

quarkus.langchain4j.mcp."client-name".transport-type

Transport type

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__TRANSPORT_TYPE

stdio, http

stdio

quarkus.langchain4j.mcp."client-name".url

The URL of the SSE endpoint. This only applies to MCP clients using the HTTP transport.

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__URL

string

quarkus.langchain4j.mcp."client-name".command

The command to execute to spawn the MCP server process. This only applies to MCP clients using the STDIO transport.

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__COMMAND

list of string

quarkus.langchain4j.mcp."client-name".environment."env-var"

Environment variables for the spawned MCP server process. This only applies to MCP clients using the STDIO transport.

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__ENVIRONMENT__ENV_VAR_

Map<String,String>

quarkus.langchain4j.mcp."client-name".log-requests

Whether to log requests

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__LOG_REQUESTS

boolean

false

quarkus.langchain4j.mcp."client-name".log-responses

Whether to log responses

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__LOG_RESPONSES

boolean

false

quarkus.langchain4j.mcp."client-name".tool-execution-timeout

Timeout for tool executions performed by the MCP client

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__TOOL_EXECUTION_TIMEOUT

Duration

60S

quarkus.langchain4j.mcp."client-name".resources-timeout

Timeout for resource-related operations (retrieving a list of resources as well as the actual contents of resources).

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__RESOURCES_TIMEOUT

Duration

60S

quarkus.langchain4j.mcp."client-name".ping-timeout

Timeout for pinging the MCP server process to check if it’s still alive. If a ping times out, the client’s health check will start failing.

Environment variable: QUARKUS_LANGCHAIN4J_MCP__CLIENT_NAME__PING_TIMEOUT

Duration

10S

About the Duration format

To write duration values, use the standard java.time.Duration format. See the Duration#parse() Java API documentation for more information.

You can also use a simplified format, starting with a number:

If the value is only a number, it represents time in seconds.
If the value is a number followed by ms, it represents time in milliseconds.

In other cases, the simplified format is translated to the java.time.Duration format for parsing:

If the value is a number followed by h, m, or s, it is prefixed with PT.
If the value is a number followed by d, it is prefixed with P.