How to set up the AWS MCP Server

The Agent Toolkit user guide sets up the AWS MCP Server in three steps: remove older AWS MCP servers if you still have them, connect with OAuth or SigV4, then test. It is a managed remote MCP server. Samples use the US East (N. Virginia) endpoint. For another supported Region, substitute that Region in the endpoint URL.

If you already have an AWS account, start at the setup steps. If you are new to AWS, sign up for an account first. Account creation is not documented on this page.

Choose OAuth or SigV4

Option A, OAuth, connects without local proxy software. A human authenticates in the browser. An automated agent authenticates by requesting a token. It works for web clients such as Claude.ai and ChatGPT.com, and for most IDE, terminal, and desktop clients. Use it if you are new to AWS and use a single account, or if you interact through web clients.

Option B, SigV4, authenticates with the AWS CLI, then uses the MCP Proxy for AWS to sign requests. Use it with terminal or IDE agents such as Claude Code, Kiro, and Codex, or when you switch AWS accounts often.

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

Multi-profile switching in one session is not supported with OAuth. Read-only mode is a SigV4 reason on this page, but the read-only configuration is not shown here.

Remove the older servers

If you use the AWS API MCP Server or the AWS Knowledge MCP Server, switch. AWS MCP Server reduces setup and maintenance and offers enhanced security controls through IAM condition keys. Older entries can create tool conflicts.

Open the MCP client configuration. The Kiro example is ~/.kiro/settings/mcp.json.
Remove entries for aws-api-mcp-server and aws-knowledge-mcp-server.
Save the file.
Restart the MCP client.

Use a supported endpoint

US East (N. Virginia), us-east-1: https://aws-mcp.us-east-1.api.aws/mcp
US West (Oregon), us-west-2: https://aws-mcp.us-west-2.api.aws/mcp
Asia Pacific (Singapore), ap-southeast-1: https://aws-mcp.ap-southeast-1.api.aws/mcp
Asia Pacific (Sydney), ap-southeast-2: https://aws-mcp.ap-southeast-2.api.aws/mcp
Asia Pacific (Tokyo), ap-northeast-1: https://aws-mcp.ap-northeast-1.api.aws/mcp
Europe (Frankfurt), eu-central-1: https://aws-mcp.eu-central-1.api.aws/mcp
Europe (Ireland), eu-west-1: https://aws-mcp.eu-west-1.api.aws/mcp
Europe (London), eu-west-2: https://aws-mcp.eu-west-2.api.aws/mcp

Samples use us-east-1. Substitute the Region in the URL, for example https://aws-mcp.eu-west-1.api.aws/mcp.

With SigV4, the endpoint Region selects the MCP server. AWS_REGION metadata sets the default Region for AWS operations. Without it, operations default to us-east-1. Samples set that metadata to us-west-2 while calling the us-east-1 endpoint.

Connect with OAuth

Attach the managed policy AWSMCPSignInOAuthAccessPolicy to the IAM role or user before you connect. The setup page shows that step with the placeholder role name MyRole. Use the command printed there.

These 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 https://aws-mcp.us-east-1.api.aws/mcp in the 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 a remote MCP server with URL https://aws-mcp.us-east-1.api.aws/mcp.

Devin CLI:

devin mcp add -s user aws-mcp https://aws-mcp.us-east-1.api.aws/mcp

Append ?oauth=initialize for these clients.

Claude Desktop, Cursor, and Kiro IDE: https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize

Visual Studio Code uses a servers key, not mcpServers. Add this to .vscode/mcp.json, or run MCP: Open User Configuration from the Command Palette:

