feat: make httpx connection pool size configurable via flags and env

The single shared httpx.AsyncClient that serves all proxied MCP tool
calls was constructed with a hardcoded
httpx.Limits(max_keepalive_connections=1, max_connections=5). MCP
clients that fan out parallel aws_* tool calls per turn (Claude Code,
opencode — typically 4-8 concurrent) saturate the 5-connection pool,
causing intermittent failures.

Expose the pool size via new CLI flags --max-connections /
--max-keepalive-connections with environment-variable fallbacks
MCP_PROXY_MAX_CONNECTIONS / MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS. The two
values are threaded from cli -> server -> create_transport_with_sigv4 ->
create_sigv4_client, and through the per-profile override middleware.

Defaults are unchanged: max_connections=5, max_keepalive_connections=1,
so existing deployments behave byte-for-byte as before. A backward-
compat test asserts the default limits equal the original hardcoded
Limits object.

Scope: pool-sizing knob only. Does not touch the auth-path
serialization (_sign_request_hook / next(auth_flow)), which is tracked
separately in #270.

Fixes #295

Author: valter-silva-au

README.md

@@ -112,6 +112,8 @@ docker build -t mcp-proxy-for-aws .
 | `--tool-timeout`	   | Maximum seconds a tool call may take before being cancelled. When set, returns a graceful error to the agent instead of hanging indefinitely	                                                                                             | 300	                                                                    |No	|
 | `--skip-auth`         | Skip request signing when AWS credentials are unavailable instead of failing                                                                                                                                                             | `False`                                                                     |No	|
 | `--disable-telemetry` | Disables telemetry data collection                                                                                                                                                                                                      | `False`                                                                     |No	|
+| `--max-connections`   | Maximum number of concurrent HTTP connections in the shared pool used for all proxied tool calls. Increase this when your MCP client fans out parallel `aws_*` tool calls per turn (e.g. Claude Code, opencode).                          | 5 (falls back to `MCP_PROXY_MAX_CONNECTIONS`)                               |No	|
+| `--max-keepalive-connections` | Maximum number of idle keep-alive connections to retain in the pool                                                                                                                                                             | 1 (falls back to `MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS`)                     |No	|
 
 ### Optional Environment Variables
 
@@ -131,9 +133,16 @@ export AWS_REGION=<aws_region>
 
 # Multi-profile switching (alternative to --profile flag, useful for plugin integration)
 export AWS_MCP_PROXY_PROFILES="prod-readonly dev staging"
