AWS MCP Server Setup Guide (2026): Managed, GA, 15K APIs

TL;DR + what you actually need

Four facts that shape every decision below:

• It’s remote and managed. The server runs at https://aws-mcp.us-east-1.api.aws/mcp (or eu-central-1 for Frankfurt). Nothing to host, nothing to update, no per-service local servers to babysit.
• Auth is IAM, bridged by a local proxy. The endpoint wants SigV4-signed requests; MCP clients speak OAuth for remote servers. AWS’s answer is mcp-proxy-for-aws — a small stdio process your client launches via uvx that signs requests with credentials from your local AWS credential chain. You need uv installed and (for API calls) working AWS credentials — aws login on AWS CLI 2.32+ is the simplest path.
• It costs nothing extra. No charge for the server; you pay for whatever AWS resources the agent creates. Docs search and skill discovery don’t even need credentials.
• It replaces two older servers. If you run aws-api-mcp-server or aws-knowledge-mcp-server from the awslabs suite, AWS recommends removing them when you adopt this one — overlapping tools confuse agents.

The one-liner for Claude Code, if you only came for the copy-paste:

claude mcp add-json aws-mcp --scope user \
'{"command":"uvx","args":["mcp-proxy-for-aws==1.6.0","https://aws-mcp.us-east-1.api.aws/mcp","--metadata","AWS_REGION=us-west-2"]}'

Swap AWS_REGION=us-west-2 for the Region your resources live in. The rest of this guide explains why that snippet looks the way it does and what the server can do once it’s connected.

What the AWS MCP Server actually is

The AWS MCP Server is a managed remote MCP server — AWS-operated infrastructure that exposes a small, fixed set of tools to any MCP client. Per AWS’s GA announcement, it gives coding agents “secure, auditable access to AWS services through the Model Context Protocol”, and it’s the core component of the new Agent Toolkit for AWS. It launched in preview on November 30, 2025 (us-east-1 only) and went GA on May 6, 2026 with a second region (Frankfurt), IAM condition-key support, and credential-free documentation search.

The design choice that matters: instead of one MCP tool per AWS API (which would blow past every client’s tool budget — there are over 15,000 operations), the server collapses everything into roughly ten tools. One tool, aws___call_aws, executes any AWS API operation. Another, aws___run_script, runs agent-written Python server-side in a sandbox for multi-step workflows. The rest handle documentation, skills, regions, presigned URLs, and long-running task polling. Your agent gets the whole AWS surface without the context bloat of 15,000 tool definitions — a pattern we’ve covered before in our context-bloat deep dive.

In practice that means you can ask Claude Code “create an S3 bucket with versioning and a lifecycle policy that moves objects to Glacier after 90 days” and the agent searches current AWS docs, finds the relevant skill, and executes the right sequence of API calls — under your IAM identity, with every call logged to CloudTrail. The verification prompt AWS suggests after install is simply “What AWS Regions are available?”

Managed AWS MCP Server vs the awslabs suite (the distinction nobody explains)

Search “AWS MCP server” and you’ll hit two very different things with nearly identical names. Picking wrong wastes an afternoon.

The awslabs/mcp repo (docs at awslabs.github.io/mcp) is a catalog of dozens of open-source servers grouped into categories — documentation, infrastructure, data & analytics, cost & operations, and more. They predate the managed server and most remain useful when you want a narrow, auditable tool surface for one service.

Two of them are now effectively superseded. AWS’s own setup docs say it plainly: if you use the AWS API MCP Server or AWS Knowledge MCP Server, “we recommend switching to the AWS MCP Server” — and removing the old entries from your config, because duplicate tools “can confuse AI agents and reduce performance.” Our take: that advice is correct. The managed server does both jobs with less setup, and the IAM condition keys give you control the local servers never had. Keep specialized awslabs servers (CDK guidance, cost analysis) if they earn their context window; drop the two general-purpose ones.

Auth model: IAM + SigV4 through a local proxy

This is the part of the setup where everyone slows down, so here is the exact shape of it. The AWS MCP Server endpoint authenticates requests with SigV4 — the same request-signing scheme every AWS API uses. But the MCP spec’s remote authentication story is OAuth 2.1 (we’ve written up how OAuth 2.1 works for remote MCP servers). MCP clients don’t know how to SigV4-sign anything.

AWS bridges the gap with MCP Proxy for AWS — an open-source stdio proxy. Your MCP client launches it as a local subprocess (uvx mcp-proxy-for-aws==1.6.0 <endpoint>); the proxy reads credentials from the standard AWS credential provider chain, signs each outgoing MCP request with SigV4, and forwards it to the remote endpoint. So the “remote” server is, from your client’s point of view, a local stdio server. That’s why the configs below all say "command": "uvx" rather than "url": ….

