fix: stale credentials issue

[anasstahr]

Summary

Changes

• Added ToolErrorMiddleware that wraps every tool call with a timeout and error handler, ensuring the proxy never hangs on stale credentials or unresponsive endpoints
• Added --tool-timeout CLI flag (default: 300s) to configure the maximum duration for a tool call
• Added credential error detection (401/403) with actionable suggestions to use --profile or aws sso login
• Updated README troubleshooting section with guidance on authentication errors and the new --tool-timeout flag

User experience

When a user's credentials expire mid-session, they now get an actionable error message suggesting --profile or aws sso login instead of the client hanging indefinitely. The server will need to be restarted for new credential configuration to take effect.

Testing

1. Start a session with credentials that expire in 15 minutes
2. Make at least one successful request
3. Wait for credentials to expire
4. Make a new request
5. Previously: client hangs → Now: returns an error with remediation guidance

Testing isError propagation:

import asyncio
import fastmcp
from fastmcp import Client
from mcp_proxy_for_aws.middleware.tool_error_middleware import ToolErrorMiddleware


async def main():
    """Run the isError e2e test."""
    server = fastmcp.FastMCP("test")
    server.add_middleware(ToolErrorMiddleware(tool_call_timeout=5.0))

    @server.tool()
    def boom() -> str:
        raise RuntimeError("something broke")

    client = Client(server)
    async with client:
        result = await client.call_tool("boom", {}, raise_on_error=False)
        is_error = getattr(result, "is_error", None)
        print(f"isError = {is_error}")


if __name__ == "__main__":
    asyncio.run(main())

Output:

Tool call 'boom' failed: Error calling tool 'boom': something broke.
isError = True

Checklist

• I have reviewed the contributing guidelines
• I have performed a self-review of this change
• Changes have been tested
• Changes are documented

Is this a breaking change?

• Yes
• No

• Did integration tests succeed?
• If the feature is a new use case, is it necessary to add a new integration test case?

Acknowledgment

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[arnewouters]

Don't forget to run/install the pre-commit hooks :)

[arnewouters]

Do we want to create a new variable for tool call timeouts? Is there another place where read_timeout is used? Trying to understand if this is a new feature or a miss that we are fixing now

[anasstahr]

Yes we will need a new variable, the read timeout and the tool timeout are 2 different things

[arnewouters]

Suggested change

	'--tool-error-timeout',
	'--tool-timeout',

[arnewouters]

Do we really have to define a new class?

[anasstahr]

yes
fastmcp's ToolResult doesn't expose isError
Subclassing and overriding to_mcp_result() is the only way to set isError=True

  # ToolResult.__init__ — no isError parameter
  def __init__(
      self,
      content: list[ContentBlock] | Any | None = None,
      structured_content: dict[str, Any] | Any | None = None,
      meta: dict[str, Any] | None = None,
  ):

  # ToolResult.to_mcp_result() — never sets isError
  def to_mcp_result(self):
      if self.meta is not None:
          return CallToolResult(content=self.content, _meta=self.meta)  # no isError
      if self.structured_content is None:
          return self.content  # bare list, not even a CallToolResult
      return self.content, self.structured_content  # tuple, not a CallToolResult

[arnewouters]

I believe we can raise a ToolError instead of creating a new class and returning that. It should have isError set.

    async def test_specific_tool_errors_are_sent_to_client(self):
        mcp = FastMCP("TestServer")

        @mcp.tool
        def custom_error_tool():
            raise ToolError("This is a test error (abc)")

        client = Client(transport=FastMCPTransport(mcp))

        async with client:
            result = await client.call_tool_mcp("custom_error_tool", {})
            assert result.isError
            assert isinstance(result.content[0], TextContent)
            assert "test error" in result.content[0].text
            assert "abc" in result.content[0].text