View a markdown version of this page

Setting up the AWS MCP Server - Agent Toolkit for AWS
Set up the AWS MCP ServerTroubleshooting authentication errors

Setting up the AWS MCP Server

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 and then continue below.

Set up the AWS MCP Server

To set up AWS MCP Server, use the steps in the following sections.

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

  2. Remove any entries for these servers:

    • aws-api-mcp-server

    • aws-knowledge-mcp-server

  3. Save the configuration file.

  4. 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. You need version 2.32.0 or later.

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

  3. Verify your credentials are working:

    aws sts get-caller-identity

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

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 to translate MCP requests into AWS requests authenticated with SigV4. 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.).

  2. Wait for the MCP server to initialize (this may take a few minutes on first connection).

  3. Test the connection by asking your AI assistant:

    Example: What AWS Regions are available?

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

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:

  • aws login users: Run aws login again to start a new session. Consider switching to this method if you experience frequent expiry, as it auto-rotates credentials every 15 minutes.

  • SSO users: Run aws sso login --profile your-profile-name to refresh your SSO session.

  • Assume-role users: Refresh the source profile credentials, then the SDK will automatically re-assume the role.

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:

  1. Run aws sts get-caller-identity to check if your credentials are recognized.

  2. If the command fails, reconfigure your credentials using aws login or aws configure sso.

  3. Ensure you are using credentials for the correct AWS partition (for example, aws vs. aws-cn).
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:

  1. Verify your system clock is accurate. Run date and compare with an authoritative time source. SigV4 requires your clock to be within 5 minutes of AWS servers.

  2. Ensure your credentials are configured for the correct AWS Region and service.

  3. Reconfigure your credentials and restart your MCP client.
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. 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 on the AWS Security Blog.