How to Build Agents Using the AWS Agent Toolkit: Complete Setup Guide

The AWS Agent Toolkit enables AI coding agents to interact with AWS services securely through plugins, skills, and an AWS MCP Server that exposes 300+ AWS APIs through a single authenticated endpoint.

The aws/agent-toolkit-for-aws repository provides a comprehensive framework for integrating popular AI coding agents—including Claude Code, Codex, Cursor, and Kiro—with AWS infrastructure. By combining pre-built plugins with an MCP (Model Context Protocol) server, the toolkit allows agents to discover, deploy, and manage AWS resources without exposing raw credentials to the agent environment.

Understanding the AWS Agent Toolkit Architecture

The toolkit consists of three integrated layers that work together to provide safe, scoped access to AWS APIs.

The AWS MCP Server

The AWS MCP Server acts as a secure gateway between your AI agent and AWS services. It authenticates the agent using your AWS credentials and exposes over 300 AWS APIs through a standardized MCP endpoint. According to the repository's README.md, the server runs as a proxy that translates MCP requests into AWS API calls, ensuring that agents never handle credentials directly.

Plugin Architecture

Plugins are agent-specific bundles that include the MCP server configuration and curated collections of AWS-focused skills. Each plugin targets a specific agent runtime and includes the necessary metadata to register the AWS MCP Server with that agent's plugin system.

Skill Library

Skills are discrete capabilities that teach agents how to perform specific AWS tasks—such as deploying CDK stacks, querying Athena, or investigating security incidents. Skills are stored in the skills/ directory and can be installed individually or as part of a plugin bundle.

Supported AI Coding Agents

The AWS Agent Toolkit officially supports four major agent platforms, with configuration paths documented in the main README.md:

• Claude Code – Uses the claude-plugins-official marketplace
• Codex – OpenAI's agent with native plugin support
• Cursor – IDE-integrated agent using Team Marketplaces
• Kiro – Cloud-based agent using MCP configuration files

Any agent supporting the Model Context Protocol can also connect manually using the AWS MCP Server configuration.

Step-by-Step Setup by Agent

Claude Code

For Claude Code, install the aws-core plugin directly from the official marketplace:

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

To refresh the available plugin list, run:

/plugin marketplace update claude-plugins-official

You can substitute aws-core with aws-agents, aws-data-analytics, or aws-agents-for-devsecops depending on your use case.

Codex (OpenAI)

Codex users must first add the toolkit repository to their plugin marketplace:

codex plugin marketplace add aws/agent-toolkit-for-aws

After adding the marketplace, launch Codex and run /plugins to browse available plugins, then install your desired plugin (e.g., aws-core) from the interface.

Cursor

Cursor requires repository-level configuration through Team Marketplaces:

1. Open Settings → Plugins → Team Marketplaces
2. Add aws/agent-toolkit-for-aws as a marketplace source
3. Install plugins (such as aws-core) from the Plugins panel

Kiro

Kiro requires manual MCP server configuration. Create the file ~/.kiro/settings/mcp.json with the following content:

{
  "mcpServers": {
    "aws": {
      "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"
      ]
    }
  }
}

After configuring the MCP server, install the skill library:

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

Other Agents

For agents not explicitly listed, manually configure the MCP server using the JSON configuration above, then install skills via:

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

Available Plugin Categories

The repository organizes capabilities into four primary plugins, each documented in dedicated README.md files under the plugins/ directory:

• aws-core – Found in plugins/aws-core/README.md, this starter plugin covers service selection, CDK/CloudFormation, serverless architectures, containers, observability, billing, SDK usage, and deployment workflows.

• aws-agents – Skills for building AI agents on AWS using Amazon Bedrock and AgentCore, including prompt engineering and agent orchestration patterns.

• aws-data-analytics – Data lake construction, Glue ETL jobs, Athena query optimization, and vector search implementations.

• aws-agents-for-devsecops – Located in plugins/aws-agents-for-devsecops/README.md, this plugin provides incident investigation, automated code review, UAT validation, vulnerability scanning, and penetration testing workflows.

Key Configuration Files and Resources

Beyond the setup commands, the repository contains several authoritative reference files:

File Path	Purpose
README.md	High-level overview, quick-start instructions, and agent-specific installation commands
plugins/aws-core/README.md	Detailed documentation for the core plugin and its bundled skills
plugins/aws-agents-for-devsecops/README.md	DevSecOps-specific skills and security workflows
rules/aws-agent-rules.md	Recommended policy files that constrain agent behavior to safe AWS usage patterns
skills/README.md	Complete catalog of individual skill packages available for fine-grained installation

For advanced credential setup and authentication flows, consult the User Guide referenced in the main repository documentation.

Summary

• The AWS Agent Toolkit provides plugins, skills, and an AWS MCP Server to connect AI agents with AWS services.
• The AWS MCP Server authenticates via your credentials and exposes 300+ AWS APIs through a single endpoint using mcp-proxy-for-aws@1.6.3.
• Installation varies by agent: Claude Code uses /plugin install, Codex uses marketplace commands, Cursor uses Team Marketplaces, and Kiro uses ~/.kiro/settings/mcp.json.
• Four plugin tiers cover core AWS operations (aws-core), AI agent building (aws-agents), data analytics (aws-data-analytics), and security operations (aws-agents-for-devsecops).
• Configuration files in plugins/aws-core/README.md, rules/aws-agent-rules.md, and skills/README.md provide implementation details and security policies.

Frequently Asked Questions

What is the AWS MCP Server and how does it handle authentication?

The AWS MCP Server is a proxy service that runs locally via uvx and connects to https://aws-mcp.us-east-1.api.aws/mcp. It authenticates using your existing AWS credentials configured in your environment, then exposes AWS APIs through the Model Context Protocol. This design ensures that AI agents interact with AWS resources without ever accessing raw IAM credentials or secret keys.

Which AI coding agents are officially supported by the AWS Agent Toolkit?

The toolkit officially supports Claude Code, Codex (OpenAI), Cursor, and Kiro. Each agent has a specific installation path documented in the repository's README.md: Claude Code uses the claude-plugins-official marketplace, Codex uses codex plugin marketplace add, Cursor uses Team Marketplaces, and Kiro uses MCP configuration files. Any MCP-compatible agent can connect manually using the provided JSON configuration.

How do I install AWS skills for a custom agent that isn't explicitly listed?

For custom agents or those not officially supported, configure the AWS MCP Server manually by adding the JSON configuration to your agent's MCP settings, then install the complete skill library using npx skills add aws/agent-toolkit-for-aws/skills. This command downloads and registers all available skills from the skills/ directory, making them available to your agent regardless of the specific IDE or runtime.

What security policies govern agent behavior when using the toolkit?

Agent behavior is governed by the policies defined in rules/aws-agent-rules.md, which provides recommended constraints for safe AWS usage. Additionally, the AWS MCP Server implements scoped permissions based on your AWS credentials, and the DevSecOps plugin (aws-agents-for-devsecops) includes specific skills for vulnerability scanning and security incident investigation to ensure agents operate within secure boundaries.

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