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

> Learn to build AI coding agents with the AWS Agent Toolkit. Securely interact with AWS services using plugins and expose 300+ APIs via a single authenticated endpoint. Get the complete setup guide.

- Repository: [Amazon Web Services/agent-toolkit-for-aws](https://github.com/aws/agent-toolkit-for-aws)
- Tags: getting-started
- Published: 2026-06-28

---

**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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/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:

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

```

To refresh the available plugin list, run:

```bash
/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:

```bash
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:

```json
{
  "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:

```bash
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:

```bash
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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md) files under the `plugins/` directory:

- **`aws-core`** – Found in [`plugins/aws-core/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md) | High-level overview, quick-start instructions, and agent-specific installation commands |
| [`plugins/aws-core/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/README.md) | Detailed documentation for the core plugin and its bundled skills |
| [`plugins/aws-agents-for-devsecops/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-agents-for-devsecops/README.md) | DevSecOps-specific skills and security workflows |
| [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md) | Recommended policy files that constrain agent behavior to safe AWS usage patterns |
| [`skills/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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](https://docs.aws.amazon.com/agent-toolkit/latest/userguide/) 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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/README.md), [`rules/aws-agent-rules.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md), and [`skills/README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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`](https://github.com/aws/agent-toolkit-for-aws/blob/main/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.