AWS agent-toolkit documentation change
Summary
Restructured prerequisites section, simplified AWS credential configuration, removed IAM authorization details, and added references to enhanced security controls.
Security assessment
The changes promote enhanced security by recommending credential methods with automatic rotation and reference IAM condition keys for access control. However, there's no evidence of addressing a specific security vulnerability. The removal of detailed IAM policy examples is offset by added links to security documentation.
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 84b72b7e1..7cdec126e 100644 --- a//agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md +++ b//agent-toolkit/latest/userguide/getting-started-aws-mcp-server.md @@ -7 +7 @@ -PrerequisitesSet up the AWS MCP ServerTroubleshooting authentication errors +Set up the AWS MCP ServerTroubleshooting authentication errors @@ -11,87 +11 @@ PrerequisitesSet up the AWS MCP ServerTroubleshooting authentication errors -This section outlines how you can set up your AWS MCP Server. - -###### Topics - - * Prerequisites - - * Set up the AWS MCP Server - - * Troubleshooting authentication errors - - - - -## Prerequisites - -Before you begin, you must ensure that you have set up an AWS account. - -#### Sign up for an AWS account - -If you do not have an AWS account, complete the following steps to create one. - -###### To sign up for an AWS account - - 1. Open [https://portal.aws.amazon.com/billing/signup](https://portal.aws.amazon.com/billing/signup). - - 2. Follow the online instructions. - -Part of the sign-up procedure involves receiving a phone call or text message and entering a verification code on the phone keypad. - -When you sign up for an AWS account, an _AWS account root user_ is created. The root user has access to all AWS services and resources in the account. As a security best practice, assign administrative access to a user, and use only the root user to perform [tasks that require root user access](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_root-user.html#root-user-tasks). - - - - -AWS sends you a confirmation email after the sign-up process is complete. At any time, you can view your current account activity and manage your account by going to [https://aws.amazon.com/](https://aws.amazon.com/) and choosing **My Account**. - -#### Create a user with administrative access - -After you sign up for an AWS account, secure your AWS account root user, enable AWS IAM Identity Center, and create an administrative user so that you don't use the root user for everyday tasks. - -###### Secure your AWS account root user - - 1. Sign in to the [AWS Management Console](https://console.aws.amazon.com/) as the account owner by choosing **Root user** and entering your AWS account email address. On the next page, enter your password. - -For help signing in by using root user, see [Signing in as the root user](https://docs.aws.amazon.com/signin/latest/userguide/console-sign-in-tutorials.html#introduction-to-root-user-sign-in-tutorial) in the _AWS Sign-In User Guide_. - - 2. Turn on multi-factor authentication (MFA) for your root user. - -For instructions, see [Enable a virtual MFA device for your AWS account root user (console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/enable-virt-mfa-for-root.html) in the _IAM User Guide_. - - - - -###### Create a user with administrative access - - 1. Enable IAM Identity Center. - -For instructions, see [Enabling AWS IAM Identity Center](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-set-up-for-idc.html) in the _AWS IAM Identity Center User Guide_. - - 2. In IAM Identity Center, grant administrative access to a user. - -For a tutorial about using the IAM Identity Center directory as your identity source, see [ Configure user access with the default IAM Identity Center directory](https://docs.aws.amazon.com//singlesignon/latest/userguide/quick-start-default-idc.html) in the _AWS IAM Identity Center User Guide_. - - - - -###### Sign in as the user with administrative access - - * To sign in with your IAM Identity Center user, use the sign-in URL that was sent to your email address when you created the IAM Identity Center user. - -For help signing in using an IAM Identity Center user, see [Signing in to the AWS access portal](https://docs.aws.amazon.com/signin/latest/userguide/iam-id-center-sign-in-tutorial.html) in the _AWS Sign-In User Guide_. - - - - -###### Assign access to additional users - - 1. In IAM Identity Center, create a permission set that follows the best practice of applying least-privilege permissions. - -For instructions, see [ Create a permission set](https://docs.aws.amazon.com//singlesignon/latest/userguide/get-started-create-a-permission-set.html) in the _AWS IAM Identity Center User Guide_. - - 2. Assign users to a group, and then assign single sign-on access to the group. - -For instructions, see [ Add groups](https://docs.aws.amazon.com//singlesignon/latest/userguide/addgroups.html) in the _AWS IAM Identity Center User Guide_. - - - +If you already have an AWS account, skip to Set up the AWS MCP Server. If you are new to AWS, [sign up for an AWS account](https://portal.aws.amazon.com/billing/signup) and then continue below. @@ -111,3 +25 @@ To set up AWS MCP Server, use the steps in the following sections. - * Step 4: Understand IAM authorization - - * Step 5: Test your connection + * Step 4: Test your connection @@ -120 +32,3 @@ To set up AWS MCP Server, use the steps in the following sections. -If you currently have AWS API MCP Server or AWS Knowledge MCP Server installed, we recommend removing them before setting up the AWS MCP Server to avoid tool conflicts that can confuse AI agents and reduce performance. +If you are currently using the AWS API MCP Server or AWS Knowledge MCP Server, we recommend switching to the AWS MCP Server. The AWS MCP Server is a managed remote MCP server that reduces setup and maintenance effort and offers enhanced security controls through IAM condition keys. + +To switch, remove the older servers from your MCP client configuration to avoid tool conflicts that can confuse AI agents and reduce performance. @@ -124 +38 @@ If you currently have AWS API MCP Server or AWS Knowledge MCP Server installed, - 1. Open your MCP client configuration file. + 1. Open your MCP client configuration file (for example, `~/.kiro/settings/mcp.json` for Kiro). @@ -141,5 +55 @@ If you currently have AWS API MCP Server or AWS Knowledge MCP Server installed, -Before connecting to AWS MCP Server, you need to configure AWS credentials on your local machine. The server uses these credentials to authenticate your requests. - -You can use the SigV4 via Proxy to authenticate the AWS MCP Server. SigV4 via Proxy uses your available AWS credentials and requires the [MCP Proxy for AWS](https://github.com/aws/mcp-proxy-for-aws). The MCP Proxy for AWS handles SigV4 signing and credential management between your MCP client and the AWS MCP Server. No separate installation is required — the `uvx mcp-proxy-for-aws@latest` command in your MCP client configuration automatically downloads and runs the latest version of the proxy each time your MCP client starts. For the full list of configuration options, see the [MCP Proxy for AWS repository](https://github.com/aws/mcp-proxy-for-aws) on GitHub. - -For detailed information about configuring AWS credentials, see [Sign in with the aws login command](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) in the _AWS CLI User Guide_. + 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. @@ -147,15 +57 @@ For detailed information about configuring AWS credentials, see [Sign in with th -###### Important - -AWS MCP Server requires valid AWS credentials for the duration of your development session. We strongly recommend using a credential method that supports automatic renewal, such as `aws login` or `aws configure sso`. Expired credentials would prevent the MCP server from being initialized, making all AWS tools unavailable until you restart your MCP client with valid AWS credentials. - -###### Note - -If your authentication step worked previously but you have encountered an authentication error, you might need to refresh your credentials and try again. See Troubleshooting authentication errors for common authentication errors and how to resolve them. - - 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). - - 2. Configure your AWS credentials using one of these methods: - -###### For users with AWS Management Console credentials (Recommended) - -From the AWS CLI, run the following command: + 2. Run the following command and follow the prompts to sign in: @@ -165,13 +61 @@ From the AWS CLI, run the following command: -This is the recommended method because the AWS SDK automatically rotates your credentials every 15 minutes within the session, eliminating credential expiry during normal use. Your session remains valid for up to 12 hours without any manual intervention. - -###### Note - -AWS Management Console credentials means that you have a username and password that allows you to sign in to the console. To use this method, you need the AWS CLI version `2.32.0` or later. - -###### For SSO users (Recommended) - - aws configure sso - -Follow the prompts to set up your SSO configuration. SSO credentials support automatic renewal through cached refresh tokens. The SDK silently obtains new access tokens and role session credentials without requiring you to re-authenticate. - -###### Tip +This automatically rotates your credentials every 15 minutes, keeping your session valid for up to 12 hours without manual intervention. @@ -179,24 +63 @@ Follow the prompts to set up your SSO configuration. SSO credentials support aut -For administrators: The default SSO session duration is 1 hour. You can extend this up to 12 hours in your IAM Identity Center settings to reduce the frequency of re-authentication for your team. - -###### For IAM users - - aws configure - -Enter your Access Key ID, Secret Access Key, default region, and output format. - -###### Warning - -Static IAM access keys do not support automatic credential renewal and are not recommended for use with AWS MCP Server. If you must use IAM access keys, be aware that AWS recommends rotating them every 90 days. Where possible, use `aws login` or `aws configure sso` instead. - -###### For cross-account access (assume-role) - -If you need to access AWS resources in a different account, you can configure an assume-role profile in your `~/.aws/config` file. The AWS SDK handles credential refresh transparently for this method. - - [profile my-role] - role_arn = arn:aws:iam::123456789012:role/MyRole - source_profile = default - region = us-east-1 - -Then set the `AWS_PROFILE` environment variable or pass the profile name in your MCP client configuration. - - 3. Test your configuration: + 3. Verify your credentials are working: @@ -206 +67 @@ Then set the `AWS_PROFILE` environment variable or pass the profile name in your - 4. Install uv (if not already installed) + 4. Install uv (if not already installed): @@ -218,0 +80,2 @@ Then set the `AWS_PROFILE` environment variable or pass the profile name in your +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). + @@ -230 +93 @@ AWS MCP Server is available in the following AWS Regions: -Replace the endpoint URL in the configuration examples below with the endpoint for your preferred Region. When configuring the SigV4 proxy, append `/mcp` to the base endpoint URL as shown in the following examples. +The configuration examples below 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. @@ -236,4 +98,0 @@ Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGIO -###### Note - -Replace `us-west-2` with your preferred default AWS Region. - @@ -336,50 +195 @@ Codex -### Step 4: Understand IAM authorization - -AWS MCP Server does not require separate IAM permissions to invoke the MCP server. Authorization occurs at the AWS service level using your existing IAM roles and policies. When an AI agent calls the AWS MCP Server, the server authenticates your request and forwards it to the appropriate AWS service. The AWS service then authorizes the request using your existing IAM permissions, just as it would for any direct API call. - -Two global condition context keys are automatically added to all requests made through the AWS MCP Server: - - * `aws:ViaAWSMCPService` – Set to `true` for any request that passes through an AWS managed MCP server. - - * `aws:CalledViaAWSMCP` – Contains the service principal of the specific AWS managed MCP server (for example, `aws-mcp.amazonaws.com`). - -