feat: add support for meta parameter in client paginated list queries by smohite04 · Pull Request #906 · modelcontextprotocol/java-sdk

smohite04 · 2026-04-07T15:59:48Z

Add support for meta parameter in listTools method.

Motivation and Context

McpSchema.PaginatedRequest now has a meta field (added in #344), but the client API methods don't expose it. As a result, servers which can accept the meta parameter in list tools cannot be used with java client. The Python SDK already supports passing _meta in tools/list requests:

python
async def list_tools(self, *, cursor=None, meta=None) -> ListToolsResult

This change aligns the Java SDK with the Python SDK and the MCP spec which allows _meta in PaginatedRequestParams.

How Has This Been Tested?

Unit tests: McpAsyncClientTests.testListToolsWithCursorAndMeta() and testSyncListToolsWithCursorAndMeta() - verify _meta is correctly serialized in the JSON-RPC request
Integration test: AbstractMcpSyncClientTests.testListToolsWithMeta() - verified against the real server-everything MCP server via HttpClientStreamableHttpSyncClientTests (Docker/Testcontainers).

Ran per recommendations

Unit tests (McpAsyncClientTests):
Tests run: 7, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.467 s
  testListToolsWithCursorAndMeta    -- Time elapsed: 0.031 s  ✅
  testSyncListToolsWithCursorAndMeta -- Time elapsed: 0.006 s  ✅
  testListToolsWithEmptyCursor      -- Time elapsed: 0.360 s  ✅
  (+ 4 existing tests passing)
BUILD SUCCESS


Integration test (HttpClientStreamableHttpSyncClientTests against real 
server-everything via Docker):
Tests run: 1, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 13.59 s
  testListToolsWithMeta -- Time elapsed: 0.445 s  ✅
BUILD SUCCESS

Breaking Changes

None. New overloaded methods added; existing listTools(String cursor) behavior unchanged.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

Closes #907

Kehrlann · 2026-04-08T14:13:34Z

@smohite04 thank you for your contribution.

Could you please expand this to all paginated requests?

That is:

resources/list
resources/templates/list
prompts/list
tools/list

smohite04 · 2026-04-08T15:12:37Z

Thanks @Kehrlann. I will expand this to all paginated requests and update the PR shortly.

…are: - resources/list - resources/templates/list - prompts/list - tools/list paginated list operations extended in this review: - listResources(String cursor, Map<String, Object> meta) - listResourceTemplates(String cursor, Map<String, Object> meta) - listPrompts(String cursor, Map<String, Object> meta) Closes modelcontextprotocol#907

smohite04 · 2026-04-08T16:09:58Z

Extended support for remaining paginated requests.

Unit tests (McpAsyncClientTests):
Tests run: 13, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 0.480 s
  testListToolsWithCursorAndMeta              ✅
  testSyncListToolsWithCursorAndMeta          ✅
  testListResourcesWithCursorAndMeta          ✅
  testSyncListResourcesWithCursorAndMeta      ✅
  testListResourceTemplatesWithCursorAndMeta   ✅
  testSyncListResourceTemplatesWithCursorAndMeta ✅
  testListPromptsWithCursorAndMeta            ✅
  testSyncListPromptsWithCursorAndMeta        ✅
  testListToolsWithEmptyCursor   ✅
  validateContextPassedToTransportConnect   ✅
  testCallToolWithOutputSchemaValidationSuccess   ✅
  testCallToolWithNoOutputSchemaSuccess   ✅
  testCallToolWithOutputSchemaValidationFailure   ✅
BUILD SUCCESS

Integration tests :
Tests run: 4, Failures: 0, Errors: 0, Skipped: 0, Time elapsed: 12.72 s
  testListToolsWithMeta             ✅
  testListResourcesWithMeta         ✅
  testListResourceTemplatesWithMeta ✅
  testListPromptsWithMeta           ✅
BUILD SUCCESS

Kehrlann

Looks good. Minor details that I'll polish in a subsequent commit.

Thanks for your contribution!

Kehrlann · 2026-04-09T08:37:38Z

mcp-core/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

+	 * @param meta Optional metadata to include in the request (_meta field)
+	 * @return A Mono that emits the list of tools result
+	 */
+	public Mono<McpSchema.ListToolsResult> listTools(String cursor, java.util.Map<String, Object> meta) {


I general, prefer imports over FQN

Kehrlann · 2026-04-09T08:38:09Z

mcp-test/src/test/java/io/modelcontextprotocol/client/McpAsyncClientTests.java

+		McpClientTransport transport = new McpClientTransport() {
+			Function<Mono<McpSchema.JSONRPCMessage>, Mono<McpSchema.JSONRPCMessage>> handler;
+
+			@Override
+			public Mono<Void> connect(
+					Function<Mono<McpSchema.JSONRPCMessage>, Mono<McpSchema.JSONRPCMessage>> handler) {
+				return Mono.deferContextual(ctx -> {
+					this.handler = handler;
+					return Mono.empty();
+				});
+			}
+
+			@Override
+			public Mono<Void> closeGracefully() {
+				return Mono.empty();
+			}
+
+			@Override
+			public Mono<Void> sendMessage(McpSchema.JSONRPCMessage message) {
+				if (!(message instanceof McpSchema.JSONRPCRequest request)) {
+					return Mono.empty();
+				}
+
+				McpSchema.JSONRPCResponse response;
+				if (McpSchema.METHOD_INITIALIZE.equals(request.method())) {
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), MOCK_INIT_RESULT,
+							null);
+				}
+				else if (McpSchema.METHOD_TOOLS_LIST.equals(request.method())) {
+					capturedRequest[0] = JSON_MAPPER.convertValue(request.params(), McpSchema.PaginatedRequest.class);
+					response = new McpSchema.JSONRPCResponse(McpSchema.JSONRPC_VERSION, request.id(), mockToolsResult,
+							null);
+				}
+				else {
+					return Mono.empty();
+				}
+
+				return handler.apply(Mono.just(response)).then();
+			}
+
+			@Override
+			public <T> T unmarshalFrom(Object data, TypeRef<T> typeRef) {
+				return JSON_MAPPER.convertValue(data, new TypeRef<>() {
+					@Override
+					public java.lang.reflect.Type getType() {
+						return typeRef.getType();
+					}
+				});
+			}
+		};


