refactor: rename aws_profile to proxy_aws_profile and add AWS_MCP_PROXY_PROFILES env var

krishmakochhar · krishmakochhar · commit 6766c5f9b786 · 2026-05-17T23:58:03.000+02:00
- Renamed injected tool parameter from aws_profile to proxy_aws_profile
  to avoid potential collision with backend tool parameters (EKS MCP,
  ECS MCP, customer-hosted servers use the same proxy)
- Added AWS_MCP_PROXY_PROFILES env var support as alternative to --profile
  flag. Enables plugin integration where CLI args cannot be modified.
  Format: space-separated profile names, first is default.
- --profile flag takes precedence over env var when both are set
- Documented env var in README
- Added unit tests for env var parsing and precedence
diff --git a/README.md b/README.md
@@ -97,7 +97,7 @@ docker build -t mcp-proxy-for-aws .
 | `endpoint`	          | MCP endpoint URL (e.g., `https://your-service.us-east-1.amazonaws.com/mcp`)	                                                                                                                                                            | N/A	                                                                        |Yes	|
 | ---	                 | ---	                                                                                                                                                                                                                                    | ---	                                                                        |---	|
 | `--service`	         | AWS service name for SigV4 signing, if omitted we try to infer this from the url	                                                                                                                                                       | Inferred from endpoint if not provided	                                     |No	|
-| `--profile`	         | AWS profile(s) to use. First profile is the default. Additional profiles enable per-call switching via `aws_profile` tool parameter (e.g., `--profile default dev staging`) | Uses `AWS_PROFILE` environment variable if not set                          |No	|
+| `--profile`	         | AWS profile(s) to use. First profile is the default. Additional profiles enable per-call switching across accounts (e.g., `--profile default dev staging`) | Falls back to `AWS_MCP_PROXY_PROFILES` env var, then default credential chain                          |No	|
 | `--region`	          | AWS region to use	                                                                                                                                                                                                                      | Uses `AWS_REGION` environment variable if not set	                           |No	|
 | `--metadata`	        | Metadata to inject into MCP requests as key=value pairs (e.g., `--metadata KEY1=value1 KEY2=value2`)                                                                                                                                    | `AWS_REGION` is automatically injected based on `--region` if not provided    |No	|
 | `--read-only`	       | Disable tools which may require write permissions (tools which DO NOT require write permissions are annotated with [`readOnlyHint=true`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint)) | `False`	                                                                    |No	|
@@ -125,6 +125,10 @@ export AWS_SESSION_TOKEN=<session_token>
 
 # AWS Region
 export AWS_REGION=<aws_region>
