aws-core: clarify --metadata AWS_REGION vs local region for mcp-proxy-for-aws credential refresh

[rema424]

Describe the bug

The AWS MCP Server setup docs and README examples show --metadata AWS_REGION=... as the way to set the default AWS Region for AWS MCP Server operations.

That is correct for AWS operations performed by the remote AWS MCP Server, but it does not configure the local Region used by botocore inside mcp-proxy-for-aws.

When using AWS CLI v2 aws login / SSO-style temporary credentials, mcp-proxy-for-aws may need a local Region from the normal AWS region provider chain, such as AWS_REGION, AWS_DEFAULT_REGION, or a Region configured in the active AWS profile. If no local Region is available, MCP initialization can fail before tools are exposed to the MCP client.

This is easy to miss because the current examples make --metadata AWS_REGION=... look like the only Region-related configuration needed.

Docs reviewed:

• https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md
• https://docs.aws.amazon.com/agent-toolkit/latest/userguide/quick-start.html
• https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html

Expected Behavior

The setup docs should make it clear that there are two different Region concepts:

• --metadata AWS_REGION=...: default Region for AWS operations performed by the remote AWS MCP Server
• AWS_REGION / AWS_DEFAULT_REGION / AWS profile Region: local Region used by botocore inside mcp-proxy-for-aws, including during credential refresh

Users of AWS CLI v2 aws login / SSO-style credentials should be able to configure the AWS MCP Server from the docs without hitting a local botocore NoRegionError.

It would be helpful if the setup examples included an optional env section showing AWS_REGION and/or AWS_DEFAULT_REGION.

Current Behavior

Using the documented configuration pattern with mcp-proxy-for-aws@latest, the MCP server failed to initialize and AWS MCP tools were not exposed to the MCP client.

Examples of unavailable tools:

• aws___call_aws
• aws___run_script
• aws___search_documentation

Debug logs from mcp-proxy-for-aws showed:

botocore.exceptions.NoRegionError: You must specify a region.

The failure occurred while botocore was refreshing temporary credentials locally, before AWS MCP tools became available.

Adding local Region environment variables to the MCP server process fixed the issue. For example, in Codex TOML config:

[mcp_servers.aws_mcp]
command = "uvx"
args = [
  "mcp-proxy-for-aws@latest",
  "https://aws-mcp.us-east-1.api.aws/mcp",
  "--metadata", "AWS_REGION=ap-northeast-1"
]
startup_timeout_sec = 60

[mcp_servers.aws_mcp.env]
AWS_REGION = "ap-northeast-1"
AWS_DEFAULT_REGION = "ap-northeast-1"

For JSON-based MCP clients, the equivalent is to pass environment variables to the MCP server process:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=ap-northeast-1"
      ],
      "env": {
        "AWS_REGION": "ap-northeast-1",
        "AWS_DEFAULT_REGION": "ap-northeast-1"
      }
    }
  }
}

After restarting the MCP client with those environment variables, AWS MCP tools became available, including aws___call_aws and aws___run_script.

Reproduction Steps

1. Use AWS CLI v2 aws login / SSO-style temporary credentials.
2. Ensure the local environment used by the MCP client does not provide a Region through AWS_REGION, AWS_DEFAULT_REGION, or the active AWS profile.
3. Configure AWS MCP Server using the documented pattern, for example:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata",
        "AWS_REGION=ap-northeast-1"
      ]
    }
  }
}

4. Restart the MCP client.
5. Observe that AWS MCP tools are not exposed.
6. Run with mcp-proxy-for-aws DEBUG logging.
7. Observe botocore.exceptions.NoRegionError during local credential refresh.

Plugin Version

aws-core@agent-toolkit-for-aws 1.0.0 Also observed with: - mcp-proxy-for-aws@latest - mcp-proxy-for-aws 1.5.0

AI Assistant

Codex Desktop / Codex

AI Assistant Version

Codex Desktop 0.133.0

OS

macOS

Other information

This does not appear to be specific to Codex. The same issue may affect any MCP client that launches mcp-proxy-for-aws locally with the same AWS CLI v2 aws login / SSO credential setup.

Related but distinct issue:

• tools/list returns empty array silently when AWS MCP Server throttles concurrent proxy initialization mcp-proxy-for-aws#287

That issue also involves AWS MCP tools not being available, but the reported cause appears to be tools/list returning an empty array under concurrent proxy initialization / throttling.

The issue described here is different: botocore raises NoRegionError during local credential refresh before AWS MCP tools become available.

Suggested documentation change:

Please clarify that --metadata AWS_REGION=... and the local AWS Region used by mcp-proxy-for-aws serve different purposes, and consider adding optional env examples for AWS_REGION / AWS_DEFAULT_REGION to the MCP client configuration examples.