The credential setup AWS recommends:

# AWS CLI 2.32.0 or later
aws login                      # browser sign-in; credentials auto-rotate
aws sts get-caller-identity    # verify who you are

# uv (required for the proxy)
curl -LsSf https://astral.sh/uv/install.sh | sh

aws login is the underrated piece: it rotates your credentials every 15 minutes and keeps the session valid for up to 12 hours. That matters because expired session tokens are, per AWS’s own troubleshooting table, the single most common reason the MCP server silently stops working mid-day. SSO, IAM access keys, and cross-account roles also work — anything the credential chain resolves.

Three properties of this model worth internalizing:

1. The agent is you. Every call_aws invocation executes under your IAM identity. There is no separate “agent account” unless you create one — which, for anything beyond personal experimentation, you should (see the guardrails section).
2. No new secret type. Nothing like a Datadog APP key or an OpenAI token to mint and paste. If aws sts get-caller-identity works in your terminal, the proxy will authenticate.
3. Two Regions, two meanings. The endpoint Region (us-east-1 or eu-central-1) picks which MCP server you talk to. The --metadata AWS_REGION=… parameter sets the default Region for the AWS operations the server performs. They can differ — you can connect to the us-east-1 endpoint and operate on eu-west-1 resources. Without the metadata parameter, all operations default to us-east-1, which is a classic “why is my bucket list empty” footgun.

Install (every client)

The install card below pulls configs from the canonical /servers/aws-managed catalog entry. For docs search and skill discovery the endpoint works without credentials; for call_aws and run_script you need the proxy + credential setup from the previous section.

One-line install · AWS (Managed)

Open server page

Install

Cursor

One-click install

1-Click

VS Code

One-click install

1-Click

Claude Desktop

Copy configuration

Claude Code

Copy CLI command

CLI

Gemini

Copy CLI command

CLI

Codex

Copy CLI command

CLI

Windsurf

Copy configuration

ChatGPT

Add via Settings → Connectors

M

Manual

Copy configuration

Client-by-client, the verified paths from AWS’s Agent Toolkit docs:

Claude Code

Two options. The plugin route bundles the MCP server config and a curated set of AWS skills in one install:

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-core@agent-toolkit-for-aws
/reload-plugins

Or register just the server with claude mcp add-json (the TL;DR snippet above). The plugin route is better for most people — the bundled skills are contributed by AWS service teams and meaningfully improve multi-step task quality. Full client reference at /clients/claude-code.

Cursor / Claude Desktop

Paste into ~/.cursor/mcp.json (see /clients/cursor) or claude_desktop_config.json:

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws==1.6.0",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

Kiro

Same JSON shape in ~/.kiro/settings/mcp.json, with two extra fields AWS includes for Kiro: "timeout": 100000 and "transport": "stdio". Then install skills: npx skills add aws/agent-toolkit-for-aws/skills.

Codex CLI

Either codex plugin marketplace add aws/agent-toolkit-for-aws and install aws-core from /plugins, or add the TOML directly to ~/.codex/config.toml:

[mcp_servers.aws_mcp]
command = "uvx"
args = [
  "mcp-proxy-for-aws==1.6.0",
  "https://aws-mcp.us-east-1.api.aws/mcp",
  "--metadata", "AWS_REGION=us-west-2"
]
startup_timeout_sec = 60

The wizard (any client)

AWS CLI 2.35.0+ ships an interactive setup that detects installed agents (Kiro, Cursor, Claude Code, and others), installs default skills, and writes the MCP config in one command:

aws configure agent-toolkit

Whichever path you take, verify with a new conversation and the prompt “What AWS Regions are available?” A Region list back means the connection works. First initialization can take a couple of minutes.

Tools walkthrough

The server exposes ten tools in two families (names as they appear in your client’s tool list, from AWS’s tools reference):

Knowledge tools (no credentials required)

• aws___search_documentation — searches all AWS documentation: API references, service guides, best practices, and skills. The entry point for almost every task.
• aws___read_documentation — fetches a specific docs page converted to markdown.
• aws___recommend — related-content recommendations for a docs page.
• aws___retrieve_skill — pulls a domain-specific skill: workflows, decision frameworks, step-by-step procedures maintained by AWS service teams. Skills replaced the preview-era “Agent SOPs.”
• aws___list_regions and aws___get_regional_availability — Region identifiers and per-Region availability of services, features, SDK APIs, and CloudFormation resources. The availability check is quietly excellent: agents love proposing services that don’t exist in your Region, and this tool stops that.

API tools (credentials required)

