Class McpAgent

java.lang.Object
dev.langchain4j.agentic.mcp.McpAgent

public class McpAgent extends Object
Provides type-safe factory methods to create MCP client agent builders.

An MCP client agent wraps a single MCP tool as a non-AI agent, allowing it to be composed with other agents in sequences, loops, supervisors, and other workflow patterns. The tool is looked up on the MCP server the first time it is needed, which is normally the first invocation of the agent, never when the agent is built, and the McpClient itself is created at that moment too when it is given through a supplier.

UntypedAgent agent = McpAgent
        .builder(mcpClient)
        .toolName("my_tool")
        .inputKeys("arg1", "arg2")
        .outputKey("result")
        .build();
  • Method Details

    • builder

      public static McpClientBuilder<UntypedAgent> builder(McpClient mcpClient)
      Creates a builder for an untyped MCP client agent. The given client is created by the caller, so a DefaultMcpClient has already connected to its server: to defer that too, use builder(Supplier).
      Parameters:
      mcpClient - the MCP client instance used to discover and execute the tool
      Returns:
      a new McpClientBuilder instance
    • builder

      public static <T> McpClientBuilder<T> builder(McpClient mcpClient, Class<T> agentServiceClass)
      Creates a builder for a typed MCP client agent implementing the given agent service interface. The given client is created by the caller, so a DefaultMcpClient has already connected to its server: to defer that too, use builder(Supplier, Class).
      Parameters:
      mcpClient - the MCP client instance used to discover and execute the tool
      agentServiceClass - the class of the agent service interface
      Returns:
      a new McpClientBuilder instance
    • builder

      public static McpClientBuilder<UntypedAgent> builder(Supplier<McpClient> mcpClientSupplier)
      Creates a builder for an untyped MCP client agent whose MCP client is created lazily.

      The supplier is invoked on the thread of the invocation that first needs the client, or, when the agent has a resolution timeout, on a thread of the LangChain4j executor and within that time, and the client it returns is then used by every invocation of the agent, so it must not depend on per-request or per-user state, like the credentials of the current user. When it fails, the invocations waiting for the client fail, it is invoked again the next time the client is needed, and a DefaultMcpClient that fails to connect stops its transport, so the supplier can reuse one or create it inside. The agent never closes the client: to close it when it is no longer needed, keep a reference to it from the supplier.

      Parameters:
      mcpClientSupplier - the supplier of the MCP client used to discover and execute the tool, invoked when the client is first needed, which is normally the first invocation of the agent, so that creating the client, which normally connects to the MCP server, does not require the server to be up when the agent is built
      Returns:
      a new McpClientBuilder instance
      Since:
      1.24.0
    • builder

      public static <T> McpClientBuilder<T> builder(Supplier<McpClient> mcpClientSupplier, Class<T> agentServiceClass)
      Creates a builder for a typed MCP client agent implementing the given agent service interface, whose MCP client is created lazily.

      The supplier is invoked on the thread of the invocation that first needs the client, or, when the agent has a resolution timeout, on a thread of the LangChain4j executor and within that time, and the client it returns is then used by every invocation of the agent, so it must not depend on per-request or per-user state, like the credentials of the current user. When it fails, the invocations waiting for the client fail, it is invoked again the next time the client is needed, and a DefaultMcpClient that fails to connect stops its transport, so the supplier can reuse one or create it inside. The agent never closes the client: to close it when it is no longer needed, keep a reference to it from the supplier.

      Parameters:
      mcpClientSupplier - the supplier of the MCP client used to discover and execute the tool, invoked when the client is first needed, which is normally the first invocation of the agent, so that creating the client, which normally connects to the MCP server, does not require the server to be up when the agent is built
      agentServiceClass - the class of the agent service interface
      Returns:
      a new McpClientBuilder instance
      Since:
      1.24.0