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.

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 call_aws, run_script, get_presigned_url, get_tasks, and suggest_aws_commands.

  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 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==1.6.0", "https://aws-mcp.us-east-1.api.aws/mcp"],
      "env": {
        "AWS_MCP_PROXY_PROFILES": "prod-readonly dev staging"
      }
    }
  }
}

Prerequisites

  • AWS CLI profiles configured in ~/.aws/config and ~/.aws/credentials for each profile you want to use.

  • mcp-proxy-for-aws version 1.6.0 or later.

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

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."