What Is the AWS Agent Toolkit? Architecture, Plugins, and Security Controls for AI Agents

The AWS Agent Toolkit for AWS is a curated collection of plugins, skills, and MCP server configurations that enable AI coding agents—including Claude Code, Codex, Cursor, and Kiro—to interact with AWS services through authenticated, sandboxed, and fully auditable API calls.

Hosted in the aws/agent-toolkit-for-aws repository, this toolkit provides the bridge between generative AI agents and the AWS cloud, packaging domain-specific expertise into reusable components. It ensures that every action an agent takes—whether deploying a Lambda function or querying an S3 bucket—is subject to IAM condition keys, CloudTrail logging, and CloudWatch metrics.

Core Architecture of the AWS Agent Toolkit

The toolkit bundles three primary components that work together to provide safe, structured access to AWS APIs.

The MCP Server Component

At the heart of the system lies the MCP Server (Model Context Protocol), a managed endpoint defined in the repository’s README.md. This server authenticates agents, provides full AWS API coverage, runs sandboxed Python scripts, and exposes real-time AWS documentation. It acts as the secure gateway through which all agent requests flow, ensuring centralized authentication and authorization before any AWS resource is touched.

Plugin Structure

Plugins are domain-specific packages that group related skills and MCP server configurations. The repository organizes these under the plugins/ directory, with four primary offerings:

• aws-core – Located in plugins/aws-core/, this plugin covers fundamental AWS services including service selection, CDK/CloudFormation, serverless architectures, containers, storage, observability, billing, SDK usage, and deployment workflows.
• aws-agents – Found in plugins/aws-agents/, this package provides skills for building AI agents on AWS using Amazon Bedrock and AgentCore.
• aws-data-analytics – Stored in plugins/aws-data-analytics/, it delivers data-lake, ETL, Athena, and Glue workflow capabilities.
• aws-agents-for-devsecops – Located in plugins/aws-agents-for-devsecops/, this plugin supports incident investigation, code review, vulnerability scanning, and penetration testing using specialized DevOps and Security Agents.

Skills and Rules System

Each skill is a self-contained markdown package within a plugin’s skills/ subdirectory that contains step-by-step guidance, reference snippets, and optional shell or Python scripts. Rules, defined in files like rules/aws-agent-rules.md, provide policy-level guardrails including IAM condition keys, required CloudWatch metrics, and CloudTrail audit logging requirements. These rules enforce organizational compliance by differentiating agent actions from human actions and mandating observability for every request.

How AI Agents Use the Toolkit

The workflow follows a discover-load-execute pattern that keeps agents within defined operational boundaries.

Discovery and Execution Flow

An agent first discovers the appropriate plugin from the registry, loads the required skill(s) from the corresponding skills/ directory, and then issues MCP calls to perform the AWS operation. For example, when creating a Lambda function, the agent might reference the aws-serverless skill from plugins/aws-core/skills/aws-serverless/ and execute:

aws-serverless create-function \
  --function-name MyFunction \
  --runtime python3.11 \
  --handler app.handler \
  --zip-file fileb://my-function.zip

The MCP server intercepts this request, validates it against the rules defined in rules/aws-agent-rules.md, logs the action to CloudTrail, and only then forwards the authenticated call to the AWS API.

Sandboxed Script Execution

The toolkit supports running Python scripts in a sandboxed environment via the MCP server. A skill can embed a script reference (e.g., plugins/aws-core/skills/aws-serverless/references/deployment.script.md) containing code like:

import boto3, json

client = boto3.client('lambda')
response = client.get_function_configuration(FunctionName='MyFunction')
print(json.dumps(response, indent=2))

The MCP server executes this script with restricted permissions, ensuring the agent cannot exceed the IAM policy boundaries defined in the active ruleset.

Built-in Security Guardrails

Security is not an afterthought in the AWS Agent Toolkit; it is enforced through three integrated mechanisms:

• IAM Condition Keys – Policies differentiate between agent-initiated and human-initiated actions, allowing fine-grained access control based on the principal’s origin.
• CloudWatch Metrics and CloudTrail Audit Logs – Every MCP request generates CloudWatch metrics for monitoring and CloudTrail logs for forensics, providing a complete audit trail of agent activity.
• Pre-installed Evaluations – The toolkit includes evaluation suites that verify skill reliability and safety before execution, preventing agents from running unverified or potentially destructive operations.

These guardrails enable enterprises to adopt AI coding assistants while maintaining strict compliance and least-privilege access models.

Installing and Configuring Plugins

Integration depends on the specific AI agent platform, with Claude Code being a primary supported environment.

To install the core plugin in Claude Code:

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

To install the DevSecOps plugin:

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-agents-for-devsecops
/reload-plugins
/aws-agents-for-devsecops:setup

For agents supporting the npx workflow, you can add skills directly from the repository:

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

Once installed, agents automatically discover available capabilities by scanning the skills/ directories within each plugin folder and validating their manifests against the MCP server’s configuration.

Summary

• The AWS Agent Toolkit provides a secure, extensible framework for AI agents to manage AWS infrastructure through the aws/agent-toolkit-for-aws repository.
• It consists of three pillars: an MCP Server for authenticated API access, Plugins (aws-core, aws-agents, aws-data-analytics, aws-agents-for-devsecops) that bundle domain expertise, and Skills & Rules that enforce operational and security policies.
• Guardrails are enforced via rules/aws-agent-rules.md, utilizing IAM condition keys, CloudTrail logging, and CloudWatch metrics to differentiate and monitor agent actions.
• Agents follow a discover-load-execute workflow, retrieving markdown-based skill definitions and running sandboxed scripts through the MCP server.
• Installation is agent-specific, with native support for Claude Code via /plugin install commands and general support through npx skills for other MCP-compatible agents.

Frequently Asked Questions

What AI agents are compatible with the AWS Agent Toolkit?

The toolkit is designed for MCP-compatible AI coding agents, specifically Claude Code, Codex, Cursor, and Kiro. These agents connect to the MCP server to authenticate and route AWS API calls through the toolkit’s curated plugins and skills.

How does the toolkit prevent AI agents from making unauthorized changes?

Authorization is enforced through IAM condition keys defined in rules/aws-agent-rules.md that tag and restrict agent sessions, combined with mandatory CloudTrail audit logging for every request. The MCP server acts as a gatekeeper, ensuring no AWS API call proceeds without passing policy validation and identity verification.

What is the difference between a plugin and a skill in the AWS Agent Toolkit?

A plugin is a high-level domain package (e.g., plugins/aws-core/) that contains configuration, dependencies, and a collection of related skills. A skill is a granular, self-contained markdown file within that plugin’s skills/ directory that provides specific instructions, code snippets, and scripts for a single task—such as creating a Lambda function or configuring a Glue ETL job.

Where can I find the security rules and guardrail definitions?

All policy-level guardrails are defined in rules/aws-agent-rules.md at the repository root. This file specifies the IAM condition keys, required CloudWatch metrics, and CloudTrail logging configurations that enforce organizational compliance across all agent operations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}