How to set up the AWS MCP Server

The AWS MCP Server is a managed remote endpoint in the Agent Toolkit for AWS. Install the aws-core plugin, or add the endpoint yourself and authenticate with OAuth or SigV4. Searching documentation and discovering skills does not require local AWS credentials. Tools that execute AWS API calls and run scripts do. If you do not have an AWS account, create one before setup.

Choose OAuth or SigV4

OAuth connects without local proxy software. A person authenticates in the browser. An automated agent requests a token. Use it if you are new to AWS and use a single account, if you interact through web clients such as Claude.ai and ChatGPT.com, if you want to start without installing uvx, the AWS CLI, or local credentials, or if the client only supports remote MCP servers.

SigV4 is the advanced option. Authenticate with the AWS CLI, then use the MCP Proxy for AWS to sign requests. Use it for terminal or IDE-based coding agents such as Claude Code, Kiro, and Codex, or when you switch AWS accounts frequently. The decision table also selects SigV4 for:

Access across multiple AWS accounts in the same session.
Read-only mode that hides write-capable tools from the agent. The table names that need. The setup steps do not include the control.
Organizations that restrict signin:AuthorizeOAuth2Access and signin:CreateOAuth2Token.
A default AWS Region for the session, without specifying it in every query.
A client that does not support the OAuth flow but can run a local MCP proxy.

Multi-profile switching is not supported with OAuth. It is only available with SigV4.

Remove conflicting MCP servers

If you still use the AWS API MCP Server or the AWS Knowledge MCP Server, switch. 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. Remove the older entries so tool conflicts do not confuse the agent or reduce performance.

Open the MCP client configuration. For Kiro, the example file is ~/.kiro/settings/mcp.json. Remove aws-api-mcp-server and aws-knowledge-mcp-server, save, and restart the client.

Install the aws-core plugin

The fastest documented start is the plugin. It bundles the AWS MCP Server configuration and a curated set of agent skills. uv is required for the MCP proxy. IAM credentials on the machine are optional: required for AWS API calls and scripts, not for searching documentation or discovering skills.

In Claude Code:

/plugin install aws-core@claude-plugins-official
/reload-plugins

For Codex, run this in a terminal:

codex plugin marketplace add aws/agent-toolkit-for-aws

Launch Codex and run /plugins to browse and install the aws-core plugin.

With AWS CLI version 2.35.0 or later, this wizard detects installed agents, including Kiro, Cursor, and Claude Code, installs default AWS skills, and configures the connection:

aws configure agent-toolkit

After aws-core, install aws-agents, aws-data-analytics, or aws-agents-for-devsecops the same way. The quick start does not print separate commands for those three.

Kiro's quick start path is not that plugin command. Add the proxy configuration from the setup page, then install skills:

npx skills add aws/agent-toolkit-for-aws/skills

Other agents that already speak MCP use the same skills command after you configure the server directly. Copy the recommended rules file from the Agent Toolkit for AWS repository into CLAUDE.md for Claude Code or AGENTS.md for Codex. The quick start says that without it, the agent might apply AWS best practices less consistently.

Connect with OAuth

Attach AWSMCPSignInOAuthAccessPolicy to the IAM role or user before browser login. The only command printed is the role form. MyRole is the guide's placeholder.

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

Examples use the us-east-1 endpoint. Substitute another supported Region in the host if you need a different MCP server.

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

Codex CLI and Codex Desktop:

codex mcp add aws-mcp --url https://aws-mcp.us-east-1.api.aws/mcp?oauth=initialize

Claude Desktop, Cursor, and Kiro IDE use that same URL, query included, as a remote MCP server. If your client is not listed, start with https://aws-mcp.us-east-1.api.aws/mcp and rely on MCP OAuth discovery. If tool calls fail due to credential errors, append ?oauth=initialize.

The first tool call opens AWS Sign-in. Sign in and authorize access. Access tokens remain valid for 1 hour. AWS Sign-in refreshes them for up to 12 hours.

Connect with SigV4

Install the AWS CLI at version 2.32.0 or later. That floor is for this path, not the 2.35.0 wizard. Sign in, then verify the caller:

aws login

aws sts get-caller-identity

aws login auto-rotates credentials every 15 minutes for sessions up to 12 hours. Install uv if it is not already present:

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

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. The commands below call the us-east-1 MCP endpoint and set metadata to 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

Copy the JSON block for your client from the setup page. The Kiro sample and the desktop sample are not identical. SSO, IAM access keys, and cross-account roles are left to the AWS CLI sign-in documentation that page points to. Extra named profiles, for several accounts in one session, are only on the SigV4 multi-profile topic.

Supported endpoint Regions

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

Test the connection

Start the MCP client and wait for initialization. The first connection might take a few minutes. Ask what AWS Regions are available. A list of Regions means the connection is working.

In Kiro CLI, /tools lists tools and /mcp lists installed MCP servers. You should see tools like aws___search_documentation and aws___retrieve_skill.

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

ExpiredTokenException: run aws login again, or aws sso login --profile your-profile-name for SSO. Assume-role users refresh the source profile so the SDK can re-assume the role. Restart the client.
UnrecognizedClientException: run aws sts get-caller-identity. If it fails, use aws login or aws configure sso, and confirm the partition. The guide's example is aws versus aws-cn.
InvalidSignatureException: run date and compare it with an authoritative clock. SigV4 requires the clock to be within 5 minutes of AWS servers. Reconfigure credentials and restart the client.
A 400 error page after OAuth sign-in: the principal lacks signin:AuthorizeOAuth2Access and signin:CreateOAuth2Token. Attach AWSMCPSignInOAuthAccessPolicy.
No AWS credentials found: the provider chain cannot locate credentials. The guide recommends aws login for automatic renewal.

Next step

Start a new conversation and ask what AWS Regions are available. If that returns a list, try a quick-start task: which AWS services to use for a serverless API, or help with a failed CloudFormation deployment. The agent discovers skills from the request. You do not name a skill first. For several accounts in one session, stay on SigV4 and follow the multi-profile topic linked from the setup guide.