Package io.modelcontextprotocol.client

Class McpSyncClient

java.lang.Object
io.modelcontextprotocol.client.McpSyncClient
All Implemented Interfaces:
AutoCloseable
public class McpSyncClient extends Object implements AutoCloseable
A synchronous client implementation for the Model Context Protocol (MCP) that wraps an McpAsyncClient to provide blocking operations.

This client implements the MCP specification by delegating to an asynchronous client and blocking on the results. Key features include:

  • Synchronous, blocking API for simpler integration in non-reactive applications
  • Tool discovery and invocation for server-provided functionality
  • Resource access and management with URI-based addressing
  • Prompt template handling for standardized AI interactions
  • Real-time notifications for tools, resources, and prompts changes
  • Structured logging with configurable severity levels

The client follows the same lifecycle as its async counterpart:

  1. Initialization - Establishes connection and negotiates capabilities
  2. Normal Operation - Handles requests and notifications
  3. Graceful Shutdown - Ensures clean connection termination

This implementation implements AutoCloseable for resource cleanup and provides both immediate and graceful shutdown options. All operations block until completion or timeout, making it suitable for traditional synchronous programming models.

Author:
Dariusz Jędrzejczyk, Christian Tzolov
See Also:

  • Constructor Details

    • McpSyncClient

      @Deprecated public McpSyncClient(McpAsyncClient delegate)
      Deprecated.
      Use McpClient.sync(ClientMcpTransport) to obtain an instance.
      Create a new McpSyncClient with the given delegate.
      Parameters:
      delegate - the asynchronous kernel on top of which this synchronous client provides a blocking API.

  • Method Details

    • getServerCapabilities

      public McpSchema.ServerCapabilities getServerCapabilities()
      Get the server capabilities that define the supported features and functionality.
      Returns:
      The server capabilities

    • getServerInfo

      public McpSchema.Implementation getServerInfo()
      Get the server implementation information.
      Returns:
      The server implementation details

    • getClientCapabilities

      public McpSchema.ClientCapabilities getClientCapabilities()
      Get the client capabilities that define the supported features and functionality.
      Returns:
      The client capabilities

    • getClientInfo

      public McpSchema.Implementation getClientInfo()
      Get the client implementation information.
      Returns:
      The client implementation details

    • close

      public void close()
      Specified by:
      close in interface AutoCloseable

    • closeGracefully

      public boolean closeGracefully()

    • initialize

      public McpSchema.InitializeResult initialize()
      The initialization phase MUST be the first interaction between client and server. During this phase, the client and server:
      • Establish protocol version compatibility
      • Exchange and negotiate capabilities
      • Share implementation details

      The client MUST initiate this phase by sending an initialize request containing:
      • The protocol version the client supports
      • The client's capabilities
      • Client implementation information
      The server MUST respond with its own capabilities and information: McpSchema.ServerCapabilities.
      After successful initialization, the client MUST send an initialized notification to indicate it is ready to begin normal operations.
      Initialization Spec
      Returns:
      the initialize result.

    • rootsListChangedNotification

      public void rootsListChangedNotification()
      Send a roots/list_changed notification.

    • addRoot

      public void addRoot(McpSchema.Root root)
      Add a roots dynamically.

    • removeRoot

      public void removeRoot(String rootUri)
      Remove a root dynamically.

    • ping

      public Object ping()
      Send a synchronous ping request.
      Returns:

    • callTool

      public McpSchema.CallToolResult callTool(McpSchema.CallToolRequest callToolRequest)
      Calls a tool provided by the server. Tools enable servers to expose executable functionality that can interact with external systems, perform computations, and take actions in the real world.
      Parameters:
      callToolRequest - The request containing: - name: The name of the tool to call (must match a tool name from tools/list) - arguments: Arguments that conform to the tool's input schema
      Returns:
      The tool execution result containing: - content: List of content items (text, images, or embedded resources) representing the tool's output - isError: Boolean indicating if the execution failed (true) or succeeded (false/absent)

    • listTools

      public McpSchema.ListToolsResult listTools()
      Retrieves the list of all tools provided by the server.
      Returns:
      The list of tools result containing: - tools: List of available tools, each with a name, description, and input schema - nextCursor: Optional cursor for pagination if more tools are available

    • listTools

      public McpSchema.ListToolsResult listTools(String cursor)
      Retrieves a paginated list of tools provided by the server.
      Parameters:
      cursor - Optional pagination cursor from a previous list request
      Returns:
      The list of tools result containing: - tools: List of available tools, each with a name, description, and input schema - nextCursor: Optional cursor for pagination if more tools are available

    • listResources

      public McpSchema.ListResourcesResult listResources(String cursor)
      Send a resources/list request.
      Parameters:
      cursor - the cursor
      Returns:
      the list of resources result.

    • listResources

      public McpSchema.ListResourcesResult listResources()
      Send a resources/list request.
      Returns:
      the list of resources result.

    • readResource

      public McpSchema.ReadResourceResult readResource(McpSchema.Resource resource)
      Send a resources/read request.
      Parameters:
      resource - the resource to read
      Returns:
      the resource content.

    • readResource

      public McpSchema.ReadResourceResult readResource(McpSchema.ReadResourceRequest readResourceRequest)
      Send a resources/read request.
      Parameters:
      readResourceRequest - the read resource request.
      Returns:
      the resource content.

    • listResourceTemplates

      public McpSchema.ListResourceTemplatesResult listResourceTemplates(String cursor)
      Resource templates allow servers to expose parameterized resources using URI templates. Arguments may be auto-completed through the completion API. Request a list of resource templates the server has.
      Parameters:
      cursor - the cursor
      Returns:
      the list of resource templates result.

    • listResourceTemplates

      public McpSchema.ListResourceTemplatesResult listResourceTemplates()
      Request a list of resource templates the server has.
      Returns:
      the list of resource templates result.

    • sendResourcesListChanged

      public void sendResourcesListChanged()
      List Changed Notification. When the list of available resources changes, servers that declared the listChanged capability SHOULD send a notification:

    • subscribeResource

      public void subscribeResource(McpSchema.SubscribeRequest subscribeRequest)
      Subscriptions. The protocol supports optional subscriptions to resource changes. Clients can subscribe to specific resources and receive notifications when they change. Send a resources/subscribe request.
      Parameters:
      subscribeRequest - the subscribe request contains the uri of the resource to subscribe to.

    • unsubscribeResource

      public void unsubscribeResource(McpSchema.UnsubscribeRequest unsubscribeRequest)
      Send a resources/unsubscribe request.
      Parameters:
      unsubscribeRequest - the unsubscribe request contains the uri of the resource to unsubscribe from.

    • listPrompts

      public McpSchema.ListPromptsResult listPrompts(String cursor)

    • listPrompts

      public McpSchema.ListPromptsResult listPrompts()

    • getPrompt

      public McpSchema.GetPromptResult getPrompt(McpSchema.GetPromptRequest getPromptRequest)

    • promptListChangedNotification

      public void promptListChangedNotification()
      (Server) An optional notification from the server to the client, informing it that the list of prompts it offers has changed. This may be issued by servers without any previous subscription from the client.

    • setLoggingLevel

      public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel)
      Client can set the minimum logging level it wants to receive from the server.
      Parameters:
      loggingLevel - the min logging level