Interface McpClient

All Superinterfaces:
AutoCloseable
All Known Implementing Classes:
DefaultMcpClient
public interface McpClient extends AutoCloseable
Represents a client that can communicate with an MCP server over a given transport protocol, retrieve and execute tools using the server.

  • Method Details

    • key

      String key()
      Returns the unique key of this client.

    • instructions

      default @Nullable String instructions()
      Returns the server instructions from the initialize result, or null if the server did not provide any.

    • listTools

      List<ToolSpecification> listTools()
      Obtains a list of tools from the MCP server.

    • listTools

      List<ToolSpecification> listTools(InvocationContext invocationContext)
      Obtains a list of tools from the MCP server.

    • executeTool

      ToolExecutionResult executeTool(ToolExecutionRequest executionRequest)
      Executes a tool on the MCP server and returns the result. Currently, this expects a tool execution to only contain text-based results or JSON structured content.

    • executeTool

      ToolExecutionResult executeTool(ToolExecutionRequest executionRequest, InvocationContext invocationContext)
      Executes a tool on the MCP server and returns the result. Currently, this expects a tool execution to only contain text-based results or JSON structured content.

    • executeToolAsync

      @Experimental default CompletableFuture<ToolExecutionResult> executeToolAsync(ToolExecutionRequest executionRequest, InvocationContext invocationContext)
      Non-blocking counterpart of executeTool(ToolExecutionRequest, InvocationContext): executes a tool on the MCP server without holding a thread while the result is in flight.

      The default implementation returns a failed future carrying AsyncNotSupportedException.

      Since:
      1.20.0

    • listResources

      List<McpResource> listResources()
      Obtains the current list of resources available on the MCP server.

    • listResources

      List<McpResource> listResources(InvocationContext invocationContext)
      Obtains the current list of resources available on the MCP server.

    • listResourceTemplates

      List<McpResourceTemplate> listResourceTemplates()
      Obtains the current list of resource templates (dynamic resources) available on the MCP server.

    • listResourceTemplates

      List<McpResourceTemplate> listResourceTemplates(InvocationContext invocationContext)
      Obtains the current list of resource templates (dynamic resources) available on the MCP server.

    • readResource

      McpReadResourceResult readResource(String uri)
      Retrieves the contents of the resource with the specified URI. This also works for dynamic resources (templates).

    • readResource

      McpReadResourceResult readResource(String uri, InvocationContext invocationContext)
      Retrieves the contents of the resource with the specified URI. This also works for dynamic resources (templates).

    • subscribeToResource

      @Deprecated(since="1.19.0-beta29") void subscribeToResource(String uri)
      Deprecated.
      Use subscribeToResources(List) for MCP 2026-07-28 and later. Throws UnsupportedOperationException when using the modern protocol.
      Subscribes to updates for the resource with the specified URI. When the resource changes, the server will send a notifications/resources/updated notification. The client will invoke the onResourceUpdated callback (if configured) with the URI of the updated resource.

    • unsubscribeFromResource

      @Deprecated(since="1.19.0-beta29") void unsubscribeFromResource(String uri)
      Deprecated.
      Use unsubscribeFromResources(long) for MCP 2026-07-28 and later. Throws UnsupportedOperationException when using the modern protocol.
      Unsubscribes from updates for the resource with the specified URI.

    • subscribeToResources

      default long subscribeToResources(List<String> uris)
      Subscribes to resource content update notifications for the given URIs. Once subscribed, the server notifies the client whenever one of those resources changes; the notifications are delivered to the callback registered via DefaultMcpClient.Builder#onResourceUpdated.

      The MCP specification requires the server to confirm a subscription before it sends anything on it, so this method blocks until that confirmation arrives and fails if it does not. When it returns normally, the subscription is established and the returned subscription ID can be passed to unsubscribeFromResources(long) to stop receiving the notifications. How long the client waits for the confirmation is governed by DefaultMcpClient.Builder#resourcesTimeout(Duration).

      Because this method blocks, do not call it from inside a notification callback such as onResourceUpdated: those callbacks run on the thread that reads messages from the server, which is the same thread that would have to deliver the confirmation.

      Only available with MCP protocol version 2026-07-28 and later.

      Parameters:
      uris - the list of resource URIs to subscribe to
      Returns:
      a subscription ID
      Throws:
      UnsupportedOperationException - when using legacy protocol (2025-11-25)
      McpException - if the server rejects the subscription
      IllegalStateException - if the server confirms the subscription but declines to honour the requested resource URIs, if it ends the subscription without ever confirming it, or if the client is closed while the call is still waiting
      CancellationException - if the subscription is cancelled before the server confirms it, for example by a concurrent unsubscribeFromResources(long)
      RuntimeException - if the underlying transport fails, or the server does not confirm the subscription in time

    • unsubscribeFromResources

      default void unsubscribeFromResources(long subscriptionId)
      Unsubscribes from resource content update notifications for the given subscription ID. Only available with MCP protocol version 2026-07-28 and later.
      Parameters:
      subscriptionId - the subscription ID returned by subscribeToResources(List)
      Throws:
      UnsupportedOperationException - when using legacy protocol (2025-11-25)

    • listPrompts

      List<McpPrompt> listPrompts()
      Obtain a list of prompts available on the MCP server.

    • getPrompt

      McpGetPromptResult getPrompt(String name, Map<String,Object> arguments)
      Render the contents of a prompt.

    • checkHealth

      void checkHealth()
      Performs a health check that returns normally if the MCP server is reachable and properly responding to ping requests. If this method throws an exception, the health of this MCP client is considered degraded.

    • setRoots

      @Deprecated(since="1.19.0-beta29") void setRoots(List<McpRoot> roots)
      Deprecated.
      Roots are deprecated in MCP protocol version 2026-07-28. This method throws UnsupportedOperationException when the modern protocol is in use.
      Sets the roots that are made available to the server upon its request. After calling this method, the client also sends a notifications/roots/list_changed message to the server.