Skip to content

fix: keep MCP tool error flag in interceptors and session memory - #2041

Merged
patriknw merged 8 commits into
mainfrom
fix-mcp-tool-error-flag
Oct 13, 2026
Merged

patriknw merged 8 commits into
mainfrom
fix-mcp-tool-error-flag

Conversation

@johanandren

Copy link
Copy Markdown
Contributor

MCP tool interceptors can now see whether a tool result is an error through ToolInterceptorContext.isError(). Session memory stores the flag with tool call responses, so history replay keeps it, and the testkit ToolResult exposes it. Follows lightbend/akka-runtime#5853.

The interceptor now uses the runtime's McpToolCallHooks. As a result, ToolInterceptorContext.toolName() is always the tool name on the MCP server, and the runtime records the tool call intent with the arguments that interceptRequest returns.

@github-actions github-actions Bot added the documentation documentation related label Oct 12, 2026
@patriknw

Copy link
Copy Markdown
Contributor

🤖 review, judge if the suggestions are valid

  • [should-fix] No test covers the case in the issue, and no test guards the request-based route. akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:1026, akka-javasdk-tests/src/test/java/akkajavasdk/components/agent/autonomous/TaskIntegrationTest.java:217.

    • The one new integration test makes a function tool of an autonomous agent throw. The runtime recovers that failure and gives it to the model as an error result. That is not an MCP error result, and it does not run the interceptor. It also does not run a second request of the session.
    • I changed isError = res.isError to false in onSuccess. Every test on the branch still passed: the unit specs, AgentIntegrationTest, SessionMemoryEntityTest and SessionMemoryClientIntegrationTest. So no test checks what a request-based or streamed agent stores.
    • When the flag is dropped in toSpiContextMessages or in the response hook, only the unit specs fail. No test runs an interceptor against the running runtime.
    • The test service can return an MCP error result: an @McpTool method that throws does it. A test with such a tool and a request-recording model provider (SanitizerIntegrationTest already has one) covers the whole route for request-based, streamed and autonomous agents. My local version of that test caught all three mutations above.
  • [should-fix] The javadoc does not say what the flag means for every way the runtime sets it. akka-javasdk/src/main/java/akka/javasdk/agent/SessionMessage.java:280 and :321. It says "true when the tool reported the result as an error".

    • Runtime 1.7.2 sets the flag in two ways. The first: an MCP server marks a result as an error, for both kinds of agent. The second: a tool call of an autonomous agent fails, and the runtime gives the failure to the model as an error result whose text is the exception message. That happens when a function tool throws, when the model names an unknown tool, when an MCP call or its connection fails, and when an interceptor hook throws.
    • In the second case no tool reported anything. That second case is the one the new integration test uses.
    • "The runtime sends such a result to the model as an error result" is true at the model-library level only. In langchain4j 1.20.2, which runtime 1.7.2 uses, only the Anthropic provider passes the flag on. OpenAI, Azure OpenAI, Gemini, Bedrock, Mistral and Ollama send the text only. The same sentence appears in SessionMemory.java:30 and SessionMemoryInterceptor.java:17.
    • Also state the known runtime gap. When an autonomous agent's model asks for a built-in tool and other tools in one response, the runtime stores the other results without the flag, whatever the SDK does.
  • [should-fix] The interceptor now behaves differently in three ways, and users can read about them only in the PR description. akka-javasdk/src/main/java/akka/javasdk/agent/RemoteMcpTools.java:99-110. I ran the same interceptor test on main and on the branch. The thread, a throw from either hook, the arguments that the response hook gets, and the flag the model gets within the interaction are all unchanged. These differ:

    1. For an MCP tool that the runtime aliases because of a name clash, toolName() now returns the name on the MCP server (lookup), not the name the model used (lookup_2). This is true on main, 3.6.6 and the milestone alike. An interceptor that filters or logs by the alias no longer matches. The toolName() javadoc still says only "The tool name that the call is for".
    2. The ledger intent record of the call now holds the arguments that interceptRequest returns, not the model's arguments. The runtime writes them unmasked. So an interceptor that adds a credential to the arguments now has that credential in the ledger.
    3. A null from either hook now fails the tool call with a message that names the hook. On main, it failed with "argument "content" is null" or with a generic component client error.

    These follow from the two-hook form of the runtime interface. State them in the toolName() javadoc and in the release notes.

  • [nit] No test pins the stored field name of the two events with a literal. akka-javasdk/src/test/java/akka/javasdk/impl/agent/SessionMemoryEventSerializationTest.java:34. The bytes are correct: both events, the snapshot messages, AddInteractionCmd and SessionHistory all write "isError":true, and nothing writes "error". But only the SessionMessage forms are pinned (:142). I added @JsonProperty("error") to the event component and every test still passed. Add a literal for each event, and add a "read without the field" case for MultimodalToolResponseMessageAdded and MTCR.

  • [nit] ToolInterceptorContext.isError() is abstract. RemoteMcpTools.java:109. The interface is @DoNotInherit, so this is allowed. But it had a single method, so users' unit tests of an interceptor can build a context as () -> "weather", and those no longer compile. default boolean isError() { return false; } avoids that at no cost.

  • [nit] The user docs say nothing about the flag beyond the interceptor sentence. docs/src/modules/sdk/pages/agents/memory.adoc:55 (MemoryProvider.custom()) does not say that a custom memory must store and return isError. If it does not, error results replay as normal results and nothing tells the developer. docs/src/modules/sdk/pages/agents/testing.adoc:23 does not mention tr.isError(). Neither page says how to make an error result in a test:

    • with an MCP tool: an @McpTool that throws;
    • with a function tool: only in an autonomous agent, because a throwing function tool fails a request-based agent's request, and the session memory then stores nothing.