+
+# HTTP connection pool sizing (alternative to --max-connections / --max-keepalive-connections)
+# Raise the pool size when your MCP client issues many parallel aws_* tool calls per turn.
+export MCP_PROXY_MAX_CONNECTIONS=25
+export MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS=5
 ```
 
 > **Note:** `AWS_MCP_PROXY_PROFILES` takes precedence over `--profile` / `AWS_PROFILE` when set.
+>
+> **Note:** `--max-connections` / `--max-keepalive-connections` take precedence over `MCP_PROXY_MAX_CONNECTIONS` / `MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS` when explicitly passed. Defaults are `5` / `1`, preserving the previous behavior.
 
 ### Multi-account access
 

mcp_proxy_for_aws/cli.py

@@ -17,7 +17,7 @@
 import argparse
 import os
 from mcp_proxy_for_aws import __version__
-from mcp_proxy_for_aws.utils import within_range
+from mcp_proxy_for_aws.utils import positive_int, within_range
 from typing import Any, Dict, Optional, Sequence
 
 
@@ -185,4 +185,22 @@ def parse_args():
         help='Skip request signing when AWS credentials are unavailable instead of failing',
     )
 
+    parser.add_argument(
+        '--max-connections',
+        type=positive_int(1),
+        default=positive_int(1)(os.getenv('MCP_PROXY_MAX_CONNECTIONS', '5')),
+        help='Maximum number of concurrent HTTP connections in the pool used for all '
+        'proxied tool calls. Increase this when your MCP client fans out parallel '
+        'aws_* tool calls per turn (default: 5). '
+        'Falls back to MCP_PROXY_MAX_CONNECTIONS if not set.',
+    )
+
+    parser.add_argument(
+        '--max-keepalive-connections',
+        type=positive_int(0),
+        default=positive_int(0)(os.getenv('MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS', '1')),
+        help='Maximum number of idle keep-alive connections to retain in the pool '
+        '(default: 1). Falls back to MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS if not set.',
+    )
+
     return parser.parse_args()

mcp_proxy_for_aws/middleware/profile_switcher.py

@@ -66,6 +66,8 @@ def __init__(
         endpoint: str,
         disable_telemetry: bool = False,
         skip_auth: bool = False,
+        max_connections: int = 5,
+        max_keepalive_connections: int = 1,
     ) -> None:
         """Initialize the middleware with connection and profile configuration."""
         super().__init__()
@@ -78,6 +80,8 @@ def __init__(
         self._timeout = timeout
         self._disable_telemetry = disable_telemetry
         self._skip_auth = skip_auth
+        self._max_connections = max_connections
+        self._max_keepalive_connections = max_keepalive_connections
         self._profile_clients: dict[str, Client] = {}
         self._lock = asyncio.Lock()
 
@@ -172,6 +176,8 @@ async def _get_profile_client(self, profile: str) -> Client:
                     profile,
                     self._disable_telemetry,
                     self._skip_auth,
+                    self._max_connections,
+                    self._max_keepalive_connections,
                 )
                 client = Client(transport=transport)
                 await client.__aenter__()

mcp_proxy_for_aws/server.py

@@ -108,6 +108,8 @@ async def run_proxy(args) -> None:
         default_profile,
         args.disable_telemetry,
         args.skip_auth,
+        args.max_connections,
+        args.max_keepalive_connections,
     )
     client_factory = AWSMCPProxyClientFactory(transport)
 
@@ -138,6 +140,8 @@ async def run_proxy(args) -> None:
             args.endpoint,
             args.disable_telemetry,
             args.skip_auth,
+            args.max_connections,
+            args.max_keepalive_connections,
         )
 
         if args.retries:
@@ -174,6 +178,8 @@ def add_profile_override_middleware(
     endpoint: str,
     disable_telemetry: bool = False,
     skip_auth: bool = False,
+    max_connections: int = 5,
+    max_keepalive_connections: int = 1,
 ) -> ProfileOverrideMiddleware | None:
     """Add profile override middleware to target MCP server.
 
@@ -188,6 +194,8 @@ def add_profile_override_middleware(
         endpoint: The MCP endpoint URL
         disable_telemetry: Whether to disable telemetry on profile transports
         skip_auth: Whether to skip signing when credentials are unavailable
+        max_connections: Maximum concurrent connections per profile transport pool
+        max_keepalive_connections: Maximum idle keep-alive connections per profile pool
 
     Returns:
         The ProfileOverrideMiddleware instance if added, None otherwise
@@ -207,6 +215,8 @@ def add_profile_override_middleware(
         endpoint=endpoint,
         disable_telemetry=disable_telemetry,
         skip_auth=skip_auth,
+        max_connections=max_connections,
+        max_keepalive_connections=max_keepalive_connections,
     )
     mcp.add_middleware(middleware)
     return middleware

mcp_proxy_for_aws/sigv4_helper.py

@@ -183,6 +183,8 @@ def create_sigv4_client(
     metadata: Optional[Dict[str, Any]] = None,
     disable_telemetry: bool = False,
     skip_auth: bool = False,
+    max_connections: int = 5,
+    max_keepalive_connections: int = 1,
     **kwargs: Any,
 ) -> httpx.AsyncClient:
     """Create an httpx.AsyncClient with SigV4 authentication.
@@ -196,6 +198,10 @@ def create_sigv4_client(
         metadata: Metadata to inject into MCP _meta field
         disable_telemetry: Whether to disable telemetry
         skip_auth: Whether to skip signing when credentials are unavailable
+        max_connections: Maximum number of concurrent connections in the pool
+            (default: 5, preserving historical behavior)
+        max_keepalive_connections: Maximum number of idle keep-alive connections
+            to retain (default: 1, preserving historical behavior)
         **kwargs: Additional arguments to pass to httpx.AsyncClient
 
     Returns:
@@ -205,7 +211,10 @@ def create_sigv4_client(
     client_kwargs = {
         'follow_redirects': True,
         'timeout': timeout,
-        'limits': httpx.Limits(max_keepalive_connections=1, max_connections=5),
+        'limits': httpx.Limits(
+            max_keepalive_connections=max_keepalive_connections,
+            max_connections=max_connections,
+        ),
         **kwargs,
     }
 

mcp_proxy_for_aws/utils.py

@@ -75,6 +75,8 @@ def create_transport_with_sigv4(
     profile: Optional[str] = None,
     disable_telemetry: bool = False,
     skip_auth: bool = False,
+    max_connections: int = 5,
+    max_keepalive_connections: int = 1,
 ) -> StreamableHttpTransport:
     """Create a StreamableHttpTransport with SigV4 authentication.
 
@@ -87,6 +89,10 @@ def create_transport_with_sigv4(
         profile: AWS profile to use (optional)
         disable_telemetry: Whether to disable telemetry
         skip_auth: Whether to skip signing when credentials are unavailable
+        max_connections: Maximum number of concurrent connections in the pool
+            (default: 5, preserving historical behavior)
+        max_keepalive_connections: Maximum number of idle keep-alive connections
+            to retain (default: 1, preserving historical behavior)
 
     Returns:
         StreamableHttpTransport instance with SigV4 authentication
@@ -107,6 +113,8 @@ def client_factory(
             metadata=metadata,
             disable_telemetry=disable_telemetry,
             skip_auth=skip_auth,
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
             auth=auth,
             **kw,
         )
@@ -247,3 +255,37 @@ def validator(value):
         return fvalue
 
     return validator
+
+
+def positive_int(min_value: int, max_value: Optional[int] = None):
+    """Factory function to create integer range validators.
+
+    Mirrors ``within_range`` but parses and returns ``int`` instead of ``float``,
+    which is the correct type for discrete counts such as connection-pool sizes.
+
+    Args:
+        min_value: Minimum allowed value (inclusive)
+        max_value: Maximum allowed value (inclusive), or None for no upper bound
+
+    Returns:
+        The argparse validator function
+
+    Raises:
+        argparse.ArgumentTypeError: If the value is not an integer within range
+    """
+
+    def validator(value):
+        try:
+            ivalue = int(value)
+        except (ValueError, TypeError):
+            raise argparse.ArgumentTypeError(f"'{value}' is not a valid integer")
+
+        if ivalue < min_value:
+            raise argparse.ArgumentTypeError(f"'{value}' must be >= {min_value}")
+
+        if max_value is not None and ivalue > max_value:
+            raise argparse.ArgumentTypeError(f"'{value}' must be <= {max_value}")
+
+        return ivalue
+
+    return validator

tests/unit/test_cli.py

@@ -202,3 +202,93 @@ def test_parse_args_disable_telemetry_default(self):
         args = parse_args()
 
         assert args.disable_telemetry is False
+
+    @patch.dict('os.environ', {}, clear=True)
+    @patch('sys.argv', ['mcp-proxy-for-aws', 'https://test.example.com'])
+    def test_parse_args_connection_pool_defaults(self):
+        """Pool sizing flags default to today's 5/1 behavior when unset."""
+        args = parse_args()
+
+        assert args.max_connections == 5
+        assert args.max_keepalive_connections == 1
+
+    @patch.dict('os.environ', {}, clear=True)
+    @patch(
+        'sys.argv',
+        [
+            'mcp-proxy-for-aws',
+            'https://test.example.com',
+            '--max-connections',
+            '25',
+            '--max-keepalive-connections',
+            '10',
+        ],
+    )
+    def test_parse_args_connection_pool_flags(self):
+        """Pool sizing flags parse from the command line."""
+        args = parse_args()
+
+        assert args.max_connections == 25
+        assert args.max_keepalive_connections == 10
+
+    @patch.dict(
+        'os.environ',
+        {
+            'MCP_PROXY_MAX_CONNECTIONS': '40',
+            'MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS': '8',
+        },
+        clear=True,
+    )
+    @patch('sys.argv', ['mcp-proxy-for-aws', 'https://test.example.com'])
+    def test_parse_args_connection_pool_from_env(self):
+        """Pool sizing falls back to env vars when flags are absent."""
+        args = parse_args()
+
+        assert args.max_connections == 40
+        assert args.max_keepalive_connections == 8
+
+    @patch.dict(
+        'os.environ',
+        {
+            'MCP_PROXY_MAX_CONNECTIONS': '40',
+            'MCP_PROXY_MAX_KEEPALIVE_CONNECTIONS': '8',
+        },
+        clear=True,
+    )
+    @patch(
+        'sys.argv',
+        [
+            'mcp-proxy-for-aws',
+            'https://test.example.com',
+            '--max-connections',
+            '25',
+            '--max-keepalive-connections',
+            '10',
+        ],
+    )
+    def test_parse_args_connection_pool_cli_overrides_env(self):
+        """Explicit pool flags take precedence over env vars."""
+        args = parse_args()
+
+        assert args.max_connections == 25
+        assert args.max_keepalive_connections == 10
+
+    @patch.dict('os.environ', {}, clear=True)
+    @patch(
+        'sys.argv',
+        ['mcp-proxy-for-aws', 'https://test.example.com', '--max-connections', '0'],
+    )
+    def test_parse_args_max_connections_below_minimum(self):
+        """--max-connections must be >= 1 (within_range validation)."""
+        with pytest.raises(SystemExit):
+            parse_args()
+
+    @patch.dict('os.environ', {}, clear=True)
+    @patch(
+        'sys.argv',
+        ['mcp-proxy-for-aws', 'https://test.example.com', '--max-keepalive-connections', '-1'],
+    )
+    def test_parse_args_max_keepalive_connections_below_minimum(self):
+        """--max-keepalive-connections must be >= 0 (within_range validation)."""
+        with pytest.raises(SystemExit):
+            parse_args()

tests/unit/test_profile_switcher.py

@@ -808,4 +808,6 @@ async def test_all_params_forwarded_to_transport_factory(self, mock_context):
             'dev-profile',
             True,
             True,
+            5,
+            1,
         )

tests/unit/test_sigv4_helper.py

@@ -292,6 +292,47 @@ def test_create_sigv4_client_registers_user_agent_request_hook(
         # reflected on every request, including the signed one.
         assert request_hooks[0].func is _set_user_agent_hook
 
+    @patch('mcp_proxy_for_aws.sigv4_helper.get_client_info', return_value=None)
+    @patch('httpx.AsyncClient')
+    def test_create_sigv4_client_default_connection_limits(
+        self, mock_client_class, mock_get_client_info
+    ):
+        """Default limits MUST preserve historical 5/1 pool behavior byte-for-byte."""
+        mock_client = Mock()
+        mock_client_class.return_value = mock_client
+
+        create_sigv4_client(service='test-service', region='test-region')
+
+        call_args = mock_client_class.call_args
+        limits = call_args[1]['limits']
+        assert isinstance(limits, httpx.Limits)
+        assert limits.max_connections == 5
+        assert limits.max_keepalive_connections == 1
+        # Backward compatibility guard: identical to the original hardcoded Limits.
+        assert limits == httpx.Limits(max_keepalive_connections=1, max_connections=5)
+
+    @patch('mcp_proxy_for_aws.sigv4_helper.get_client_info', return_value=None)
+    @patch('httpx.AsyncClient')
+    def test_create_sigv4_client_custom_connection_limits(
+        self, mock_client_class, mock_get_client_info
+    ):
+        """Explicit pool overrides MUST flow into the httpx.AsyncClient limits."""
+        mock_client = Mock()
+        mock_client_class.return_value = mock_client
+
+        create_sigv4_client(
+            service='test-service',
+            region='test-region',
+            max_connections=25,
+            max_keepalive_connections=10,
+        )
+
+        call_args = mock_client_class.call_args
+        limits = call_args[1]['limits']
+        assert isinstance(limits, httpx.Limits)
+        assert limits.max_connections == 25
+        assert limits.max_keepalive_connections == 10
+
 
 class TestSetUserAgentHook:
     """Test cases for the per-request User-Agent hook."""