This should probably be factored into a reusable method.

…#906) * feat: add support for meta parameter in client paginated list queries# - resources/list - resources/templates/list - prompts/list - tools/list paginated list operations extended in this review: - listResources(String cursor, Map<String, Object> meta) - listResourceTemplates(String cursor, Map<String, Object> meta) - listPrompts(String cursor, Map<String, Object> meta) Closes #907 Co-authored-by: SHEETAL MOHITE <mohishee@amazon.com> Signed-off-by: Daniel Garnier-Moiroux <git@garnier.wf>

smohite04 mentioned this pull request Apr 7, 2026

feat: Add support for meta parameter to list tools call( paginated request already support meta field). #907

Closed

smohite04 marked this pull request as ready for review April 7, 2026 16:03

Kehrlann self-assigned this Apr 8, 2026

Kehrlann added P1 Significant bug affecting many users, highly requested feature enhancement New feature or request area/client waiting for user Waiting for user feedback or more details labels Apr 8, 2026

SHEETAL MOHITE added 2 commits April 8, 2026 08:16

feat: add support for meta parameter in listTools

de11591

smohite04 force-pushed the support-meta-list-tools branch from cff0406 to 21c8fed Compare April 8, 2026 16:03

Kehrlann changed the title ~~feat: add support for meta parameter in listTools~~ feat: add support for meta parameter in paginated list queries Apr 9, 2026

Kehrlann changed the title ~~feat: add support for meta parameter in paginated list queries~~ feat: add support for meta parameter in client paginated list queries Apr 9, 2026

Kehrlann self-requested a review April 9, 2026 08:37

Kehrlann approved these changes Apr 9, 2026

View reviewed changes

Kehrlann merged commit eaa0c69 into modelcontextprotocol:main Apr 9, 2026
21 checks passed

Kehrlann added a commit that referenced this pull request Apr 9, 2026

Polish gh-906

fcdc0d4

Kehrlann added a commit that referenced this pull request Apr 9, 2026

Polish gh-906

141063c

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add support for meta parameter in client paginated list queries#906

feat: add support for meta parameter in client paginated list queries#906
Kehrlann merged 2 commits intomodelcontextprotocol:mainfrom
smohite04:support-meta-list-tools

smohite04 commented Apr 7, 2026 •

edited

Loading

Uh oh!

Kehrlann commented Apr 8, 2026

Uh oh!

smohite04 commented Apr 8, 2026

Uh oh!

smohite04 commented Apr 8, 2026

Uh oh!

Kehrlann left a comment

Uh oh!

Kehrlann Apr 9, 2026

Uh oh!

Kehrlann Apr 9, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

smohite04 commented Apr 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

Kehrlann commented Apr 8, 2026

Uh oh!

smohite04 commented Apr 8, 2026

Uh oh!

smohite04 commented Apr 8, 2026

Uh oh!

Kehrlann left a comment

Choose a reason for hiding this comment

Uh oh!

Kehrlann Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Kehrlann Apr 9, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

smohite04 commented Apr 7, 2026 •

edited

Loading