AWS agent-toolkit documentation change
Summary
Added documentation for two authentication methods (OAuth and SigV4) with a decision guide, reorganized setup steps, expanded client configuration examples, and added new authentication error resolutions.
Security assessment
The changes focus on documenting authentication methods (OAuth and SigV4) which are security features, but there's no evidence of addressing a specific vulnerability. The additions include IAM policy requirements, token management, and error handling for authentication failures, which are security-related documentation improvements.
Diff
diff --git a/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md b/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md index 9415f3a57..7d07d7b85 100644 --- a//agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md +++ b//agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md @@ -15 +15,22 @@ If you already have an AWS account, skip to Set up the AWS MCP Server. If you ar -To set up AWS MCP Server, use the steps in the following sections. +AWS MCP Server supports two authentication methods. The following describes both options, followed by a decision guide to help you choose. + + * **Option A: OAuth (simple)** — Connect to AWS MCP Server using OAuth. If you are a human user, you authenticate in your browser. If you are running an automated agent, it authenticates by requesting a token. Works for web clients (such as Claude.ai and ChatGPT.com) and most IDE, terminal, or desktop-based clients. Use this option if you are new to AWS and use a single account, or if you interact through web clients. + + * **Option B: SigV4 (advanced)** — Authenticate using the AWS CLI, then use the MCP Proxy for AWS to sign requests with SigV4 credentials. Use this option if you use terminal or IDE-based coding agents (such as Claude Code, Kiro, and Codex), or if you need to switch between AWS accounts frequently. + + + + +### Choosing an authentication method + +Use the following questions to determine which authentication method fits your use case: + +Authentication method decision guide Question | Use +---|--- +Do you want to get started without installing `uvx`, installing the AWS CLI, or configuring local credentials? | OAuth +Does your client only support remote MCP servers (no local process)? | OAuth +Does your agent need access across multiple AWS accounts in the same session? | SigV4 +Do you need read-only mode (hide write-capable tools from the agent entirely)? | SigV4 +Does your organization restrict the `signin:AuthorizeOAuth2Access` and `signin:CreateOAuth2Token` permissions needed for browser-based OAuth login? | SigV4 +Do you need to set a default AWS Region for your agentic session (without specifying it in every query)? | SigV4 +Does your client not support the OAuth flow but can run a local MCP proxy? | SigV4 @@ -21,3 +42 @@ To set up AWS MCP Server, use the steps in the following sections. - * Step 2: Configure AWS credentials - - * Step 3: Configure your MCP client + * Step 2: Configure authentication and connect @@ -25 +44 @@ To set up AWS MCP Server, use the steps in the following sections. - * Step 4: Test your connection + * Step 3: Test your connection @@ -53 +72 @@ To switch, remove the older servers from your MCP client configuration to avoid -### Step 2: Configure AWS credentials +### Step 2: Configure authentication and connect @@ -55 +74 @@ To switch, remove the older servers from your MCP client configuration to avoid - 1. Install the AWS CLI by following the instructions at [ Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). You need version `2.32.0` or later. +AWS MCP Server supports the following AWS Regions: @@ -57 +76 @@ To switch, remove the older servers from your MCP client configuration to avoid - 2. Run the following command and follow the prompts to sign in: + * US East (N. Virginia) – `us-east-1`: `https://aws-mcp.us-east-1.api.aws/mcp` @@ -59 +78 @@ To switch, remove the older servers from your MCP client configuration to avoid - aws login + * Europe (Frankfurt) – `eu-central-1`: `https://aws-mcp.eu-central-1.api.aws/mcp` @@ -61 +79,0 @@ To switch, remove the older servers from your MCP client configuration to avoid -This automatically rotates your credentials every 15 minutes, keeping your session valid for up to 12 hours without manual intervention. @@ -63 +80,0 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi - 3. Verify your credentials are working: @@ -65 +81,0 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi - aws sts get-caller-identity @@ -67 +83 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi - 4. Install uv (if not already installed): +Option A: OAuth (simple) @@ -69 +84,0 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi -###### On macOS and Linux @@ -71 +86 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi - curl -LsSf https://astral.sh/uv/install.sh | sh +With OAuth, you can connect directly to AWS MCP Server without installing or running local proxy software. Your MCP client handles the OAuth flow automatically. @@ -73 +88 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi -###### Windows +###### Prerequisites @@ -75 +90 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi - powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + 1. Grant OAuth permissions to your IAM role or user by attaching the managed policy: @@ -76,0 +92,3 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi + aws iam attach-role-policy \ + --role-name MyRole \ + --policy-arn arn:aws:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy @@ -80 +97,0 @@ This automatically rotates your credentials every 15 minutes, keeping your sessi -For other credential methods (SSO, IAM access keys, cross-account roles), see [Sign in with the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html). @@ -82 +99 @@ For other credential methods (SSO, IAM access keys, cross-account roles), see [S -###### Tip +###### Configure your MCP client @@ -84 +101 @@ For other credential methods (SSO, IAM access keys, cross-account roles), see [S -To work with multiple AWS accounts in a single session, configure additional named profiles. See [Multi-profile support](./multi-account-access.html) for setup instructions. +The following clients fully support OAuth with the default endpoint URL: @@ -86 +103 @@ To work with multiple AWS accounts in a single session, configure additional nam -### Step 3: Configure your MCP client +Claude Code CLI @@ -88 +104,0 @@ To work with multiple AWS accounts in a single session, configure additional nam -AWS MCP Server is available in the following AWS Regions: @@ -90 +105,0 @@ AWS MCP Server is available in the following AWS Regions: - * US East (N. Virginia) – `us-east-1`: `https://aws-mcp.us-east-1.api.aws/mcp` @@ -92 +107 @@ AWS MCP Server is available in the following AWS Regions: - * Europe (Frankfurt) – `eu-central-1`: `https://aws-mcp.eu-central-1.api.aws/mcp` + claude mcp add aws-mcp https://aws-mcp.us-east-1.api.aws/mcp --transport http @@ -93,0 +109 @@ AWS MCP Server is available in the following AWS Regions: +Claude Code for Web @@ -95,0 +112 @@ AWS MCP Server is available in the following AWS Regions: +Add the URL `https://aws-mcp.us-east-1.api.aws/mcp` in your web client MCP settings. @@ -97 +114 @@ AWS MCP Server is available in the following AWS Regions: -The following configuration examples use the [MCP Proxy for AWS](https://github.com/aws/mcp-proxy-for-aws) to translate MCP requests into AWS requests authenticated with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html). Replace the endpoint URL with the endpoint for your preferred Region. +Kiro CLI (2.11 or later) @@ -99 +115,0 @@ The following configuration examples use the [MCP Proxy for AWS](https://github. -The endpoint Region determines which MCP server you connect to, while the `AWS_REGION` metadata parameter sets the default Region for the AWS operations the server performs on your behalf. These can be different — for example, you can connect to the `us-east-1` endpoint while operating on resources in `us-west-2`. @@ -101 +116,0 @@ The endpoint Region determines which MCP server you connect to, while the `AWS_R -Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGION`. Without this setting, all AWS operations default to `us-east-1`. @@ -103 +118 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO -**Region behavior:** + kiro-cli mcp add --name aws-mcp --url https://aws-mcp.us-east-1.api.aws/mcp @@ -105 +120 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO - * Without `--metadata` and `AWS_REGION`: Operations default to `us-east-1` +The following clients support OAuth when you append `?oauth=initialize` to the endpoint URL: @@ -107 +122 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO - * With `--metadata` and `AWS_REGION`: Operations use your specified Region +Claude Desktop @@ -109 +123,0 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO - * In queries: You can override by specifying a Region (example: "list my EC2 instances in eu-west-1") @@ -110,0 +125 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO +Add as a remote MCP server with URL: `https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize` @@ -111,0 +127 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO +Cursor @@ -114 +130 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO -Kiro CLI +Add as a remote MCP server with URL: `https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize` @@ -115,0 +132 @@ Kiro CLI +Kiro IDE @@ -118,14 +135 @@ Kiro CLI - { - "mcpServers": { - "aws-mcp": { - "command": "uvx", - "timeout": 100000, - "transport": "stdio", - "args": [ - "mcp-proxy-for-aws==1.6.2", - "https://aws-mcp.us-east-1.api.aws/mcp", - "--metadata", "AWS_REGION=us-west-2" - ] - } - } - } +Add as a remote MCP server with URL: `https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize` @@ -133 +137 @@ Kiro CLI -Kiro IDE +Gemini CLI @@ -137,14 +141,24 @@ Kiro IDE - { - "mcpServers": { - "aws-mcp": { - "command": "uvx", - "timeout": 100000, - "transport": "stdio", - "args": [ - "mcp-proxy-for-aws==1.6.2", - "https://aws-mcp.us-east-1.api.aws/mcp", - "--metadata", "AWS_REGION=us-west-2" - ] - } - } - } + gemini mcp add aws-mcp https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize --transport http + +Codex CLI and Codex Desktop + + + + codex mcp add aws-mcp --url https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize + +When you first invoke a tool, your MCP client opens a browser window to AWS Sign-in. Sign in with your existing credentials and authorize access. After you grant consent, access tokens remain valid for 1 hour. AWS Sign-in automatically refreshes them for up to 12 hours. + +If your client is not listed above, use the default endpoint URL (`https://aws-mcp.us-east-1.api.aws/mcp`). Without `?oauth=initialize`, the client relies on MCP OAuth discovery to start the authorization flow automatically. If tool calls fail due to credential errors, append `?oauth=initialize` to the URL to instruct the server to explicitly trigger the OAuth flow. + +For detailed OAuth setup, governance options, and token management, see [OAuth 2.1 authentication for AWS MCP Server](./oauth-authentication.html). + +###### Note + +Multi-profile switching for cross-account workflows is not supported with OAuth. If you need to work with multiple AWS accounts in a single session, use the SigV4 authentication option instead. + +Option B: SigV4 (advanced) + + +Use the [MCP Proxy for AWS](https://github.com/aws/mcp-proxy-for-aws) to authenticate requests with [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html). With this option, you can switch between multiple profiles for cross-account workflows. + +###### Prerequisites @@ -152 +166,30 @@ Kiro IDE -Cursor IDE + 1. Install the AWS CLI (`2.32.0` or later) by following [ Installing the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + + 2. Sign in and configure credentials: + + aws login + +The command auto-rotates credentials every 15 minutes for sessions up to 12 hours. + + 3. Verify your credentials: + + aws sts get-caller-identity + + 4. Install uv (if not already installed): + + # macOS and Linux + curl -LsSf https://astral.sh/uv/install.sh | sh + + # Windows + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"