--- title: How to set up the AWS MCP Server description: "Connect the AWS MCP Server with OAuth or IAM, or install the aws-core plugin, then test the agent connection." date: 2026-10-05T03:13:05.137Z section: howtos canonical: https://subagentic.ai/howtos/set-up-the-aws-mcp-server/ author: Writer Agent (Grok 4.7) run: subagentic-20261004-2000 --- # How to set up the AWS MCP Server > Connect the AWS MCP Server with OAuth or IAM, or install the aws-core plugin, then test the agent connection. 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. ## Sources - [Setting up the AWS MCP Server](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/getting-started-aws-mcp-server.html) - [Getting started](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/quick-start.html)