feat: MCP tools support ToolContext #3831

YunKuiLu · 2025-07-16T17:28:50Z

Add excludedToolContextKeys to McpClientCommonProperties.ToolCallback. This will let us control which ToolContext fields should not be sent to the server. By default, excludedToolContextKeys is set to TOOL_CALL_HISTORY.
Add AbstractMcpToolCallback to hold common code for McpToolCallback
Update AsyncMcpToolCallback and SyncMcpToolCallback to pass ToolContext via _meta using key ai.springframework.org/tool_context
Update McpToolUtils to help server tools extract ToolContext from MCP Client requests
Update AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider to use the Builder design pattern and add the excludedToolContextKeys field
Update the corresponding test cases

PR description

The Spring AI MCP client now sends ToolContext data inside the _meta field of CallToolRequest, using the key ai.springframework.org/tool_context.
By default, the TOOL_CALL_HISTORY entry in ToolContext is excluded from being sent to the server. This can be customized using the config spring.ai.mcp.client.toolcallback.excluded-tool-context-keys.
On the server side, Spring AI reads the ToolContext from the _meta field using the same key ai.springframework.org/tool_context, and passes it into the tool method.

QA

Why is ai.springframework.org/tool_context used as the key for ToolContext in _meta?
I decided to use it based on the MCP protocol's description of _meta. https://modelcontextprotocol.io/specification/2025-06-18/basic/index#meta

Example

Client

application.yml

spring:
  ai:
    mcp:
      client:
        type: sync
        sse:
          connections:
            server1:
              url: http://localhost:8080
        toolcallback:
          excluded-tool-context-keys: TOOL_CALL_HISTORY,foo

code

chatClient.prompt()
    .toolCallbacks(syncMcpToolCallbackProvider)
    .toolContext(Map.of("userId", "123", "person", new Person("username1", 18), "foo", "bar"))
    .user(userMessage)
    .call()
    .content();

public record Person(String name, int age) {
}

Server

private final ObjectMapper objectMapper = new ObjectMapper();
@Tool(description = "Query the number of users for the specified system.")
public String querySystemPersonNum(@ToolParam(description = "systemName") String param, ToolContext toolContext) {
    log.info("param = {}", param);
    log.info("toolContext = {}", toolContext.getContext());
    log.info("userId = {}", toolContext.getContext().get("userId"));
    log.info("person = {}", objectMapper.convertValue(toolContext.getContext().getOrDefault("person", null), Person.class));
    log.info("_meta = {}", toolContext.getContext().get(TOOL_CONTEXT_MCP_META_KEY));
    return "102";
}

public record Person(String name, int age) {
}

print:

INFO 28100 --- [oundedElastic-1] t.l.a.s.d.mcp.server.DemoMcpServerTools  : param = User Center
INFO 28100 --- [oundedElastic-2] t.l.a.s.d.mcp.server.DemoMcpServerTools  : toolContext = {_meta={ai.springframework.org/tool_context={userId=123, person={name=username1, age=18}}}, exchange=io.modelcontextprotocol.server.McpSyncServerExchange@505a4e46, userId=123, person={name=username1, age=18}}
INFO 28100 --- [oundedElastic-2] t.l.a.s.d.mcp.server.DemoMcpServerTools  : userId = 123
INFO 28100 --- [oundedElastic-2] t.l.a.s.d.mcp.server.DemoMcpServerTools  : person = Person[name=username1, age=18]
INFO 28100 --- [oundedElastic-2] t.l.a.s.d.mcp.server.DemoMcpServerTools  : _meta = {ai.springframework.org/tool_context={userId=123, person={name=username1, age=18}}}

Resolves #3505
Resolves #2868
Resolves #2784
Resolves #2620

msievers · 2025-07-17T08:03:19Z

Just an idea regarding the excludedToolContextKeys ... Another option would be to have this configurable the other way around. What I mean is to exclude the TOOL_CALL_HISTORY by default and instead make it configurable to include it in the ToolContext only if explicitly enabled. I don't know, something like the following, for example:

spring.ai.mcp.client.toolcallback.tool-call-history.enabled=true

That way, the out-of-the-box user experience would be that the server only receives what the user explicitly writes into the ToolContext. And if the user wants to transmit additional metadata (such as TOOL_CALL_HISTORY), they can explicitly enable that on the client side.

On the other hand, one could argue that the default behavior of the ToolContext would then change depending on whether the tool call is executed locally or via MCP, which in turn would be an argument for including it by default.

