AWS just shipped the official way to let a coding agent build, deploy, and operate on your cloud — a managed MCP server, evaluated skills, and guardrails that finally distinguish what an **agent* did from what a human did. This is a deep dive on how the Agent Toolkit for AWS works, the IAM trick that makes it enterprise-ready, and how to wire it into Claude Code, Cursor, Codex, or Kiro without handing over the keys to the kingdom.*
Why This Matters
Point an AI coding agent at AWS and you get an instant taste of both heaven and hell.
Heaven: "spin up a serverless API with a DynamoDB table, wire the IAM role, and deploy it." The agent knows CloudFormation, it knows the SDK, it just does it.
Hell: the agent is now an actor inside your account with your permissions, calling APIs you can't easily see, against 300+ services where a single wrong delete-* is unrecoverable. Every community MCP server that "connects Claude to AWS" runs into the same three questions I keep hammering on: Is the credential scoped? Are side effects documented? Is there a trace when it acts? For production AWS, "it works on my laptop" is not good enough. You need governance.
That's exactly the gap the Agent Toolkit for AWS was built to close. It's AWS's official, supported answer to "how do I let an agent touch my cloud safely" — and the headline feature isn't the 15,000 APIs it exposes. It's that AWS can now tell, at the IAM layer, whether a request came from a human or from an agent, and write policy accordingly. That single capability changes the risk calculus entirely.
Let me break down the whole thing.
TL;DR
- The Agent Toolkit for AWS gives AI coding agents the tools, knowledge, and guardrails to work with AWS. It works with the agents you already use — Claude Code, Codex, Cursor, Kiro, and any MCP client.
- Three pillars: a managed AWS MCP Server (capability), curated Skills (competence), and Rules files (guardrails). Plugins bundle all three into one install.
- The MCP Server covers 300+ services and 15,000+ APIs through one authenticated endpoint, plus a sandboxed Python runtime and no-auth documentation search.
- The killer feature: IAM condition keys that distinguish agent actions from human actions, so you can enforce "agents get read-only" even when the underlying role can write — with CloudTrail audit logging and CloudWatch metrics on every request.
- It's the successor to the AWS Labs MCP servers/skills from 2025, now managed, evaluated, and governed. Apache-2.0, ~2k stars, actively developed.
- Setup is a paste-one-prompt affair, or a handful of AWS CLI commands if you want to see every step.
What Is the Agent Toolkit for AWS?
In one sentence: official, AWS-supported MCP servers, skills, and plugins that help AI agents build on AWS.
If you've read my earlier pieces on MCP servers and Claude Skills, the shape will feel familiar — this is the same MCP-plus-Skills architecture, but assembled, managed, and hardened by AWS itself for one domain: your cloud.
It's also a consolidation. Through 2025, AWS shipped a scattering of MCP servers, skills, and plugins under AWS Labs. The Agent Toolkit is the official successor. The Labs tooling keeps working, but the best of it is being folded into the Toolkit — because the Toolkit adds the three things Labs couldn't guarantee: agent-aware IAM, full audit logging, and end-to-end-evaluated skills. If you're starting today, start here.
The Architecture: Three Pillars + a Bundle
The Toolkit is not one thing; it's a small system of complementary parts. Understanding the split is the key to using it well, because — critically — the pieces work independently. Skills don't require the MCP server; the MCP server doesn't serve your local skills. You can adopt as much or as little as you need.
┌─────────────────────────────────────────┐
│ Your coding agent │
│ (Claude Code · Cursor · Codex · Kiro) │
└───────────────┬───────────────┬───────────┘
│ │
┌──────────────────▼───┐ ┌───────▼────────────────┐
│ AWS MCP Server │ │ Skills (local) │
│ (capability) │ │ (competence) │
│ • 15,000+ APIs │ │ • on-demand SKILL.md │
│ • sandboxed Python │ │ • CDK, serverless, … │
│ • live docs search │ └─────────────────────────┘
│ • IAM / CloudTrail │
└──────────────────────┘ ┌─────────────────────────┐
│ Rules files (guardrails)│
│ • use MCP, search docs │
│ • secret-safety, etc. │
└─────────────────────────┘
└────────── Plugins bundle all of the above ──────────┘
Let's take each pillar in turn.
Pillar 1: The AWS MCP Server (Capability)
This is the engine. The AWS MCP Server is a managed, remote server that gives your agent access to AWS through the Model Context Protocol. "Managed and remote" is the first thing that sets it apart from the DIY servers most people run — there's no container to host, no server to patch, and the security controls live in AWS, not in your docker run.
What it provides:
- Full AWS API coverage. Most of the 15,000+ AWS APIs across 300+ services through a single authenticated endpoint. Not a hand-picked subset — the whole surface.
- Sandboxed script execution. The agent can run Python in an isolated environment with AWS access, for the multi-step, cross-service, parallel, retry-heavy work that's painful to express as individual API calls.
- Real-time documentation access. Search and retrieve current AWS docs, API references, and service capabilities — and this part needs no authentication at all. Your agent stops hallucinating APIs because it can look them up.
- Enterprise controls. CloudWatch metrics, IAM condition keys, and CloudTrail audit logging on every request. (More on this — it's the whole ballgame.)
The tools it exposes
The server surfaces a tight, well-designed toolset — two families, exactly the "knowledge vs. action" split good MCP servers use:
Knowledge tools (read, no mutations):
| Tool | What it does |
|---|---|
aws___search_documentation |
Search all AWS docs, best practices, service guides, and skills |
aws___read_documentation |
Fetch a doc page and convert it to clean Markdown |
aws___retrieve_skill |
Pull the full content of a named skill (workflows, decision frameworks) |
aws___list_regions |
List all AWS Regions and identifiers |
aws___get_regional_availability |
Check whether a service/feature/API exists in a Region |
API tools (the ones that actually do things):
| Tool | What it does |
|---|---|
aws___call_aws |
Execute an authenticated AWS API call with syntax validation and error handling |
aws___run_script |
Run Python in a sandbox with AWS access — for multi-step, parallel, cross-service work |
aws___get_presigned_url |
Generate pre-signed S3 URLs for direct upload/download |
aws___get_tasks |
Poll the status of long-running call_aws / run_script operations |
The design intent is clean: skills guide the workflow, knowledge tools supply current facts, and API tools execute — each with proper auth and authorization. That separation is exactly what you want from an agent touching infrastructure.
The Killer Feature: IAM That Knows It's Talking to an Agent
Here's the part that made me sit up, and the reason I'd reach for this over any community AWS MCP server for anything near production.
Every other "connect an agent to AWS" approach has the same fundamental flaw: to the cloud, the agent is you. It inherits your IAM role. If your role can dynamodb:DeleteTable, so can the agent, and IAM has no way to tell the difference between you clicking a console button and an agent looping through a workflow at 2 a.m.
The Agent Toolkit breaks that tie. The managed MCP server passes IAM condition keys that distinguish agent actions from human actions. Which means you can write policies that apply only to agents:
Allow this developer's role to take write actions normally — but only allow read-only actions when the request comes through the agent.
Read that again, because it's the whole enterprise story. You no longer have to choose between "give the agent a crippled role" and "give the agent your full power." You give it your role, and constrain what it's allowed to do as an agent, independently. Least privilege that finally matches how people actually work.
And it doesn't stop at prevention:
- CloudTrail audit logging captures every request the agent makes — so after the fact you can answer exactly what it did, with what, and why. That "useful trace" is the thing DIY servers almost never give you.
- CloudWatch metrics let you monitor agent activity in aggregate — volume, errors, patterns.
- Read-only mode (via SigV4 auth) can hide write-capable tools from the agent entirely, so they never even appear in its toolset.
Scoped credentials, documented side effects, clean failures, and a full audit trail — the exact rubric I'd apply to any tool an agent can call, delivered as a managed service. AWS even published a Security Blog deep-dive, "Understanding IAM for managed AWS MCP servers," if you want the policy-level detail.
Authentication: OAuth vs. SigV4
The server supports two auth methods, and picking the right one matters. Here's the decision guide, distilled:
| Your situation | Use |
|---|---|
| New to AWS, single account, want zero local setup | OAuth |
| Web-only client (no local process) | OAuth |
| Terminal/IDE agent (Claude Code, Kiro, Codex) | SigV4 |
| Need multiple AWS accounts in one session | SigV4 |
| Need read-only mode (hide write tools) | SigV4 |
| Need a default Region for the session | SigV4 |
| Org restricts the OAuth sign-in permissions | SigV4 |
OAuth (simple) connects directly to the remote server — a human authenticates in the browser, an automated agent requests a token. Tokens last 1 hour and auto-refresh for up to 12 hours. You attach the AWSMCPSignInOAuthAccessPolicy managed policy and add the endpoint:
claude mcp add aws-mcp https://aws-mcp.us-east-1.api.aws/mcp --transport http
SigV4 (advanced) uses the MCP Proxy for AWS to sign requests with your AWS credentials — this is the one for serious coding-agent work, because it unlocks read-only mode and multi-account switching:
{
"mcpServers": {
"aws-mcp": {
"command": "uvx",
"args": [
"mcp-proxy-for-aws==1.6.3",
"https://aws-mcp.us-east-1.api.aws/mcp",
"--metadata", "AWS_REGION=us-west-2"
]
}
}
}
Pin the proxy version (
==1.6.3, not@latest) for reproducible behavior and supply-chain safety, and check PyPI periodically for stable updates. This is the same discipline I'd apply to any dependency an agent runs.
Two more practical notes: the server endpoints live in us-east-1 and eu-central-1, while the AWS_REGION metadata sets the default operating Region (falling back to us-east-1 if unset). And aws login gives you the smoothest credential story — browser sign-in, no long-lived access keys, auto-rotating short-lived credentials for up to 12 hours.
Pillar 2: Skills (Competence)
If the MCP server is capability, Skills are competence — the procedural know-how for doing AWS tasks the right way. Each skill is a curated package of instructions plus reference material, and — exactly like Claude Skills — they load on demand: the agent discovers and retrieves only what's relevant to the task in front of it, so it doesn't drag a 200-page AWS playbook into context on every turn.
Mechanically, a skill is a directory with a SKILL.md and an optional references/ folder the agent reads from when it needs deeper detail. Install them with one command:
npx skills add aws/agent-toolkit-for-aws/skills
The core aws-core set covers the bread and butter of cloud work: service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, and deployment, with more landing regularly (recent additions include dedicated aws-compute and aws-database skills). And here's the differentiator over a random community skill: these have undergone thorough end-to-end evaluations, so you're not betting your deployment on an untested prompt someone pushed on a Friday.
Pillar 3: Rules Files (Guardrails)
The quietest pillar and, for an architect, one of the most important. Rules files are project-level configuration that tell the agent how to behave with AWS — before it does anything. Things like: prefer the AWS MCP Server for API calls, discover available skills, search the docs before acting, and honor safety constraints.
A concrete example already in the repo: a secret-safety guardrail for AWS Secrets Manager, so the agent doesn't do something careless with your secrets. This is the deterministic backstop layer — the equivalent of the hooks and rules I've written about for Claude Code — that catches the model when instinct isn't enough.
Rules land in each agent's native config location, which the setup handles for you:
| Agent | Rules file | Location |
|---|---|---|
| Claude Code | CLAUDE.md |
Project root |
| Codex | AGENTS.md |
Project root |
| Cursor | .cursor/rules/*.mdc |
.cursor/rules/ |
| Kiro | .kiro/steering/*.md |
.kiro/steering/ |
Plugins: The Three Pillars in One Install
You don't have to wire the pieces up individually. Plugins bundle the MCP Server configuration and the relevant skills into a single install, and there are four worth knowing:
| Plugin | What it's for |
|---|---|
| aws-core | The foundation — service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK, deployment. Start here. |
| aws-agents | Building AI agents on AWS with Amazon Bedrock and AgentCore. |
| aws-data-analytics | Data lake, analytics, and ETL with S3 Tables, AWS Glue, and Athena. |
| aws-agents-for-devsecops | Incident investigation, code review, UAT for release readiness, vulnerability scanning, and pen tests via the AWS DevOps Agent and AWS Security Agent. |
For Claude Code they're on the official marketplace by default:
/plugin install aws-core@claude-plugins-official
Plugins are currently available for Claude Code, Codex, and Cursor; for Kiro and other agents you configure the MCP server directly and add skills from the repo.
Setup: The Fast Path and the Explicit Path
The one-paste path
The genuinely slick part: you can hand the whole setup to your agent. Paste this and it drives the entire process:
Set up Agent Toolkit for AWS by following instructions:
https://raw.githubusercontent.com/aws/agent-toolkit-for-aws/refs/heads/main/setup-instructions/setup.md
Your agent then walks a carefully-guarded runbook: detect your OS, install AWS CLI v2, run aws login (browser-based — it will never ask you for access keys), verify with aws sts get-caller-identity, install the Toolkit, and save the AWS experience rules into your agent's config. The setup instructions are themselves a nice piece of agent engineering — every step has an error-handling table, and hard constraints like "you MUST NOT ask the user for AWS credentials" and "you MUST explain what step is being executed and why." Guardrails all the way down.
The explicit CLI path
If you'd rather see every command (I usually do the first time), the AWS CLI drives it directly:
# 1. Authenticate — browser sign-in, short-lived auto-rotating creds
aws login --region us-east-1
# 2. Confirm who you are
aws sts get-caller-identity
# 3. Install the Toolkit (the service lives in us-east-1 regardless of your Region)
aws configure agent-toolkit --yes --region us-east-1
# 4. See what skills are available in the catalog
aws agent-toolkit list-available-skills --region us-east-1
One gotcha worth flagging: the Agent Toolkit service is currently only available in us-east-1. Use us-east-1 for these commands even if your workloads live elsewhere — that's the control plane Region, not where your resources get created. Your credentials from aws login are valid for 12 hours and renewable for up to 90 days without re-authenticating in the browser.
What a Session Actually Looks Like
Concretely, here's the loop once it's wired up. You ask:
"Stand up an SQS queue with a dead-letter queue, a Lambda consumer, and the IAM role to connect them. Use CDK. Show me the plan before deploying."
Behind the scenes:
- The agent matches the task to the
aws-coreCDK/serverless skill and retrieves it (aws___retrieve_skill) — now it has AWS's own opinionated playbook, not its training-data guess. - It searches live docs (
aws___search_documentation) for the current CDK constructs and any recent API changes — no hallucinated method names. - It drafts the stack, shows you the plan, and on approval executes via
aws___call_aws/aws___run_script, polling long ops withaws___get_tasks. - Your rules file kept it honest throughout (search before acting, respect secret-safety), your IAM condition keys constrained what it could do as an agent, and CloudTrail logged every call for the audit later.
Capability, competence, and guardrails, all firing together. That's the toolkit's whole thesis in one prompt.
An Architect's Guardrails (Read This Part)
The Toolkit hands you real power, so spend it deliberately. My checklist before letting it near anything that matters:
- Use the agent-vs-human IAM condition keys. This is the whole reason to prefer the managed server. Start agents read-only and grant write scopes explicitly, per service, as trust builds.
- Prefer SigV4 with read-only mode for coding agents that shouldn't mutate infrastructure — it hides write tools entirely rather than trusting the model to abstain.
- Turn on the audit trail from day one. CloudTrail + CloudWatch aren't optional extras here; they're how you reason about blast radius. If you can't see what the agent did, you can't govern it.
-
Pin versions. The MCP proxy, the skills, the plugins — pin them and review updates. An agent running
@latestis an un-audited supply chain. - Scope by account. Use SigV4 multi-profile to keep dev and prod credentials separate; never let a single session hold god-mode across accounts by accident.
-
Sandbox the blast radius. Test the agent in a non-prod account first. The
run_scriptsandbox isolates execution, not authorization — a scoped IAM role is still your real boundary. -
Treat rules files as code. Review changes to
CLAUDE.md/AGENTS.md/ steering files the way you'd review a security policy, because that's what they are.
The through-line: the Toolkit gives you the mechanisms for safe agent-on-AWS work, but you still own the policy. Delegation isn't abdication.
How It Compares to Rolling Your Own
I've been vocal that most teams over-collect MCP servers and should curate ruthlessly. So where does this land?
- vs. a community AWS MCP server: No contest for production. Community servers give you API access; they don't give you agent-aware IAM, CloudTrail on every call, or evaluated skills. For a weekend project, roll your own if you like. For anything with a compliance surface, use the official one.
- vs. the old AWS Labs servers: The Toolkit is their successor. Same lineage, now managed, governed, and evaluated. Migrate.
- vs. a giant multi-server sprawl: The Toolkit is actually a consolidation play — one authenticated endpoint for 300+ services instead of a dozen bespoke servers each taxing your context window. That's the anti-sprawl direction I keep advocating.
The honest caveat: it's AWS-specific and the control plane is us-east-1-only today, and the managed/remote model means you're trusting an AWS-hosted endpoint rather than a local process. For most teams already all-in on AWS, those are features, not bugs.
FAQ
Which agents does it support?
Claude Code, Codex, Cursor, and Kiro get first-class support (plugins for the first three). Any MCP-capable client can use the AWS MCP Server directly and install skills from the repo.
Do I need the MCP server and the skills?
No — they're independent. Skills work without the server (they're just local guidance), and the server works without your local skills. Most people want both, but you can adopt incrementally.
Is it free?
The Toolkit itself is Apache-2.0 open source. You pay for the AWS resources your agent creates and any API usage, as always. The managed MCP endpoint is an AWS service.
How is this different from just giving an agent my AWS creds?
Governance. Raw credentials make the agent indistinguishable from you at the IAM layer. The Toolkit's condition keys let you write policy that applies only to agent requests, plus you get CloudTrail/CloudWatch visibility you'd otherwise have to build.
What's the catch with Regions?
The Toolkit control plane and MCP endpoints are limited (endpoints in us-east-1 and eu-central-1; the aws configure agent-toolkit service in us-east-1). Your actual resources deploy to whatever Region you set via AWS_REGION — don't confuse the two.
OAuth or SigV4?
OAuth if you're new, single-account, or on a web client. SigV4 for terminal/IDE coding agents, read-only mode, or multi-account work.
Final Take: AWS Meets Agents Where They Are
For a year the story of AI agents on AWS has been a patchwork — community MCP servers, AWS Labs experiments, everyone hand-rolling credentials and hoping the agent didn't do anything dramatic. The Agent Toolkit for AWS is the moment that patchwork becomes a platform.
What makes it matter isn't the 15,000 APIs — plenty of servers can call APIs. It's that AWS took the three hard problems of agent-on-cloud work and solved them at the layer that counts: capability (a managed server across the whole API surface), competence (evaluated, on-demand skills so the agent does it the AWS way), and governance (IAM that finally knows an agent from a human, with a full audit trail). That last one is the unlock. It's the difference between "we experimented with an agent in a sandbox" and "we let agents operate in production because we can prove and constrain exactly what they do."
If you're building on AWS with a coding agent, this is now the default starting point. Paste the setup prompt, start the agent read-only, turn on the audit trail, and expand its powers as it earns them. Give it the capability, give it the competence — but keep the guardrails yours.
The agent can have 15,000 APIs. You keep the policy. That's how you sleep at night.
About the Author
Suraj Khaitan — Gen AI Architect | Building scalable platforms and secure cloud-native systems
Connect on LinkedIn | Follow for more engineering and architecture write-ups
Have you pointed an agent at your AWS account yet — and how are you scoping what it's allowed to do? Drop your setup in the comments. I'm always comparing notes on safe agent-on-cloud patterns.
Top comments (0)