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 with the setup process.

Set up the AWS MCP Server

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

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 authentication and connect

AWS MCP Server supports 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

Option A: OAuth (simple)

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.

Prerequisites

  1. Grant OAuth permissions to your IAM role or user by attaching the managed policy:

    aws iam attach-role-policy \
  --role-name MyRole \
  --policy-arn arn:aws:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy
Configure your MCP client

The following clients fully support OAuth with the default endpoint URL:

Claude Code CLI
claude mcp add aws-mcp https://aws-mcp.us-east-1.api.aws/mcp --transport http
Claude Code for Web

Add the URL https://aws-mcp.us-east-1.api.aws/mcp in your web client MCP settings.

Kiro CLI (2.11 or later)
kiro-cli mcp add --name aws-mcp --url https://aws-mcp.us-east-1.api.aws/mcp

The following clients support OAuth when you append ?oauth=initialize to the endpoint URL:

Claude Desktop

Add as a remote MCP server with URL: https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize

Cursor

Add as a remote MCP server with URL: https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize

Kiro IDE

Add as a remote MCP server with URL: https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize

Gemini CLI
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.

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 to authenticate requests with SigV4. With this option, you can switch between multiple profiles for cross-account workflows.

Prerequisites

  1. Install the AWS CLI (2.32.0 or later) by following Installing the AWS CLI.

  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"

For other credential methods (SSO, IAM access keys, cross-account roles), see Sign in with the AWS CLI.

Configure your MCP client

The endpoint Region determines which MCP server you connect to, while the AWS_REGION metadata parameter sets the default Region for AWS operations. Without AWS_REGION, operations default to us-east-1.

Kiro CLI or 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"
      ]
    }
  }
}
Cursor IDE or Claude Desktop
{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws==1.6.2",
        "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==1.6.2",
  "https://aws-mcp.us-east-1.api.aws/mcp",
  "--metadata", "AWS_REGION=us-west-2"
]
startup_timeout_sec = 60
Tip

To work with multiple AWS accounts in a single session, configure additional named profiles. See Multi-profile support for setup instructions. Multi-profile switching is only available with SigV4 authentication.

Step 3: Test your connection

  1. Start your MCP client (Kiro CLI, Cursor, Claude Desktop, or a similar client).

  2. Wait for the MCP server to initialize (this might take a few minutes on the 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. When this happens, your AI agent cannot use AWS MCP tools. 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. Short-lived session tokens (default 1 hour) typically expire 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, because 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. The SDK then automatically re-assumes 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 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.
400 error page after OAuth sign-in Your IAM principal does not have the required OAuth permissions (signin:AuthorizeOAuth2Access and signin:CreateOAuth2Token).

Attach the AWSMCPSignInOAuthAccessPolicy managed policy to your IAM role or user:

aws iam attach-role-policy \
  --role-name MyRole \
  --policy-arn arn:aws:iam::aws:policy/AWSMCPSignInOAuthAccessPolicy

For more information, see AWS managed policies for AWS MCP Server.
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 authentication and connect. 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.