@octonato

Copy link
Copy Markdown
Contributor

🤖 says...

No end-to-end test of an MCP error result

high · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:461

No test sends an MCP server error through the runtime, an interceptor and session memory. AgentImplMcpToolInterceptorSpec calls the adapter directly, and TaskIntegrationTest uses a throwing @FunctionTool on an autonomous agent.

Nothing checks that the runtime takes the McpToolCallHooks branch, passes the server tool name, and keeps the flag on rewritten text. A regression on the path in the PR title would pass the suite.

Incompatible MCP hooks adapter in PR #1995

high · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:473

PR #1995 adds its own McpToolCallHooksAdapter. Its contextFor builds an anonymous ToolInterceptorContext with no isError(). It also adds a FIXME in toSpiContextMessages that says SessionMessage does not keep the flag, and a second spec, AgentImplMcpToolsSpec, for the same adapter.

Once this PR is on main, #1995 does not compile. The two PRs also carry two adapters and two specs for the same code.

A SessionMemoryInterceptor that rewrites a tool response drops the error flag

high · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/InterceptingSessionMemory.scala:49

dispatch stores whatever beforeWrite returns, and the 5-arg and 6-arg constructors set isError to false. The truncation pattern in InterceptingSessionMemorySpec.scala:171 therefore stores a failed tool call as a success.

On the next turn the model sees error text as normal tool data, which is the bug this PR fixes. The MCP ToolInterceptor keeps the flag on a rewrite, so the two interceptors behave differently.

Exact-match whenToolResult no longer matches error results

medium · akka-javasdk-testkit/src/main/java/akka/javasdk/testkit/TestModelProvider.java:537

whenToolResult(ToolResult) matches with equals, which now includes isError. A stub such as whenToolResult(new ToolResult("tool", "error text")) no longer matches a failed tool, and no text-only constructor takes isError.

User tests fail with MissingModelResponseException or a timeout, not a compile error. The new record component also breaks user record patterns on ToolResult.

toolName() javadoc does not state the new contract

medium · akka-javasdk/src/main/java/akka/javasdk/agent/RemoteMcpTools.java:101

toolName() now returns the tool name on the MCP server, not the name the model used, which the runtime can suffix (for example search_2). The javadoc still says "The tool name that the call is for".

An interceptor that matched on the suffixed name stops matching without an error, and the contract does not tell the user.

SessionMemoryInterceptor javadoc gives conflicting guidance

medium · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMemoryInterceptor.java:16

The paragraph says to use the constructors without sanitized, which also set isError to false. The next sentence says to pass the original isError, but only the canonical constructor takes it, and the paragraph does not say so.

A reader who follows the first instruction drops the error flag. The sentence also uses "so that", which the project comment rules ban.

isError javadoc omits failed tool calls

medium · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMessage.java:280

@param isError says "true when the tool reported the result as an error". The same text is at line 321.

The runtime also sets the flag when the tool call fails, for example when a @FunctionTool throws. The new TaskIntegrationTest asserts that case, so the javadoc understates the contract.

Positional boolean constructors make sanitized and isError easy to swap

medium · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMessage.java:298

new ToolCallResponse(ts, c, id, name, text, tcr.isError()) compiles and binds to the 6-arg constructor, where the last boolean is sanitized. The canonical constructor has two adjacent booleans, and AutonomousAgentImpl.scala:507 passes them by position. The same pattern is at line 343 and in SessionMemoryEntity.java:315 and :349.

An error result then gets sanitized true, which skips masking, and isError false. Both mistakes are silent. The two new event constructors with only sanitized have no production caller.

Request-based Agent storage of the flag is untested

