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.

    • 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. Returns a subscription ID that can be used to unsubscribe later. 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)

    • 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.