Tough decision, but I just thought I’d think out loud about it for a moment 🤔

YunKuiLu · 2025-07-17T09:25:24Z

...va/org/springframework/ai/mcp/client/autoconfigure/properties/McpClientCommonProperties.java

+		/**
+		 * The keys that will not be sent to the MCP Server inside * the `_meta` field of
+		 * {@link io.modelcontextprotocol.spec.McpSchema.CallToolRequest}
+		 */
+		// Remember to update META-INF/additional-spring-configuration-metadata.json if
+		// you change this default values.
+		private Set<String> excludedToolContextKeys = Set.of(TOOL_CALL_HISTORY);


That way, the out-of-the-box user experience would be that the server only receives what the user explicitly writes into the ToolContext. And if the user wants to transmit additional metadata (such as TOOL_CALL_HISTORY), they can explicitly enable that on the client side.

@msievers I did think about the scenario you mentioned.

The default value is spring.ai.mcp.client.toolcallback.excluded-tool-context-keys=TOOL_CALL_HISTORY, and users can override it. It also makes it easier for us to add more defaults in the future.

I'm not sure if we need a separate field just for handling TOOL_CALL_HISTORY.

...-mcp-client-common/src/main/resources/META-INF/additional-spring-configuration-metadata.json

...springframework/ai/mcp/client/common/autoconfigure/properties/McpClientCommonProperties.java

msievers · 2025-07-18T08:40:26Z

mcp/common/src/main/java/org/springframework/ai/mcp/McpToolUtils.java

