View a markdown version of this page

Multi-profile support - Agent Toolkit for AWS
How it worksConfigurationPrerequisitesSecurity considerationsExample use cases

Multi-profile support

When using the MCP Proxy for AWS with the AWS MCP Server, you can configure multiple AWS CLI profiles to switch between accounts or roles on a per-call basis. The proxy adds an aws_profile parameter to the server's auth-requiring tools, letting the agent route each request through a different set of credentials without restarting.

Note

This feature is specific to the AWS MCP Server. Profile switching is not available when proxying to other MCP servers.

Profile switching is a client-side feature of the MCP Proxy for AWS, so it behaves the same in every AWS Region that the AWS MCP Server supports. The proxy strips the aws_profile parameter before it forwards the request, which means the Region that you connect to has no effect on whether the parameter is available.

Important

Multi-profile switching requires SigV4 authentication with the MCP Proxy for AWS. OAuth authentication does not support this feature. If you use OAuth, each session is bound to a single IAM role and switching accounts requires re-authentication.

How it works

  1. You configure the proxy with multiple profiles at startup (via the --profile flag or AWS_MCP_PROXY_PROFILES environment variable).

  2. The proxy adds an aws_profile parameter into the tool schema for run_script, get_presigned_url, and get_tasks.

  3. When the agent makes a tool call:

    • Without aws_profile: the proxy signs with the default (first) profile.

    • With aws_profile="dev": the proxy routes through a dedicated connection signed with the dev profile's credentials.

    • With an invalid profile: the proxy rejects the call with an error listing allowed profiles.

  4. The aws_profile parameter is stripped before forwarding to the backend — the AWS MCP Server never sees it.

Configuration

Configure multiple profiles using either the CLI flag or the environment variable.

CLI flag

The first profile is the default. Additional profiles are switchable:

mcp-proxy-for-aws-cli https://aws-mcp.us-east-1.api.aws/mcp --profile prod-readonly dev staging
Environment variable

Same behavior, useful for plugin integration where CLI args cannot be modified:

AWS_MCP_PROXY_PROFILES="prod-readonly dev staging"
Note

AWS_MCP_PROXY_PROFILES takes precedence over --profile and AWS_PROFILE when set.

Example MCP config

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": ["mcp-proxy-for-aws-cli@latest", "https://aws-mcp.us-east-1.api.aws/mcp"],
      "env": {
        "AWS_MCP_PROXY_PROFILES": "prod-readonly dev staging"
      }
    }
  }
}

Prerequisites

  • Two or more AWS CLI profiles configured in ~/.aws/config and ~/.aws/credentials, and passed to the proxy at startup with the --profile flag or the AWS_MCP_PROXY_PROFILES environment variable. The proxy adds the aws_profile parameter only when you make more than one profile available to it.

  • mcp-proxy-for-aws version 1.6.0 or later. The latest version is 1.6.3.

  • SigV4 authentication. OAuth does not support multi-profile switching.

  • Valid IAM permissions for each profile. Each profile should have the minimum permissions required for the operations the agent will perform.

Note

If the aws_profile parameter doesn't appear in the run_script, get_presigned_url, or get_tasks tool schemas, check each of the following common causes in turn:

  • A single profile passed to the proxy.

  • An mcp-proxy-for-aws version that is earlier than the minimum.

  • The use of OAuth instead of SigV4.

The AWS Region that you connect to is not a cause — the parameter is added by the proxy on your machine and is never sent to the AWS MCP Server.

The proxy reads your profiles only at startup. Switching between profiles that the proxy already loaded never requires a restart, but a profile that you add to ~/.aws/config while the proxy is running is not picked up until you restart the proxy or your agent.

Security considerations

  • Explicit allowlist: Only profiles declared at startup are available. The agent cannot discover or use other profiles in ~/.aws/config.

  • Stateless routing: Each call carries its own identity. No shared session state means parallel requests cannot interfere with each other.

  • Least privilege: Configure profiles with the minimum permissions needed. Consider using a read-only profile as the default and requiring explicit selection of write-capable profiles.

  • Client-side gating: For additional control (for example, requiring manual approval before using a production profile), configure client-side hooks or permission rules in your MCP client.

Example use cases

  • Cross-account cost comparison: "Compare Lambda invocation costs between my dev and prod accounts."

  • Security audit: "Check all S3 buckets across my three accounts for public access."

  • Troubleshooting: "List failed ECS tasks in staging, then check the same service config in prod."

  • Resource inventory: "Count EC2 instances across all my accounts."