[adgregory]

🐛 Bug-fix PR

📌 Summary

Closes #7055.

With stateful sessions and session affinity enabled, tools/call on /servers/<id>/mcp is rerouted to /rpc. On that path a failed or policy-blocked tool call came back as a JSON-RPC protocol error, which MCP clients do not show to the model: a plugin denial arrived as -32602 Plugin Violation: ... and a ToolInvocationError (such as "Please authorize first") as -32603 Internal error, with the message dropped. In claude.ai the model saw only a generic failure.

This PR reports those failures inside the result with isError: true, the same way call_tool in the streamable HTTP transport already does since #6868.

🔁 Reproduction Steps

See #7055. In short: USE_STATEFUL_SESSIONS=true, MCPGATEWAY_SESSION_AFFINITY_ENABLED=true, then a tools/call with an Mcp-Session-Id that a tool_pre_invoke plugin denies, or that targets a per-user OAuth gateway the caller has not authorized.

🐞 Root Cause

mcpgateway/main.py, handle_rpc, tools/call branch: PluginViolationError is re-raised to plugin_violation_exception_handler, which builds a JSON-RPC error for every method, and ToolInvocationError falls through to the generic handler (-32603 Internal error).

💡 Fix Description

In the tools/call branch only, catch ToolInvocationError and PluginViolationError around _execute_rpc_tools_call and return:

{"content": [{"type": "text", "text": "<str(exc)>"}], "isError": true}

The text is str(exc), matching the streamable transport. Unchanged on purpose:

• other methods (their protocol errors stay);
• unknown tools and malformed requests;
• PluginError (a plugin that crashed is not a tool-call outcome);
• the Rust-forwarded /_internal/mcp/tools/call path, which has its own handling and test (test_call_plugin_violation_returns_jsonrpc_format). Happy to align it in a follow-up if maintainers want both paths identical.

📏 Reviewability

• This PR has one clear purpose
• The linked issue is not labeled triage — new issue; will need triage
• Unrelated bugs or improvements are tracked in separate issues/PRs
• Tests are included with the code they validate
• If AI-assisted, I understand and can explain the generated changes

🧪 Verification

Three new tests in tests/unit/mcpgateway/test_rpc_tool_invocation.py (TestRPCToolsCallFailuresAreToolResults):

• test_plugin_violation_is_an_iserror_result: fails on unmodified main (gets -32602 Plugin Violation), passes with the fix.
• test_tool_invocation_error_is_an_iserror_result: fails on unmodified main (gets -32603 Internal error), passes with the fix.
• test_plugin_error_stays_a_protocol_error: guard that a crashed plugin keeps its JSON-RPC error; passes before and after.

Check	Command	Result
New and related tests	pytest tests/unit/mcpgateway/test_rpc_tool_invocation.py tests/unit/mcpgateway/test_main_error_handlers.py	✅ 73 passed
Main, method registry, transports	pytest -n auto tests/unit/mcpgateway/test_main.py tests/unit/mcpgateway/test_main_extended.py tests/unit/mcpgateway/test_mcp_method_registry.py tests/unit/mcpgateway/transports	✅ 1898 passed, 1 skipped
Formatting and lint on changed files	black --check, ruff check	✅
Full suite	make test	⚠️ not run locally; only the suites above

isort --check-only flags test_rpc_tool_invocation.py, but for pre-existing imports that main already has; this PR does not touch them.

End to end: we run the PluginViolationError half of this change as a patch on v1.0.10 behind claude.ai custom connectors. Policy denials and "system not connected, connect it at " denials now reach the model, which relays them to the person.

📐 MCP Compliance

MCP specification, Tools, Error Handling: protocol errors for unknown tools and invalid arguments; tool execution errors in the result with isError: true.

✅ Checklist

• Code formatted (black), lint clean (ruff) on changed files
• No secrets or credentials committed
• Commit signed off (DCO)