MCP

Model Context Protocol (MCP)

The Model Context Protocol (MCP) is an open protocol designed to connect AI models with external tools, resources, and data sources in a standardized way. An MCP server exposes resources, prompts, and tools that AI clients can discover and invoke dynamically, enabling more powerful and context-aware applications.

MCP Server

Helidon provides support for building Model Context Protocol (MCP) servers through a dedicated extension. The MCP Server feature is not part of the core Helidon Framework – it is delivered as a separate project hosted in the helidon-mcp GitHub repository.

Helidon MCP Server Extension

The Helidon MCP Server extension allows you to build and run MCP servers with Helidon.

Key points:

Separate repository: helidon-mcp
Independent lifecycle: Requires Helidon but has its own versioning and release cadence
Dedicated documentation: Full usage guides, configuration details, and examples are provided directly in the helidon-mcp documentation

To get started:

Visit the helidon-mcp GitHub repository.
Follow the setup and usage instructions in the repository’s documentation.
Explore how to expose your Helidon resources as MCP tools, prompts, and data sources.

MCP Client

Helidon includes support for an MCP client through its integration with LangChain4j. With this integration, you can set up the MCP client using Helidon configuration and plug it directly into your LangChain4j AI Services and Agents.

In LangChain4j, an MCP (Model Context Protocol) client acts as a bridge between the language model and external services or resources that follow the MCP standard. Instead of directly embedding custom logic into the application, the MCP client enables the model to discover, connect to, and interact with external tools and data providers in a standardized way.

To add MCP Clients to your AI Service, use @Ai.McpClients annotation to reference configured clients:

@Ai.Service
@Ai.ChatModel("expensive-model")
@Ai.McpClients(value = {"foo-mcp-server", "bar-mcp-server"})
public interface ChatAiService {
    String chat(String question);
}

Copied

If you want to have your MCP clients created from the configuration, it should be placed under the langchain4j.mcp-clients.

langchain4j:
  providers:
    open-ai:
      api-key: "${OPEN_AI_API_TOKEN}"

  models:
    expensive-model:
      provider: open-ai
      model-name: "openai.gpt-oss-120b"

  mcp-clients:
    foo-mcp-server:
      uri: http://foo-mcp-server
      initialization-timeout: PT15M
    bar-mcp-server:
      uri: http://bar-mcp-server
      tool-execution-timeout: PT10S

Copied

These are all the MCP Client configuration options currently supported:

Configuration options

Key	Type	Description
`ping-timeout`	`Duration`	The timeout to apply when waiting for a ping response
`client-version`	`String`	Sets the version string that the client will use to identify itself to the MCP server in the initialization message
`protocol-version`	`String`	Sets the protocol version that the client will advertise in the initialization message
`log-responses`	`Boolean`	Whether to log response traffic
`reconnect-interval`	`Duration`	The delay before attempting to reconnect after a failed connection
`uri`	`URI`	The URL of the MCP server
`prompts-timeout`	`Duration`	The timeout for prompt-related operations (listing prompts as well as rendering the contents of a prompt)
`client-name`	`String`	Sets the name that the client will use to identify itself to the MCP server in the initialization message
`resources-timeout`	`Duration`	Sets the timeout for resource-related operations (listing resources as well as reading the contents of a resource)
`log-requests`	`Boolean`	Whether to log request traffic
`tls`	`Tls`	TLS configuration for the MCP server connection
`tool-execution-timeout-error-message`	`String`	The error message to return when a tool execution times out
`key`	`String`	Sets a unique identifier for the client
`tool-execution-timeout`	`Duration`	Sets the timeout for tool execution
`initialization-timeout`	`Duration`	Sets the timeout for initializing the client

Deprecated Options

Key	Type	Description
`sse-uri`	`URI`	The initial URI where to connect to the server and request an SSE channel