medium · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:1026

No test reaches isError = res.isError in onSuccess. The only end-to-end check uses AutonomousAgentImpl.

Changing this line to isError = false leaves every test green.

Throwing interceptResponse is untested

medium · akka-javasdk/src/test/scala/akka/javasdk/impl/agent/AgentImplMcpToolInterceptorSpec.scala:99

The failure case throws only from interceptRequest.

The docs say an interceptor can deny a response by throwing, and the response path is new Future.fromTry(Try { ... }) code with no test.

Event casts in SessionMemoryEntityTest repeat the history check

low · akka-javasdk-tests/src/test/java/akkajavasdk/components/agent/SessionMemoryEntityTest.java:293

The test casts events.get(1) and events.get(2) by index. The containsExactly on the history at line 306 already checks the flag through record equality.

A change in event order breaks the test without a change in behaviour.

Success path never asserts a non-error tool result

low · akka-javasdk-tests/src/test/java/akkajavasdk/components/agent/autonomous/TaskIntegrationTest.java:193

The success-path matcher checks only content(). Only the error path checks isError().

A regression that marks every tool result as an error would pass.

Passive voice in ToolResult @PARAM isError

low · akka-javasdk-testkit/src/main/java/akka/javasdk/testkit/TestModelProvider.java:129

"was sent to the model as an error result" names no actor.

The project writing rules ask for active voice with a named actor.

Guardrails and the compaction sample do not see the flag

low · akka-javasdk/src/main/java/akka/javasdk/agent/Guardrail.java:73

Guardrail.Message.ToolCallResponse has no isError, and GuardrailProvider.scala:268 drops it. samples/doc-snippets/src/main/java/com/example/application/CompactionAgent.java:90 turns error results into plain text.

A guardrail cannot tell an error result from a normal one, and a compaction summary loses the flag. Both are outside the diff.

isError() is a constant false in the request phase

low · akka-javasdk/src/main/java/akka/javasdk/agent/RemoteMcpTools.java:109

In interceptRequest, isError() always returns false, which reads the same as "succeeded". The method is abstract.

A helper shared by both hooks cannot tell the two cases apart. The abstract method also breaks hand-written test doubles of the context, which users need to unit-test interceptors since there is no factory.

interceptResponse javadoc repeats itself and leaves the contract open

low · akka-javasdk/src/main/java/akka/javasdk/agent/RemoteMcpTools.java:131

The last two sentences say the same thing. The text does not say whether an interceptor can set the flag, or that a failed call such as a timeout never reaches interceptResponse.

A reader cannot tell from the javadoc which results reach the interceptor and what it may change.

"so that" in SessionMemory javadoc

low · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMemory.java:30

The sentence uses "so that" and says "sends an error result to the model as an error result".

The project comment rules ban "so that", and the sentence repeats itself.

Unclear wording in the event javadoc

low · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMemoryEntity.java:231

"A stored event without one of these components reads it as false" has no actor and an unclear "it". "of the tool response" differs from "of the SessionMessage that it adds" in the sentence before.

The project writing rules ask for a named actor and one term per concept.

Tool response to event mapping is written twice

low · akka-javasdk/src/main/java/akka/javasdk/agent/SessionMemoryEntity.java:461

createEvents and compactHistory (lines 626-670) build the same two tool response events. The duplication predates this PR.

This PR had to add isError() to both copies. The next field needs the same double edit, and a missed copy drops data on one path.

Hooks comment describes runtime behaviour in hard-to-parse wording

low · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:472

"and with the tool name on the MCP server" is hard to parse. The comment is accurate.

The comment describes what the runtime does. The project rules allow maintainer notes in // comments, but the wording needs to be clear.

toSpiMcpToolCallHooks is wider than needed

low · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:473

It is private[agent], but only toSpiMcpEndpoints in the same object calls it.

The wider visibility invites other callers in the package for no reason.

No SDK null check on interceptor return values

low · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:475

A null from interceptRequest becomes Future.successful(null). A null from interceptResponse becomes McpToolCallResult(null, isError).

The SDK relies on the runtime to reject null, and the runtime error does not name the user's interceptor. InterceptingSessionMemory.requireNonNullResult already fails fast with a message that names the hook.

Identity check in interceptResponse and the test that pins it

low · akka-javasdk/src/main/scala/akka/javasdk/impl/agent/AgentImpl.scala:491

if (text eq result.text) result else ... saves one allocation, and the runtime does not compare identity. AgentImplMcpToolInterceptorSpec.scala:90 asserts theSameInstanceAs.

The branch adds code for no behaviour, and the test pins an implementation detail. A change that builds a new, equal result fails the test.

Test comments describe history

