# Setting up the AWS MCP Server
If you already have an AWS account, skip to [Set up the AWS MCP Server](#mcp-set-up-process). If you are new to AWS, [sign up for an AWS account](https://portal.aws.amazon.com/billing/signup) and then continue below.
## Set up the AWS MCP Server
To set up AWS MCP Server, use the steps in the following sections.
**Topics**
+ [Step 1: (If applicable) Remove conflicting MCP servers](#step-1-remove-conflicting-servers)
+ [Step 2: Configure AWS credentials](#step-2-configure-aws-credentials)
+ [Step 3: Configure your MCP client](#step-3-configure-mcp-client)
+ [Step 4: Test your connection](#step-4-test-connection)
### Step 1: (If applicable) Remove conflicting MCP servers
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.
**To remove existing AWS MCP servers:**
1. Open your MCP client configuration file (for example, `~/.kiro/settings/mcp.json` for Kiro).
1. Remove any entries for these servers:
+ `aws-api-mcp-server`
+ `aws-knowledge-mcp-server`
1. Save the configuration file.
1. Restart your MCP client to apply the changes.
### Step 2: Configure AWS credentials
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.
1. Run the following command and follow the prompts to sign in:
```
aws login
```
This automatically rotates your credentials every 15 minutes, keeping your session valid for up to 12 hours without manual intervention.
1. Verify your credentials are working:
```
aws sts get-caller-identity
```
1. Install uv (if not already installed):
**On 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"
```
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).
### Step 3: Configure your MCP client
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`
+ Europe (Frankfurt) – `eu-central-1`: `https://aws-mcp.eu-central-1.api.aws/mcp`
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.
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`.
Set your default AWS Region by adding the `--metadata` parameter with `AWS_REGION`. Without this setting, all AWS operations default to `us-east-1`.
**Region behavior:**
+ Without `--metadata` and `AWS_REGION`: Operations default to `us-east-1`
+ With `--metadata` and `AWS_REGION`: Operations use your specified Region
+ In queries: You can override by specifying a Region (example: "list my EC2 instances in eu-west-1")
------
#### [ Kiro CLI ]
```
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"timeout": 100000,
"transport": "stdio",
"args": [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
```
------
#### [ Kiro IDE ]
```
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"timeout": 100000,
"transport": "stdio",
"args": [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
```
------
#### [ Cursor IDE ]
```
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
```
------
#### [ Claude Desktop ]
```
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
```
------
#### [ Codex ]
```
[mcp_servers.aws_mcp]
command = "uvx"
args = [
"mcp-proxy-for-aws@latest",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
startup_timeout_sec = 60
```
------
### Step 4: Test your connection
1. Start your MCP client (Kiro CLI, Cursor, Claude Desktop, etc.).
1. Wait for the MCP server to initialize (this may take a few minutes on first connection).
1. Test the connection by asking your AI assistant:
*Example: What AWS Regions are available?*
1. Verify that tools are loaded by running (in Kiro CLI):
`/tools`
Or to see installed MCP servers:
`/mcp`
You should see tools like `aws___search_documentation` and `aws___retrieve_skill` listed. For more information about the tools, see [Understanding the MCP Server tools](https://docs.aws.amazon.com/aws-mcp/latest/userguide/understanding-mcp-server-tools.html).
## Troubleshooting authentication errors
Authentication errors can prevent the MCP server from initializing, which results in AWS MCP tools not being available to AI agents. If your AI agent is not using AWS MCP tools, an expired or missing credential is the most likely cause.
Use the following table to identify and resolve common authentication errors.
**Common authentication errors**
| Error | Cause | Resolution |
| --- | --- | --- |
| ExpiredTokenException: Your AWS session token has expired. | Your temporary AWS credentials have expired. This is the most common authentication error, typically caused by short-lived session tokens (default 1 hour) expiring during development. | Refresh your credentials based on your authentication method:[See the AWS documentation website for more details](http://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html)
After refreshing, restart your MCP client to re-initialize the server. |
| UnrecognizedClientException: The security token included in the request is not recognized. | Your credentials are invalid. This can happen when credentials have been revoked, are from a different AWS partition, are malformed, or belong to a deleted IAM user or role. | Verify your credentials are valid:[See the AWS documentation website for more details](http://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) |
| InvalidSignatureException: The request signature we calculated does not match the signature you provided. | The SigV4 signature does not match. Common causes include credentials scoped to the wrong service or Region, clock skew on your machine, or a request body that was modified after signing. | Try the following steps:[See the AWS documentation website for more details](http://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) |
| No AWS credentials found. | AWS credentials are not configured on your machine, or the credential provider chain cannot locate them. | Configure your credentials by following [Step 2: Configure AWS credentials](#step-2-configure-aws-credentials). We recommend using `aws login` for the simplest setup with automatic credential renewal. |
**Note**
To learn more about how AWS IAM authorizes AWS MCP Server requests, including how to use IAM condition context keys to restrict agent actions, see [Understanding IAM for managed AWS MCP servers](https://aws.amazon.com/blogs/security/understanding-iam-for-managed-aws-mcp-servers/) on the AWS Security Blog.