Usage and Thraed Safety of McpAsyncClient

[jonasbbin]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

I am a bit unsure on how the MCP Client should be used in an application that runs an agent concurrently. (E.g. Summarizing a book by summarizing each chapter concurrently). Following the example: Is the idea that each Chapter summarizing call should have its own McpAsyncClient? It feels a bit weird to have multiple instances of an McpAsyncClient for the same agent. On the other Hand I was unsure if stateful MCP features like sampling would be thread safe.

Is there an official guideline? I couldn't find information about this.

[jialiuyang]

its one json-rpc session request ids are unique pendingResponses is ConcurrentHashMap so parallel callTool is intended

sampling rides the same session keep your sampling handler thread-safe the client itself is fine

if the server keeps cwd or open files concurrent mutating tools can still collide thats the server for chapter summarize one client is enough dont new a client per chapter thats just extra initialize

[ryux1]

Use one initialized McpAsyncClient for concurrent calls to the same MCP
session. You do not need one client per chapter.

The current implementation is built to multiplex requests on one session:

• McpClientSession generates IDs with an AtomicLong and stores outstanding
  responses in a ConcurrentHashMap.
• LifecycleInitializer coalesces concurrent initialization attempts; its
  tests explicitly assert that concurrent callers create only one session.
• callTool returns a cold Mono, so normal Reactor composition can control
  concurrency and backpressure.

For example, use flatMap's concurrency argument instead of creating clients:

Flux.fromIterable(chapters)
    .flatMap(chapter -> client.callTool(requestFor(chapter)), 8)
    .collectList();

There are two separate thread-safety boundaries to keep in mind:

1. The sampling and elicitation functions you register are application code.
   Multiple server requests may reach them concurrently, so any mutable state
   they capture must be concurrency-safe. Keep them non-blocking, or move
   blocking work to an appropriate bounded scheduler.
2. MCP request multiplexing does not make the tools' semantics independent.
   If the server mutates a shared working directory, file, transaction, or
   conversation state, concurrent tool calls can still conflict even though
   the Java client routes their responses correctly. Serialize those calls or
   isolate that state at the application/server layer.

Separate clients are useful when you intentionally need separate MCP sessions,
credentials, server processes, failure domains, or session-scoped server state.
For concurrent read-like chapter summarization against the same server, a
single client with a bounded flatMap is the appropriate shape. Close it once
at application shutdown with closeGracefully().

Relevant implementation points:

• mcp-core/.../spec/McpClientSession.java (AtomicLong requestCounter,
  ConcurrentHashMap pendingResponses)
• mcp-core/.../client/LifecycleInitializerTests.java (concurrent
  initialization coverage)
• mcp-core/.../client/McpAsyncClient.java (callTool and handler wiring)