• aws___call_aws — executes AWS API operations with syntax validation and error handling. This is the “one tool, 15,000 APIs” workhorse, including operations needing file uploads or long-running execution.
• aws___run_script — the agent writes a short Python script that runs server-side in a sandbox with AWS API access. Built for the patterns that are miserable as sequential tool calls: listing resources and checking properties across services, parallel API calls, retry logic. Per AWS’s GA post, the sandbox inherits your IAM permissions but has no access to your shell or local filesystem — the multi-step orchestration happens in a single round-trip instead of twenty.
• aws___get_presigned_url — presigned S3 URLs for uploads/downloads, and for CLI commands that expect a local file path.
• aws___get_tasks — polls long-running tasks started by call_aws or run_script.

Opinionated takeaway: run_script is the tool that separates this server from every community AWS wrapper. A “find all unencrypted S3 buckets across 14 Regions” task is ~30 sequential tool calls in a naive server and one sandboxed script here. If you’re evaluating whether the managed server is worth switching to, evaluate that tool first. (If sandboxed code execution as a primitive interests you, our sandbox platform comparison maps the broader landscape.)

Recipes

Five workflows where the server earns its slot, assuming valid credentials and the right AWS_REGION:

Recipe 1 — Build with current docs, not training data

Prompt: “What AWS services should I use to build a serverless API? Check current best practices before answering.” The agent calls search_documentation and retrieve_skill instead of free-associating from a training cutoff. The difference shows up most on fast-moving services (Bedrock, AgentCore) where model memory is reliably stale.

Recipe 2 — Create real infrastructure, with audit

Prompt: “Create an S3 bucket with versioning enabled and a lifecycle policy that transitions objects to Glacier after 90 days.” The agent retrieves the relevant skill, then issues the call_aws operations. Afterward, check CloudTrail: every call is attributed to your identity with the MCP context keys attached — the audit story most DIY agent setups never get around to.

Recipe 3 — Fleet-wide checks via run_script

Prompt: “List every Lambda function across all Regions still running a deprecated runtime, with its last invocation time.” Done as tool calls this is Region × function round-trips; the agent instead writes one Python script and run_script executes it server-side.

Recipe 4 — Troubleshoot a failed deployment

Prompt: “Help me troubleshoot why my CloudFormation deployment failed.” The agent reads stack events through call_aws, cross-references error messages against current docs, and proposes the fix. Pair it with an observability MCP server — our Datadog MCP guide covers the metrics-and-logs half of the same triage loop.

Recipe 5 — Cross-account work in one session

Since June 2026: configure named profiles, launch the proxy with --profile (or AWS_MCP_PROXY_PROFILES), and the API tools grow an aws_profile parameter. Prompt: “Compare the staging account’s VPC config against prod and list the differences.” The agent routes each request through the right profile.

IAM guardrails + audit (the GA headline feature)

The reason this server exists as a managed service rather than another npm package is governance. Three layers, all verified from AWS’s docs and security blog:

1. IAM condition context keys. GA introduced two standardized keys:

• aws:ViaAWSMCPService — boolean, true when a request arrives through any AWS-managed MCP server.
• aws:CalledViaAWSMCP — the service principal of the specific server, e.g. aws-mcp.amazonaws.com.

That lets you write one policy for humans and a stricter overlay for agents using the same role. The canonical example from AWS’s security blog: allow s3:GetObject and s3:ListBucket normally, but deny s3:DeleteObject and s3:DeleteBucket when aws:ViaAWSMCPService is true. An org-wide SCP keyed on the same condition can deny all MCP-driven mutations across every account. This also removed the preview-era requirement for a separate MCP-specific IAM permission.

2. CloudWatch metrics. The server publishes usage metrics under the AWS-MCP namespace, so platform teams can see which agents are calling what, and alarm on anomalies.

3. CloudTrail. Every API call the agent makes is captured — same trail, same tooling as the rest of your audit pipeline. Nothing new to build.

Our recommendation for teams: run agents under a dedicated role with read-only permissions plus an explicit allowlist of mutating actions, and use the condition keys as the second lock. The skeptics’ core objection to this launch (see the community section) is that nothing forces you to do this — the server happily executes whatever your IAM identity allows. The guardrails are real, but they are opt-in.

Limits + cost

• Server cost: zero. AWS’s GA post: “There is no additional charge for the AWS MCP server itself. You pay only for the AWS resources you create.” The billing risk is the agent, not the server — an agent told to “set up a data pipeline” can provision billable resources in seconds. Budget alarms and the IAM guardrails above are the mitigation.
• Two endpoint Regions. us-east-1 and eu-central-1 at GA. The server can call APIs in any Region, so this only affects latency and data-routing preferences, not reach.
• Credential lifetime. Session tokens default to short lifetimes (one hour in many setups); aws login stretches that to a 12-hour auto-rotating session. Long agent sessions die at token expiry, not gracefully — see troubleshooting.
• Sandbox boundaries. run_script executes server-side with your IAM permissions only — no shell, no local filesystem. Scripts that need your repo’s files belong in your agent’s own execution environment, not in the MCP sandbox.
• Token budget. AWS says GA reduced token consumption per interaction versus preview. Still, read_documentation on a long page returns a long page; prefer search_documentation snippets and let the agent fetch full pages selectively.