low · akka-javasdk/src/test/java/akka/javasdk/impl/agent/SessionMemoryEventSerializationTest.java:76

The comments here and at line 104 say "stored before the error flag existed".

The project rules ban development history in comments.

Missing-field tests cover only the text variants

low · akka-javasdk/src/test/java/akka/javasdk/impl/agent/SessionMemoryEventSerializationTest.java:78

No test reads a MultimodalToolResponseMessageAdded event or an MTCR snapshot message without isError.

Each multimodal record now has three constructors, so a regression in old-data reading for those types would pass.

New error-flag test duplicates the history helper

low · akka-javasdk/src/test/scala/akka/javasdk/impl/agent/AgentImplContextMessagesSpec.scala:53

The test rebuilds ts, contents and a SessionHistory that the history helper at line 20 already builds.

The two setups can drift apart.

Await in the new spec

low · akka-javasdk/src/test/scala/akka/javasdk/impl/agent/AgentImplMcpToolInterceptorSpec.scala:60

The spec uses Await.result, and Await.ready with failure.value.get.failed.get. The @volatile fields are not needed, because Future.fromTry runs on the calling thread.

Other specs in the module use ScalaFutures, so this spec reads differently from its neighbours.

Third copy of the same test fixtures

low · akka-javasdk/src/test/scala/akka/javasdk/impl/agent/AgentImplToolResponseSpec.scala:92

The new test adds a third identical text and image pair. The other two are at lines 55-59 and 75-79.

Three copies of the same fixture must change together.

New docs sentence sits before an unrelated snippet

low · docs/src/modules/sdk/pages/agents/extending.adoc:127

The sentence about context.isError() comes right before the mcp-function-tool snippet, which shows no interceptor.

A reader looks for isError in the code below and does not find it.

@johanandren
johanandren force-pushed the fix-mcp-tool-error-flag branch from 19c6565 to c499049 Compare October 13, 2026 10:27
@johanandren

Copy link
Copy Markdown
Contributor Author

Feedback mostly applied, some not:

Not applied

  • Identity check in interceptResponse: kept. It returns the original result when the interceptor leaves the text unchanged. The spec no longer pins it with theSameInstanceAs, and now checks the text
    and the flag instead.
  • Tool response to event mapping written twice in SessionMemoryEntity: the duplication predates this PR. A separate refactor PR fits better than this fix.
  • Docs sentence before an unrelated snippet in extending.adoc: the sentence is part of the interceptor paragraph that feat: ToolCallGuardrails on MCP tools #1995 added, and that whole paragraph comes before the snippet. Moving only the
    isError sentence would split the paragraph.
  • isError() is always false in interceptRequest: kept as is. The javadoc states it. A request has no result yet, so there is no error state to report. The method is now a default method, so
    hand-written test doubles of the context still compile.
  • Guardrails and the compaction sample do not see the flag: outside the scope of this PR. Guardrail.Message.ToolCallResponse and CompactionAgent need their own change. I will open an issue.
  • Runtime gap with a built-in tool and other tools in one response: this is a runtime bug, not part of the SDK contract. It is not documented in the SDK. I will report it to the runtime.

Resolved in another way

  • SDK null check on interceptor return values: the runtime fails the tool call with a message that names the hook. feat: ToolCallGuardrails on MCP tools #1995 documents this in the javadoc and in extending.adoc.
  • toolName() returns the MCP server name, and the ledger records the arguments that interceptRequest returns: feat: ToolCallGuardrails on MCP tools #1995 documents both. The toolName() javadoc now also covers renamed tools.
  • Incompatible adapter and duplicate spec from feat: ToolCallGuardrails on MCP tools #1995: resolved in the rebase. The branch keeps the McpToolCallHooksAdapter from feat: ToolCallGuardrails on MCP tools #1995 with the error flag added. The unique checks from
    AgentImplMcpToolInterceptorSpec moved into AgentImplMcpToolsSpec, and the duplicate spec is gone. The points about toSpiMcpToolCallHooks visibility and Await in that spec no longer apply.

@patriknw

Copy link
Copy Markdown
Contributor

When you rebase this, pay attention to some possible silent conflicts, see #1995 (comment)

@johanandren
johanandren force-pushed the fix-mcp-tool-error-flag branch from c499049 to 6ba0cd1 Compare October 13, 2026 11:36
@johanandren
johanandren force-pushed the fix-mcp-tool-error-flag branch from 6ba0cd1 to b8b7dd6 Compare October 13, 2026 11:53

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@patriknw
patriknw merged commit b298d0b into main Oct 13, 2026
38 checks passed
@patriknw
patriknw deleted the fix-mcp-tool-error-flag branch October 13, 2026 12:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants