Module io.modelcontextprotocol.sdk.mcp
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, Jihoon Kim
See Also:

  • Method Details

    • getCurrentInitializationResult

      public McpSchema.InitializeResult getCurrentInitializationResult()
      Get the current initialization result.
      Returns:
      the initialization result.

    • getServerCapabilities

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

    • getServerInstructions

      public String getServerInstructions()
      Get the server instructions that provide guidance to the client on how to interact with this server.
      Returns:
      The instructions

    • getServerInfo

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

    • isInitialized

      public boolean isInitialized()
      Check if the client-server connection is initialized.
      Returns:
      true if the client-server connection is initialized

    • 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 all 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()
      Retrieves the list of all resources provided by the server.
      Returns:
      The list of all resources result

    • listResources

      public McpSchema.ListResourcesResult listResources(String cursor)
      Retrieves a paginated list of resources provided by the server.
      Parameters:
      cursor - Optional pagination cursor from a previous 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()
      Retrieves the list of all resource templates provided by the server.
      Returns:
      The list of all resource templates result.

    • 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. Retrieves a paginated list of resource templates provided by the server.
      Parameters:
      cursor - Optional pagination cursor from a previous list request
      Returns:
      The list of resource templates result.

    • 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()
      Retrieves the list of all prompts provided by the server.
      Returns:
      The list of all prompts result.

    • listPrompts

      public McpSchema.ListPromptsResult listPrompts(String cursor)
      Retrieves a paginated list of prompts provided by the server.
      Parameters:
      cursor - Optional pagination cursor from a previous list request
      Returns:
      The list of prompts result.

    • getPrompt

      public McpSchema.GetPromptResult getPrompt(McpSchema.GetPromptRequest getPromptRequest)

    • 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

    • completeCompletion

      public McpSchema.CompleteResult completeCompletion(McpSchema.CompleteRequest completeRequest)
      Send a completion/complete request.
      Parameters:
      completeRequest - the completion request contains the prompt or resource reference and arguments for generating suggestions.
      Returns:
      the completion result containing suggested values.