How to Use the AWS Agent Toolkit for AWS: Complete Setup Guide

The AWS Agent Toolkit for AWS enables AI coding agents to authenticate with your AWS credentials and invoke over 300 APIs through a unified MCP Server, distributed via plugins for Claude Code, Codex, Cursor, and Kiro.

The aws/agent-toolkit-for-aws repository packages AWS service integration into reusable plugins and skills that transform generic AI agents into AWS-capable assistants. Instead of manually configuring API clients, you install agent-specific plugins that bundle the AWS MCP Server—a proxy that securely exposes AWS APIs through a single endpoint.

Supported AI Agents and Prerequisites

The toolkit officially supports Claude Code, Codex, Cursor, and Kiro. Each agent consumes the toolkit differently: Claude Code and Codex use plugin marketplaces, Cursor uses Team Marketplaces, and Kiro relies on direct MCP configuration files.

According to the repository's [README.md](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md), your environment must have:

• Valid AWS credentials configured (via IAM roles or access keys)
• Node.js and npx available for skill installation
• uvx installed for running the MCP proxy server

Configuring the AWS MCP Server

The AWS MCP Server handles authentication and API routing. It runs as a local proxy that connects to https://aws-mcp.us-east-1.api.aws/mcp and requires your AWS region metadata.

Create the configuration file specific to your agent's MCP settings. For Kiro, place this in ~/.kiro/settings/mcp.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"
      ]
    }
  }
}

The --metadata flag injects your target region into every request, ensuring API calls route to the correct AWS endpoint.

Installing the AWS Agent Toolkit by Platform

Each AI agent has a distinct installation path documented in the repository's quick-start sections.

Claude Code

Claude Code users install plugins through the built-in marketplace. The aws-core plugin is the recommended starting point.

# Install the core plugin

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

# Refresh the marketplace index if commands fail

/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 workflow.

Codex

For Codex, add the repository to your plugin sources, then install via the UI:

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

After adding the source, run /plugins in the Codex interface and select the desired plugin from the list.

Cursor

Cursor requires adding the repository as a Team Marketplace:

1. Navigate to Settings → Plugins → Team Marketplaces
2. Add aws/agent-toolkit-for-aws
3. Install plugins from the Plugins panel

This method references the plugin definitions stored in [plugins/aws-core/README.md](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-core) and sibling directories.

Kiro

Kiro combines MCP server configuration with skill installation. After creating the mcp.json file above, install the skills package:

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

This command download skills defined in [skills/README.md](https://github.com/aws/agent-toolkit-for-aws/blob/main/skills/README.md) and makes them available to the agent.

Other Agents

For unsupported agents, manually configure the MCP server JSON (as shown in the Kiro section) and run the universal skill installer:

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

Refer to the Getting Started guide in the root README.md for credential setup details.

Available Plugins and Skill Categories

The repository organizes capabilities into four primary plugins, each documented in dedicated subdirectories:

• aws-core — Covers service selection, CDK/CloudFormation, serverless architectures, containers, observability, billing, and SDK usage. Defined in [plugins/aws-core/README.md](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-core).
• aws-agents — Skills for building AI agents using Amazon Bedrock and AgentCore.
• aws-data-analytics — Data lake workflows, Glue jobs, Athena queries, and vector-search implementations.
• aws-agents-for-devsecops — Security-focused capabilities including incident investigation, automated code review, vulnerability scanning, and penetration testing. Detailed in [plugins/aws-agents-for-devsecops/README.md](https://github.com/aws/agent-toolkit-for-aws/tree/main/plugins/aws-agents-for-devsecops).

Each plugin bundles the MCP server configuration and a curated set of skills that follow the policy guidelines in [rules/aws-agent-rules.md](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md).

Complete Installation Workflow

The following bash script demonstrates a full setup for a Kiro-based environment, which serves as the reference implementation for custom agents:

# Step 1: Create MCP configuration directory

mkdir -p ~/.kiro/settings

# Step 2: Write the AWS MCP Server configuration

cat > ~/.kiro/settings/mcp.json <<'EOF'
{
  "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"
      ]
    }
  }
}
EOF

# Step 3: Install all AWS skills from the repository

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

# Step 4: Verify installation (check that the agent recognizes AWS tools)

echo "AWS Agent Toolkit installed. Restart your AI agent to load the MCP server."

For Claude Code, replace steps 1-2 with the /plugin install command shown in the previous section.

Summary

• The AWS Agent Toolkit for AWS bridges AI agents to AWS services through a centralized MCP Server.
• Install aws-core first for general infrastructure tasks, or choose specialized plugins for data analytics or DevSecOps.
• Configure the MCP server with your AWS region metadata using uvx and the proxy endpoint.
• Claude Code, Codex, and Cursor use marketplace-based installation; Kiro and custom agents use mcp.json configuration plus npx skills add.

Frequently Asked Questions

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

The toolkit officially supports Claude Code, Codex, Cursor, and Kiro. Each receives specific installation instructions in the repository's README.md. Other agents can use the toolkit by manually configuring the AWS MCP Server and running the universal npx skills add command.

How does the AWS MCP Server authenticate with AWS services?

The MCP Server uses your existing AWS credentials from the environment (such as ~/.aws/credentials or IAM roles) to sign requests. It acts as a local proxy that forwards authenticated calls to https://aws-mcp.us-east-1.api.aws/mcp, exposing over 300 AWS APIs without storing your keys.

What is the difference between plugins and skills in the AWS Agent Toolkit?

Plugins are agent-specific distribution packages that bundle the MCP server configuration and a collection of skills. Skills are individual capability units (such as "deploy CDK stack" or "query Athena") defined in the skills/ directory. Plugins install the infrastructure; skills provide the tool definitions the agent invokes.

Where can I find security policies for safe AWS usage with AI agents?

The repository includes recommended guardrails in [rules/aws-agent-rules.md](https://github.com/aws/agent-toolkit-for-aws/blob/main/rules/aws-agent-rules.md). This file contains policy files that guide agents on safe AWS usage, including restrictions on destructive operations and requirements for manual approval of high-risk changes.

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