+
+# Multi-profile switching (alternative to --profile flag)
+# Space-separated list: first is default, rest are switchable
+export AWS_MCP_PROXY_PROFILES="default dev staging"
 ```
 
 ### Setup Examples
@@ -167,12 +171,7 @@ Add the following configuration to your MCP client config file (e.g., for Kiro C
 
 #### Multi-account access
 
-When multiple profiles are passed to `--profile`, individual tool calls can route through different AWS profiles without restarting the proxy. This is useful when an AI agent needs to query resources across multiple AWS accounts in a single session.
-
-**How it works:**
-- The first profile is the **default** identity used when a tool call does not specify a profile.
-- Additional profiles are available for per-call switching via the `aws_profile` tool parameter. Each profile gets its own dedicated connection to the backend.
-- If a tool call omits `aws_profile`, the default profile connection is used. If it includes `aws_profile`, the request is routed through the matching per-profile connection instead.
+When multiple profiles are passed to `--profile`, the agent can route individual tool calls through different AWS accounts without restarting the proxy.
 
 ```json
 {
@@ -194,7 +193,31 @@ When multiple profiles are passed to `--profile`, individual tool calls can rout
 }
 ```
 
-In the example above, tool calls without an `aws_profile` argument use the `default` profile. A tool call that includes `"aws_profile": "dev-profile"` is routed through a dedicated connection signed with `dev-profile` credentials.
+**How it works:**
+- The first profile (`default`) is used for all calls unless the agent specifies otherwise.
+- The agent can switch to any additional profile (`dev-profile`, `staging-profile`) on a per-call basis. Each profile gets its own dedicated connection.
+- Only profiles in the list are accessible — other profiles in `~/.aws/config` are not exposed.
+- With a single profile (e.g., `--profile default`), no switching is available and behavior is unchanged from previous versions.
+
+**Using an environment variable:**
+
+As an alternative to `--profile`, set the `AWS_MCP_PROXY_PROFILES` environment variable:
+
+```bash
+export AWS_MCP_PROXY_PROFILES="default dev-profile staging-profile"
+```
+
+Or in your MCP configuration's `env` block:
+
+```json
+{
+  "env": {
+    "AWS_MCP_PROXY_PROFILES": "default dev-profile staging-profile"
+  }
+}
+```
+
+The `--profile` flag takes precedence over the environment variable if both are set.
 
 #### Using Docker
 
diff --git a/mcp_proxy_for_aws/cli.py b/mcp_proxy_for_aws/cli.py
@@ -94,7 +94,7 @@ def parse_args():
         nargs='+',
         dest='profiles',
         help='AWS profile(s) to use. First profile is the default. '
-        'Additional profiles enable per-call switching via aws_profile tool parameter '
+        'Additional profiles enable per-call switching via proxy_aws_profile tool parameter '
         '(e.g., --profile default dev staging)',
         default=[os.getenv('AWS_PROFILE')] if os.getenv('AWS_PROFILE') else None,
         metavar='PROFILE',
diff --git a/mcp_proxy_for_aws/middleware/profile_switcher.py b/mcp_proxy_for_aws/middleware/profile_switcher.py
@@ -12,9 +12,9 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Middleware that enables per-call AWS profile overrides via an ``aws_profile`` argument.
+"""Middleware that enables per-call AWS profile overrides via a ``proxy_aws_profile`` argument.
 
-Pass ``aws_profile`` as an extra argument on any tool call to route that single request
+Pass ``proxy_aws_profile`` as an extra argument on any tool call to route that single request
 through a dedicated transport signed with the specified profile's credentials. The
 argument is stripped before forwarding to the backend.
 
@@ -41,12 +41,12 @@
 
 
 class ProfileOverrideMiddleware(Middleware):
-    """Middleware that intercepts ``aws_profile`` on any tool call for per-request AWS identity switching.
+    """Middleware that intercepts ``proxy_aws_profile`` on any tool call for per-request AWS identity switching.
 
-    When a tool call includes an ``aws_profile`` argument, the middleware:
+    When a tool call includes a ``proxy_aws_profile`` argument, the middleware:
 
     1. Validates the profile against the allowed list
-    2. Strips ``aws_profile`` from the arguments
+    2. Strips ``proxy_aws_profile`` from the arguments
     3. Forwards the call through a dedicated per-profile MCP client
 
     Each profile gets its own transport and session to the backend so that
@@ -81,7 +81,7 @@ async def on_list_tools(
         context: MiddlewareContext[mt.ListToolsRequest],
         call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
     ) -> Sequence[Tool]:
-        """Inject ``aws_profile`` into every tool's schema."""
+        """Inject ``proxy_aws_profile`` into every tool's schema."""
         tools = await call_next(context)
 
         for tool in tools:
@@ -91,13 +91,13 @@ async def on_list_tools(
             params = copy.deepcopy(tool.parameters)
             if 'properties' not in params:
                 params['properties'] = {}
-            if 'aws_profile' in params['properties']:
+            if 'proxy_aws_profile' in params['properties']:
                 logger.warning(
-                    'Tool %r already defines an "aws_profile" parameter; '
+                    'Tool %r already defines a "proxy_aws_profile" parameter; '
                     'the middleware override is shadowing the backend definition.',
                     tool.name,
                 )
-            params['properties']['aws_profile'] = {
+            params['properties']['proxy_aws_profile'] = {
                 'type': 'string',
                 'description': (
                     'AWS CLI profile to sign this request with. Omit to use the default profile.'
@@ -116,10 +116,10 @@ async def on_call_tool(
         context: MiddlewareContext[mt.CallToolRequestParams],
         call_next: CallNext[mt.CallToolRequestParams, ToolResult],
     ) -> ToolResult:
-        """Intercept ``aws_profile`` and route through a dedicated per-profile client."""
+        """Intercept ``proxy_aws_profile`` and route through a dedicated per-profile client."""
         arguments = context.message.arguments
-        if isinstance(arguments, dict) and 'aws_profile' in arguments:
-            profile = arguments['aws_profile']
+        if isinstance(arguments, dict) and 'proxy_aws_profile' in arguments:
+            profile = arguments['proxy_aws_profile']
             return await self._call_with_profile(profile, context, call_next)
 
         return await call_next(context)
@@ -171,9 +171,9 @@ async def _call_with_profile(
                 f'Profile {profile!r} is not in the allowed list. Allowed profiles: {allowed}'
             )
 
-        # Strip aws_profile before forwarding to the backend
+        # Strip proxy_aws_profile before forwarding to the backend
         arguments: dict[str, Any] = dict(cast(dict[str, Any], context.message.arguments))
-        arguments.pop('aws_profile', None)
+        arguments.pop('proxy_aws_profile', None)
 
         logger.info(
             'Per-call profile override: routing through dedicated connection for %s', profile
diff --git a/mcp_proxy_for_aws/server.py b/mcp_proxy_for_aws/server.py
@@ -25,6 +25,7 @@
 import asyncio
 import httpx
 import logging
+import os
 from fastmcp.server.middleware.error_handling import RetryMiddleware
 from fastmcp.server.middleware.logging import LoggingMiddleware
 from fastmcp.server.providers.proxy import FastMCPProxy
@@ -64,8 +65,12 @@ async def run_proxy(args) -> None:
     if args.metadata:
         metadata.update(args.metadata)
 
-    # Get profile(s)
+    # Get profile(s) from CLI args or env var
     profiles: list[str] = args.profiles if args.profiles else []
+    if not profiles:
+        env_profiles = os.environ.get('AWS_MCP_PROXY_PROFILES')
+        if env_profiles:
+            profiles = env_profiles.split()
     default_profile = profiles[0] if profiles else None
     # Dedup switch profiles and exclude the default profile
     switch_profiles = list(dict.fromkeys(p for p in profiles[1:] if p != default_profile))
diff --git a/tests/unit/test_profile_switcher.py b/tests/unit/test_profile_switcher.py
@@ -52,8 +52,10 @@ class TestOnListTools:
     """Tests for the on_list_tools method."""
 
     @pytest.mark.asyncio
-    async def test_injects_aws_profile_property_into_tool_schemas(self, middleware, mock_context):
-        """Every proxied tool gets an aws_profile property in its schema."""
+    async def test_injects_proxy_aws_profile_property_into_tool_schemas(
+        self, middleware, mock_context
+    ):
+        """Every proxied tool gets an proxy_aws_profile property in its schema."""
         tool = Mock()
         tool.name = 'some_tool'
         tool.parameters = {'type': 'object', 'properties': {'arg': {'type': 'string'}}}
@@ -63,7 +65,7 @@ async def test_injects_aws_profile_property_into_tool_schemas(self, middleware,
 
         assert len(result) == 1
         assert result[0].name == 'some_tool'
-        profile_schema = result[0].parameters['properties']['aws_profile']
+        profile_schema = result[0].parameters['properties']['proxy_aws_profile']
         assert profile_schema['type'] == 'string'
         assert 'AWS CLI profile' in profile_schema['description']
         assert profile_schema['enum'] == sorted(ALLOWED_PROFILES)
@@ -102,15 +104,15 @@ async def test_adds_properties_key_when_missing(self, middleware, mock_context):
         result = await middleware.on_list_tools(mock_context, call_next)
 
         assert 'properties' in result[0].parameters
-        assert 'aws_profile' in result[0].parameters['properties']
+        assert 'proxy_aws_profile' in result[0].parameters['properties']
 
 
 class TestOnCallTool:
     """Tests for the on_call_tool method."""
 
     @pytest.mark.asyncio
-    async def test_passes_through_calls_without_aws_profile(self, middleware, mock_context):
-        """Tool calls without aws_profile are forwarded unchanged."""
+    async def test_passes_through_calls_without_proxy_aws_profile(self, middleware, mock_context):
+        """Tool calls without proxy_aws_profile are forwarded unchanged."""
         mock_context.message = Mock()
         mock_context.message.name = 'some_tool'
         mock_context.message.arguments = {'arg': 'value'}
@@ -145,7 +147,7 @@ async def test_profile_override_disallowed(self, middleware, mock_context):
         """Disallowed profile raises ToolError."""
         mock_context.message = Mock()
         mock_context.message.name = 'some_tool'
-        mock_context.message.arguments = {'arg': 'value', 'aws_profile': 'evil-profile'}
+        mock_context.message.arguments = {'arg': 'value', 'proxy_aws_profile': 'evil-profile'}
         call_next = AsyncMock()
 
         with pytest.raises(ToolError, match='not in the allowed list'):
@@ -154,8 +156,8 @@ async def test_profile_override_disallowed(self, middleware, mock_context):
         call_next.assert_not_called()
 
     @pytest.mark.asyncio
-    async def test_profile_override_strips_aws_profile_arg(self, middleware, mock_context):
-        """aws_profile is stripped before forwarding to the backend."""
+    async def test_profile_override_strips_proxy_aws_profile_arg(self, middleware, mock_context):
+        """proxy_aws_profile is stripped before forwarding to the backend."""
         mock_client = AsyncMock()
         mock_call_result = MagicMock()
         mock_call_result.content = 'result'
@@ -165,7 +167,7 @@ async def test_profile_override_strips_aws_profile_arg(self, middleware, mock_co
 
         mock_context.message = Mock()
         mock_context.message.name = 'some_tool'
-        mock_context.message.arguments = {'arg': 'value', 'aws_profile': 'dev-profile'}
+        mock_context.message.arguments = {'arg': 'value', 'proxy_aws_profile': 'dev-profile'}
         call_next = AsyncMock()
 
         with patch.object(middleware, '_get_profile_client', return_value=mock_client):
@@ -179,7 +181,7 @@ async def test_profile_override_connection_failure(self, middleware, mock_contex
         """Connection failure raises ToolError with sanitized message."""
         mock_context.message = Mock()
         mock_context.message.name = 'some_tool'
-        mock_context.message.arguments = {'arg': 'value', 'aws_profile': 'dev-profile'}
+        mock_context.message.arguments = {'arg': 'value', 'proxy_aws_profile': 'dev-profile'}
         call_next = AsyncMock()
 
         with patch.object(
@@ -198,7 +200,7 @@ async def test_profile_override_tool_call_failure(self, middleware, mock_context
 
         mock_context.message = Mock()
         mock_context.message.name = 'some_tool'
-        mock_context.message.arguments = {'arg': 'value', 'aws_profile': 'dev-profile'}
+        mock_context.message.arguments = {'arg': 'value', 'proxy_aws_profile': 'dev-profile'}
         call_next = AsyncMock()
 
         with patch.object(middleware, '_get_profile_client', return_value=mock_client):
diff --git a/tests/unit/test_server.py b/tests/unit/test_server.py
