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.
With this generated tool provider, by default an AI Service won’t use any of the tools provided
by any of the configured MCP servers. To enable a method of an AI service to use the MCP servers
it is required to annotate it with @McpToolBox. This annotation allows to specify the list of
MCP servers that the AI service can use. For example to enable a method to use the github MCP
server configured above and only that one it is necessary to annotate it with:
@McpToolBox("github")
String useGithub(@UserMessage String userMessage);If the @McpToolBox is used without any name then the method will automatically use all the MCP
servers available.
Authorization
MCP servers that use the "Streamable HTTP" or HTTP/SSE transport may require MCP client authorization.
In such cases, MCP clients must submit access tokens or API keys as bearer access tokens using an HTTP Authorization header, for example: Authorization: Bearer <access token>.
You can register a custom io.quarkiverse.langchain4j.mcp.auth.McpClientAuthProvider to load tokens or API keys from the database or other sources, for example:
import jakarta.enterprise.context.ApplicationScoped;
import io.quarkiverse.langchain4j.mcp.auth.McpClientAuthProvider;
@ApplicationScoped
public static class TestMcpAuthProvider implements McpClientAuthProvider {
@Override
public String getAuthorization(Input input) { (1)
String token = getToken(input);
return "Bearer " + token;
}
private String getToken(Input input) {
// ...
}
}| 1 | Represents current HTTP request URI, method and headers |
When your Quarkus LangChain4j AI service application that uses MCP client requires an OpenId Connect or OAuth2 authorization code flow login, for example, with Google or GitHub, MCP client can propagate the acquired access token to access the MCP server on the authenticated user’s behalf.
All you need to do to achieve it is to add the quarkus-langchain4j-oidc-mcp-auth-provider dependency:
<dependency>
<groupId>io.quarkiverse.langchain4j</groupId>
<artifactId>quarkus-langchain4j-oidc-mcp-auth-provider</artifactId>
</dependency>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 |
|---|---|---|
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: |
boolean |
|
File containing the MCP servers configuration in the Claude Desktop format. This configuration can only be used to configure 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: |
string |
|
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: |
boolean |
|
Type |
Default |
|
Transport type Environment variable: |
|
|
The URL of the SSE endpoint. This only applies to MCP clients using the HTTP transport. Environment variable: |
string |
|
The command to execute to spawn the MCP server process. This only applies to MCP clients using the STDIO transport. Environment variable: |
list of string |
|
Environment variables for the spawned MCP server process. This only applies to MCP clients using the STDIO transport. Environment variable: |
Map<String,String> |
|
Whether to log requests Environment variable: |
boolean |
|
Whether to log responses Environment variable: |
boolean |
|
Timeout for tool executions performed by the MCP client Environment variable: |
|
|
Timeout for resource-related operations (retrieving a list of resources as well as the actual contents of resources). Environment variable: |
|
|
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: |
|
|
About the Duration format
To write duration values, use the standard You can also use a simplified format, starting with a number:
In other cases, the simplified format is translated to the
|