What we got wrong (so you don’t)

Three assumptions we carried into testing that the docs quietly corrected:

1. We assumed “remote server” meant pasting the URL into our client’s remote-MCP field. It doesn’t work for the API tools — the endpoint wants SigV4, clients want OAuth 2.1, and the bridge is the local mcp-proxy-for-aws process. The “remote” server is configured like a stdio server. Once that clicked, every config snippet made sense.
2. We assumed the endpoint Region was where our operations would run. Wrong — without --metadata AWS_REGION=… everything defaults to us-east-1, and our eu-west-1 resource listings came back empty with no error. The endpoint Region and the operating Region are independent settings.
3. We assumed this deprecated the whole awslabs suite. It supersedes exactly two servers (API and Knowledge). The specialized ones — CDK guidance, cost analysis, per-database servers — remain the right call when you want a deliberately narrow tool surface.

Troubleshooting

The errors below come straight from AWS’s own authentication troubleshooting table, plus the failure modes we hit ourselves.

Which AWS MCP do you actually want?

“AWS MCP” is now a family, not a server. The honest decision tree:

• You work across AWS services and want one install: the managed AWS MCP Server (this guide). Docs + skills + every API + sandbox, with IAM governance. Default choice for 2026.
• You only want AWS documentation, no AWS account, no credentials: the open-source AWS Documentation server. Local, narrow, nothing it can break.
• You want a deliberately small blast radius on one service: a scoped server like S3 or Athena. An agent that can only read buckets can’t delete your CloudFormation stacks, no IAM policy required.

AWS Documentationawslabs

Official1-Click ReadyRemote

Access and search AWS documentation easily with this AWS document management solution, including WorkDocs tools and reco

7189

AWS S3samuraikun

1-Click Ready

Access AWS S3 storage to list buckets, browse objects, and extract text from files like PDFs with ease.

cloud infrastructurefile systems7612

AWS Athenalishenxydlgzs

1-Click Ready

AWS Athena connector lets you run SQL on AWS data lakes via Athena in AWS, empowering rapid, large-scale business intell

databasescloud infrastructure1.0k5

There’s also a long tail of specialized entries — Lambda Powertools docs search among them — worth browsing in the full directory if your workflow is narrower than “all of AWS.” For more hosted options like this one, see our remote MCP servers listing.

Community signal: measured praise, real worry

The GA reception split along a predictable line. InfoQ’s coverage quotes Ciena principal architect Darryl Ruggles calling it a “measured approach” to giving agents AWS access, while AWS’s Sébastien Stormacq argues the combination of “current documentation, authenticated API access, and sandboxed script execution in a single server changes what an agent can actually do on AWS.”

The skeptics are worth hearing. In the same piece, a ReliaQuest DevOps engineer flags that “there are no gateways to restrict certain actions or operations” out of the box — the guardrails exist but you must write the IAM policies yourself. Ampt founder Jeremy Daly adds that “AWS doesn’t have the same head start they did with serverless” in the agent race. And a widely shared critical post on DEV framed the launch as handing agents your cloud keys, predicting the first headline-grade “agent deleted production” incident within the year. Our read: the criticism is really about defaults, not capability — which is exactly why the governance section above leads with deny-by-condition policies.

FAQ

Sources

• GA announcement (May 6, 2026): aws.amazon.com/about-aws/whats-new/2026/05/aws-mcp-server
• GA deep-dive on the AWS News Blog: The AWS MCP Server is now generally available
• Preview announcement (Nov 30, 2025): aws.amazon.com/about-aws/whats-new/2025/11/aws-mcp-server
• Agent Toolkit quick start (install commands): docs.aws.amazon.com/agent-toolkit — quick-start
• Server setup + auth troubleshooting: Setting up the AWS MCP Server
• Tool reference: Understanding the MCP Server tools
• IAM condition keys + example policies: Understanding IAM for managed AWS MCP servers (AWS Security Blog)
• Cross-account/cross-role update (June 5, 2026): aws.amazon.com/about-aws/whats-new/2026/06/aws-mcp-server
• MCP Proxy for AWS: github.com/aws/mcp-proxy-for-aws · Agent Toolkit repo: github.com/aws/agent-toolkit-for-aws
• Open-source suite: github.com/awslabs/mcp / awslabs.github.io/mcp
• Press + community: InfoQ — AWS MCP Server Reaches GA · critical take on DEV Community
• Canonical MCP.Directory entry: /servers/aws-managed