Set up the AWS MCP Server Troubleshooting 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

Topics

Step 1: (If applicable) Remove conflicting MCP servers
Step 2: Configure authentication and connect
Step 3: Test your 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:

Open your MCP client configuration file (for example, ~/.kiro/settings/mcp.json for Kiro).
Remove any entries for these servers:
- aws-api-mcp-server
- aws-knowledge-mcp-server
Save the configuration file.
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

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

Devin Desktop

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

Devin CLI


devin mcp add aws-mcp 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

Install the AWS CLI (2.32.0 or later) by following Installing the AWS CLI.
Sign in and configure credentials:
```
aws login
```
The command auto-rotates credentials every 15 minutes for sessions up to 12 hours.
Verify your credentials:
```
aws sts get-caller-identity
```

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-cli@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

Cursor IDE, Claude Desktop, or Devin Desktop


{
  "mcpServers": {
    "aws-mcp":