Connect Claude Code to Live AWS Tools with the Agent Toolkit

AI coding agents are getting remarkably capable — but they have a blind spot. The models powering them were trained on data that’s months or years old. When you ask your agent about Amazon S3 Tables, Aurora DSQL, or any service that launched recently, it’s either guessing or drawing a blank.

The Agent Toolkit for AWS fixes this — it’s an open-source toolkit from AWS that connects Claude Code to live documentation, API execution, and tested workflows via the Model Context Protocol (MCP).

What’s Inside the Agent Toolkit for AWS?

• AWS MCP Server — A managed remote server at aws-mcp.us-east-1.api.aws. Agents call it to search documentation, execute AWS CLI commands, run sandboxed Python scripts, and check regional service availability. All calls are authenticated via IAM and logged in CloudTrail.
• Agent Skills — Curated instruction packages loaded on demand. Skills cover service selection decisions, step-by-step deployment workflows, and troubleshooting procedures. They’re retrieved only when relevant, so they don’t bloat the context window.
• Plugins — Single-install packages for Claude Code and Codex that bundle the MCP server config and a starter skill set.
• Rules files — Project-level guardrails that tell the agent how to behave: use the MCP server, discover skills before acting, search docs before assuming.

It’s free. You pay only for AWS resources your agent provisions.

Tools Available to the Agent

Once connected, Claude Code has access to:

Tool	What it does
search_documentation	Semantic search across all AWS docs
read_documentation	Fetch and read specific AWS doc pages live
call_aws	Execute any AWS CLI command via the MCP server
run_script	Run Python in a sandboxed environment (no local filesystem access)
get_regional_availability	Check which services/features are available in which regions
suggest_aws_commands	Get CLI command suggestions for a task
recommend	Discover related documentation for a given page

How to Set It Up with Claude Code

Step 1: Create a scoped IAM role

You don’t want to hand the agent your admin credentials. Create a dedicated IAM role with least-privilege permissions using the infrastructure repo.

The key insight: the toolkit injects two IAM condition keys into every request — aws:ViaAWSMCPService and aws:CalledViaAWSMCP. This lets you write policies that apply only to agent-originated calls, separate from your own human actions:

// Allow writes only when the call comes through the AWS MCP server
condition {
  test     = "StringEquals"
  variable = "aws:CalledViaAWSMCP"
  values   = ["aws-mcp.amazonaws.com"]
}

// Hard deny destructive actions via any AWS-managed MCP server
condition {
  test     = "Bool"
  variable = "aws:ViaAWSMCPService"
  values   = ["true"]
}

These condition keys mean your agent’s blast radius is bounded by policy — not by hoping the model doesn’t do something destructive.

Step 2: Configure credential auto-refresh

Avoid the token expiry problem. Instead of role_arn + source_profile (which can silently break in long-running processes), use credential_process in ~/.aws/config. The SDK calls your script fresh whenever credentials expire:

[profile ai-agent]
credential_process = /home/YOUR_USER/.aws/assume-ai-agent.sh
region             = us-east-1

The script calls sts:AssumeRole and returns credentials with a 12-hour session (MaxSessionDuration = 43200 on the role), so refreshes are rare and automatic.

Step 3: Install the plugin in Claude Code

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

Step 4: Point the plugin at your scoped role

Add this to ~/.claude/settings.json:

{
  "env": {
    "AWS_PROFILE": "ai-agent"
  }
}

Reload Claude Code. The MCP server starts, authenticates as your scoped role, and the tools are live.

What the Agent Can Now Do

With the toolkit connected, Claude Code stops answering from stale training data and starts fetching live information:

You: What's the maximum Lambda execution timeout and what are the native AWS workarounds?

Instead of guessing, the agent fetches the current Lambda quotas page, checks for recent changes, and gives you an accurate answer with links to the docs.

You: Set up an S3 Table with Iceberg format for my analytics pipeline

The agent loads the S3 Tables skill, follows the tested procedure step by step, and executes the CLI commands — correctly, on the first try.

The same applies to troubleshooting: point it at a failing CloudFormation stack or a Lambda error rate spike, and the agent uses live CloudWatch data and documented diagnostic procedures rather than generic advice.

Key Takeaways

• The Agent Toolkit connects Claude Code to live AWS documentation and API execution via MCP — the model’s training cutoff stops mattering for AWS questions.
• Scope the IAM role tightly and use the aws:CalledViaAWSMCP condition key to isolate agent-originated calls from human actions.
• Use credential_process instead of role_arn + source_profile to avoid silent credential expiry in long sessions.
• Installation is one command in Claude Code — the rest is IAM and settings.json.

Resources

• Agent Toolkit for AWS — GitHub
• Official Documentation
• AWS Product Page