{
  "servers": {
    "aws-mcp": {
      "type": "http",
      "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

GitHub Copilot CLI: use ~/.copilot/mcp-config.json for all projects, or .github/mcp.json or .mcp.json at the repository root for one project. Run /mcp in a session to confirm the server is listed.

{
  "mcpServers": {
    "aws-mcp": {
      "type": "http",
      "url": "https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize",
      "tools": ["*"]
    }
  }
}

If your client is not listed, use https://aws-mcp.us-east-1.api.aws/mcp. Without ?oauth=initialize, it relies on MCP OAuth discovery. If tool calls fail due to credential errors, append ?oauth=initialize.

The first tool call opens AWS Sign-in in a browser. After consent, access tokens remain valid for 1 hour. AWS Sign-in refreshes them for up to 12 hours.

Connect with SigV4

Install the AWS CLI, version 2.32.0 or later. Sign in, then verify:

aws login

aws sts get-caller-identity

aws login auto-rotates credentials every 15 minutes for sessions up to 12 hours. Install uv if needed:

# 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"

SSO, IAM access keys, and cross-account roles are not spelled out here. The page points to AWS CLI sign-in documentation. The JSON samples below keep the line-continuation backslashes printed in the guide.

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": {
      "command": "uvx",
      "args": [\
        "mcp-proxy-for-aws-cli@latest",\
        "https://aws-mcp.us-east-1.api.aws/mcp",\
        "--metadata", "AWS_REGION=us-west-2"\
      ]
    }
  }
}

Visual Studio Code uses servers in .vscode/mcp.json. You can also run MCP: Add Server and choose the stdio type:

{
  "servers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [\
        "mcp-proxy-for-aws-cli@latest",\
        "https://aws-mcp.us-east-1.api.aws/mcp",\
        "--metadata", "AWS_REGION=us-west-2"\
      ]
    }
  }
}

Claude Code CLI:

claude mcp add-json aws-mcp '{"type":"stdio","command":"uvx","args":["mcp-proxy-for-aws-cli@latest","https://aws-mcp.us-east-1.api.aws/mcp","--metadata","AWS_REGION=us-west-2"],"env":{}}'

Codex CLI:

codex mcp add aws-mcp uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --metadata AWS_REGION=us-west-2

Devin CLI:

devin mcp add -s user aws-mcp -- uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --metadata AWS_REGION=us-west-2

GitHub Copilot CLI uses "type": "local" in ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "aws-mcp": {
      "type": "local",
      "command": "uvx",
      "args": [\
        "mcp-proxy-for-aws-cli@latest",\
        "https://aws-mcp.us-east-1.api.aws/mcp",\
        "--metadata", "AWS_REGION=us-west-2"\
      ],
      "tools": ["*"]
    }
  }
}

Named profiles for several accounts in one session are on the Multi-profile support topic, and only with SigV4.

Test the connection

Start the client (Kiro CLI, Cursor, Claude Desktop, or similar).
Wait for initialization. The first connection might take a few minutes.
Ask: What AWS Regions are available?
In Kiro CLI, run /tools or /mcp.

You should see aws___search_documentation and aws___retrieve_skill.

If authentication fails

If the agent is not using AWS MCP tools, an expired or missing credential is the most likely cause.

ExpiredTokenException: run aws login again. SSO users run aws sso login --profile your-profile-name. Assume-role users refresh the source profile; the SDK re-assumes the role. Restart the client. Short-lived tokens default to 1 hour.
UnrecognizedClientException: run aws sts get-caller-identity. If it fails, reconfigure with aws login or aws configure sso, and use the correct partition (aws versus aws-cn).
InvalidSignatureException: run date. SigV4 requires the clock within 5 minutes of AWS servers. Then reconfigure and restart.
A 400 page after OAuth sign-in means the principal lacks signin:AuthorizeOAuth2Access and signin:CreateOAuth2Token. Attach AWSMCPSignInOAuthAccessPolicy using the command on the setup page.
No AWS credentials found: configure credentials. The guide recommends aws login.

What to do next

Remove aws-api-mcp-server and aws-knowledge-mcp-server, restart the client, and connect with one method. Ask what AWS Regions are available, and confirm aws___search_documentation and aws___retrieve_skill are listed. For several accounts in one session, stay on SigV4 and continue with Multi-profile support in the same user guide.

Sources

Setting up the AWS MCP Server