+						if (request.meta().containsKey(DEFAULT_MCP_META_TOOL_CONTEXT_KEY)) {
+							// Get the McpClient tool context from the
+							// `ai.springframework.org/tool_context` key in the _meta.
+							Map<String, Object> toolContext = OBJECT_MAPPER.convertValue(


Could ModelOptionsUtils.objectToMap perhaps be used here instead of a dedicated ObjectMapper? I'm just asking because I noticed that in other parts, ModelOptionsUtils is often used when it comes to parameter conversions.

Map<String, Object> toolContext = ModelOptionsUtils.objectToMap(request.meta().get(DEFAULT_MCP_META_TOOL_CONTEXT_KEY));

Done!

I used to think that ModelOptionsUtils was only meant for handling Models, but apparently McpToolUtils also uses it for JSON serialization. So it makes sense to use it for _meta too.
I've updated the code accordingly and also adjusted some comments.

- Added `excludedToolContextKeys` to `McpClientCommonProperties.ToolCallback`. This will let us control which `ToolContext` fields should not be sent to the server. By default, `excludedToolContextKeys` is set to `TOOL_CALL_HISTORY`. - Added `AbstractMcpToolCallback` to hold common code for `McpToolCallback` - Updated `AsyncMcpToolCallback` and `SyncMcpToolCallback` to pass `ToolContext` via `_meta` using key `ai.springframework.org/tool_context` - Updated `McpToolUtils` to help server tools extract `ToolContext` from MCP Client requests - Updated `AsyncMcpToolCallbackProvider` and `SyncMcpToolCallbackProvider` to use the Builder design pattern and add the `excludedToolContextKeys` field - Updated the corresponding test cases Signed-off-by: YunKui Lu <[email protected]>

msievers

At least in my humble opinion, this looks good. I think you can ping one the maintainers so they can take a look and ideally include it in the 1.1.0 release.

YunKuiLu · 2025-07-22T09:07:20Z

Hi @tzolov @markpollack, could you help review this PR? Thank you! 😊

msievers · 2025-07-27T04:42:14Z

@ilayaperumalg I wanted to ask if one of the maintainers could take a look at this merge request, which implements ToolContext propagation when using MCP. This is achieved by transferring the ToolContext between server and host using the new _meta field in MCP.

Support for ToolContext propagation will enable easy transmission of data such as tenantId, userId, and other metadata between MCP hosts and servers without exposing this information to the user or the model, so having this in 1.1.0 would be awesome 🚀

ilayaperumalg · 2025-07-28T08:15:59Z

@YunKuiLu Thanks for the PR and @msievers thanks for the review and follow up.

While this PR addresses the issue, we think we can simplify this by setting the meta argument directly when invoking the MCP client callTool. I have submitted a PR #3925 for that. Could you review this and let us know what you think? Thank you

ilayaperumalg · 2025-07-28T08:28:12Z

@YunKuiLu Sorry, I misunderstood your implementation. I see you are using the same approach in setting the ToolContext and handling the server side. I will close my PR and let's continue review yours from here.

YunKuiLu · 2025-07-28T10:22:55Z

@ilayaperumalg Thank you. If there is anything I didn't explain clearly, please point it out.

By the way, could you help check this PR #3252 ? It's been merged into 1.0.x, but not into main yet.

Icyrockton · 2025-08-14T11:55:42Z

Any progress on this PR?
_meta is helpful for passing some fields not directly related to the parameters, such as userId or appname

YunKuiLu · 2025-08-20T17:12:06Z

Hi @markpollack , is there a chance to add this feature to the 1.1.0.M1 milestone?

- Introduce ToolContextToMcpMetaConverter interface for converting Spring AI ToolContext to MCP call metadata - Refactor McpToolCallbackAutoConfiguration to use ObjectProvider for flexible dependency injection - Remove automatic McpToolNamePrefixGenerator bean creation in favor of ObjectProvider-based resolution - Add builder pattern for AsyncMcpToolCallback and SyncMcpToolCallback with comprehensive configuration options - Add builder pattern for AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider - Enhance tool callback call methods to support ToolContext parameter with metadata conversion - Update MCP tool callbacks to use new CallToolRequest.builder() API - Improve error handling and logging in tool callback implementations - Add comprehensive coverage for new builder functionality - Update documentation with ToolContextToMcpMetaConverter usage examples - Maintain backward compatibility through deprecation of old constructors Breaking changes: - McpToolCallbackAutoConfiguration no longer automatically creates McpToolNamePrefixGenerator bean - Tool callback constructors are now private, use builder() method instead Resolves: spring-projects#3505 Resolves: spring-projects#2868 Resolves: spring-projects#2784 Resolves: spring-projects#2620 Replaces: spring-projects#3831 Signed-off-by: Christian Tzolov <[email protected]> Co-authored-by: YunKui Lu <[email protected]>

tzolov · 2025-09-06T09:34:45Z

@YunKuiLu, thanks for your work on this.

I've reworked the issue in PR #4328 with you as co-author, making necessary design changes.

Key update: replaced exclude/include key properties with a customizable ToolContextToMcpMetaConverter.
The default conversion copies tool-context values (excluding history) as MCP meta without nesting.

Let's continue discussion and work on #4328.

tzolov · 2025-09-06T09:35:03Z

Closing this as replaced by #4328.

- Introduce ToolContextToMcpMetaConverter interface for converting Spring AI ToolContext to MCP call metadata - Refactor McpToolCallbackAutoConfiguration to use ObjectProvider for flexible dependency injection - Remove automatic McpToolNamePrefixGenerator bean creation in favor of ObjectProvider-based resolution - Add builder pattern for AsyncMcpToolCallback and SyncMcpToolCallback with comprehensive configuration options - Add builder pattern for AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider - Enhance tool callback call methods to support ToolContext parameter with metadata conversion - Update MCP tool callbacks to use new CallToolRequest.builder() API - Improve error handling and logging in tool callback implementations - Add comprehensive coverage for new builder functionality - Update documentation with ToolContextToMcpMetaConverter usage examples - Maintain backward compatibility through deprecation of old constructors Breaking changes: - McpToolCallbackAutoConfiguration no longer automatically creates McpToolNamePrefixGenerator bean - Tool callback constructors are now private, use builder() method instead Resolves: #3505 Resolves: #2868 Resolves: #2784 Resolves: #2620 Replaces: #3831 ref docs updates Signed-off-by: Christian Tzolov <[email protected]> Co-authored-by: YunKui Lu <[email protected]>

- Introduce ToolContextToMcpMetaConverter interface for converting Spring AI ToolContext to MCP call metadata - Refactor McpToolCallbackAutoConfiguration to use ObjectProvider for flexible dependency injection - Remove automatic McpToolNamePrefixGenerator bean creation in favor of ObjectProvider-based resolution - Add builder pattern for AsyncMcpToolCallback and SyncMcpToolCallback with comprehensive configuration options - Add builder pattern for AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider - Enhance tool callback call methods to support ToolContext parameter with metadata conversion - Update MCP tool callbacks to use new CallToolRequest.builder() API - Improve error handling and logging in tool callback implementations - Add comprehensive coverage for new builder functionality - Update documentation with ToolContextToMcpMetaConverter usage examples - Maintain backward compatibility through deprecation of old constructors Breaking changes: - McpToolCallbackAutoConfiguration no longer automatically creates McpToolNamePrefixGenerator bean - Tool callback constructors are now private, use builder() method instead Resolves: spring-projects#3505 Resolves: spring-projects#2868 Resolves: spring-projects#2784 Resolves: spring-projects#2620 Replaces: spring-projects#3831 ref docs updates Signed-off-by: Christian Tzolov <[email protected]> Co-authored-by: YunKui Lu <[email protected]>

- Introduce ToolContextToMcpMetaConverter interface for converting Spring AI ToolContext to MCP call metadata - Refactor McpToolCallbackAutoConfiguration to use ObjectProvider for flexible dependency injection - Remove automatic McpToolNamePrefixGenerator bean creation in favor of ObjectProvider-based resolution - Add builder pattern for AsyncMcpToolCallback and SyncMcpToolCallback with comprehensive configuration options - Add builder pattern for AsyncMcpToolCallbackProvider and SyncMcpToolCallbackProvider - Enhance tool callback call methods to support ToolContext parameter with metadata conversion - Update MCP tool callbacks to use new CallToolRequest.builder() API - Improve error handling and logging in tool callback implementations - Add comprehensive coverage for new builder functionality - Update documentation with ToolContextToMcpMetaConverter usage examples - Maintain backward compatibility through deprecation of old constructors Breaking changes: - McpToolCallbackAutoConfiguration no longer automatically creates McpToolNamePrefixGenerator bean - Tool callback constructors are now private, use builder() method instead Resolves: spring-projects#3505 Resolves: spring-projects#2868 Resolves: spring-projects#2784 Resolves: spring-projects#2620 Replaces: spring-projects#3831 ref docs updates Signed-off-by: Christian Tzolov <[email protected]> Co-authored-by: YunKui Lu <[email protected]> Signed-off-by: 家娃 <[email protected]>

YunKuiLu commented Jul 17, 2025

View reviewed changes

YunKuiLu force-pushed the tool_context_meta branch 3 times, most recently from 7db214a to 9053c65 Compare July 18, 2025 03:50

msievers reviewed Jul 18, 2025

View reviewed changes

...-mcp-client-common/src/main/resources/META-INF/additional-spring-configuration-metadata.json Show resolved Hide resolved

...springframework/ai/mcp/client/common/autoconfigure/properties/McpClientCommonProperties.java Show resolved Hide resolved

msievers reviewed Jul 18, 2025

View reviewed changes

YunKuiLu force-pushed the tool_context_meta branch from 9053c65 to e289c5c Compare July 19, 2025 07:16

YunKuiLu force-pushed the tool_context_meta branch from e289c5c to ad5c309 Compare July 19, 2025 07:28

YunKuiLu requested a review from msievers July 19, 2025 08:24

msievers reviewed Jul 20, 2025

View reviewed changes

ilayaperumalg mentioned this pull request Jul 28, 2025

Allow MCP toolcallback to use ToolContext #3925

Closed

wuwahe approved these changes Jul 30, 2025

View reviewed changes

ilayaperumalg assigned tzolov and ilayaperumalg Sep 5, 2025

ilayaperumalg added the MCP label Sep 5, 2025

tzolov mentioned this pull request Sep 6, 2025

refactor(mcp): Add ToolContext to MCP metadata conversion #4328

Closed

tzolov closed this Sep 6, 2025

feat: MCP tools support ToolContext #3831

feat: MCP tools support ToolContext #3831

Uh oh!

Conversation

YunKuiLu commented Jul 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

PR description

QA

Example

Client

Server

Uh oh!

msievers commented Jul 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

YunKuiLu Jul 17, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

msievers Jul 18, 2025

Choose a reason for hiding this comment

Uh oh!

YunKuiLu Jul 19, 2025

Choose a reason for hiding this comment

Uh oh!

msievers left a comment

Choose a reason for hiding this comment

Uh oh!

YunKuiLu commented Jul 22, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

msievers commented Jul 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ilayaperumalg commented Jul 28, 2025

Uh oh!

ilayaperumalg commented Jul 28, 2025

Uh oh!

YunKuiLu commented Jul 28, 2025

Uh oh!

Icyrockton commented Aug 14, 2025

Uh oh!

YunKuiLu commented Aug 20, 2025

Uh oh!

tzolov commented Sep 6, 2025

Uh oh!

tzolov commented Sep 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

YunKuiLu commented Jul 16, 2025 •

edited

Loading

msievers commented Jul 17, 2025 •

edited

Loading

YunKuiLu commented Jul 22, 2025 •

edited

Loading

msievers commented Jul 27, 2025 •

edited

Loading