# How to Set Up a Development Environment for the AWS Agent Toolkit

> Set up your AWS Agent Toolkit development environment easily. Install uv, configure MCP, add plugins, and authenticate for secure AWS interactions. Get started now.

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

---

**Install uv, run the MCP server with uvx, configure your AI agent's MCP settings, install the appropriate plugin, and authenticate with the aws-login skill to enable safe AWS interactions.**

The AWS Agent Toolkit (`aws/agent-toolkit-for-aws`) is an open-source collection of plugins, skills, and an AWS MCP Server that enables AI coding agents like Claude Code, Codex, and Cursor to interact with AWS services securely. Setting up a development environment involves three layers: installing the local toolchain, configuring agent-specific plugins, and bootstrapping temporary credentials. This guide walks you through the exact steps and configuration files needed to get started.

## Prerequisites and Core Components

A complete development environment consists of three integrated layers:

- **Local toolchain** – The `uv` Python package manager and `mcp-proxy-for-aws` to run the MCP server locally.
- **Agent-specific plugins** – Curated packages such as `aws-core` for Claude Code or `aws-agents-for-devsecops` for Codex, which bundle MCP configurations and skills.
- **Credential bootstrap** – The `aws-login` skill located in [`plugins/aws-core/skills/signing-in-to-aws/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/signing-in-to-aws/SKILL.md) supplies short-lived credentials for AWS calls.

## Step-by-Step Installation Guide

### Install uv and the MCP Server

First, install `uv`, the fast, deterministic Python installer required to fetch and run the AWS MCP proxy:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh

```

Launch the MCP server by running `uvx mcp-proxy-for-aws` with a pinned version to avoid supply-chain drift. According to the repository's [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md), the command connects to the AWS MCP endpoint and accepts region metadata:

```bash
uvx 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 the default AWS region; adjust `us-west-2` to match your target environment.

### Configure Your AI Agent

Each agent reads the MCP server configuration differently.

**For Kiro**, create the file `~/.kiro/settings/mcp.json` with the following stanza:

```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"
      ]
    }
  }
}

```

**For Cursor**, open **Settings → Plugins → Team Marketplaces**, click **Add Marketplace → Import from Repo**, and point it at `aws/agent-toolkit-for-aws`. Cursor reads the [`.cursor-plugin/marketplace.json`](https://github.com/aws/agent-toolkit-for-aws/blob/main/.cursor-plugin/marketplace.json) file to discover available plugins. Then install **aws-core** (or your preferred plugin) from the Plugins panel.

**For Claude Code**, install the plugin directly via the CLI:

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

```

If the marketplace index is stale, update it first:

```text
/plugin marketplace update claude-plugins-official

```

### Install Plugins and Skill Sets

Load the repository’s skill catalog using the generic `npx skills add` command, which works across all supported agents:

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

```

This makes the skill sets defined in the repository discoverable by your agent, including development-only tools like `sam deploy` and `cdk deploy` referenced in [`plugins/aws-core/skills/aws-serverless/references/deployment.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/aws-serverless/references/deployment.md).

### Authenticate with AWS

Trigger the sign-in skill to obtain short-lived, auto-rotating credentials. In the agent UI, run:

```text
/aws-core:login

```

Alternatively, for the AWS Agents plugin, use:

```text
/aws-agents:login

```

As documented in [`plugins/aws-core/skills/signing-in-to-aws/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/signing-in-to-aws/SKILL.md), this skill executes `aws login` under the hood, returning credentials that refresh every 15 minutes and remain valid for up to 12 hours.

## Verify Your Development Environment

Confirm the setup by executing a simple AWS CLI call through your agent:

```text
aws s3 ls

```

If the MCP server is reachable and credentials are valid, the agent returns a list of your S3 buckets. You can also test deployment capabilities by prompting the agent to run `/aws-serverless:deploy`, which generates a CloudFormation template and executes `sam deploy` using the development-only tooling sandbox.

## Summary

- **Install uv** to manage Python packages and run `uvx mcp-proxy-for-aws@<version>` to start the local MCP server.
- **Configure the MCP endpoint** in your agent’s settings (e.g., `~/.kiro/settings/mcp.json` for Kiro or the Cursor marketplace import).
- **Install the appropriate plugin** (`aws-core`, `aws-agents`, etc.) via `/plugin install` or the Cursor Plugins panel.
- **Add skills** with `npx skills add aws/agent-toolkit-for-aws/skills` to load the repository’s curated tool catalog.
- **Authenticate** using `/aws-core:login` to obtain temporary credentials that auto-rotate every 15 minutes.
- **Verify** by running AWS CLI commands or deployment skills through the agent interface.

## Frequently Asked Questions

### What is uv and why is it required for the AWS Agent Toolkit?

**uv** is a fast, deterministic Python package manager and installer. The AWS Agent Toolkit uses it to fetch and execute `mcp-proxy-for-aws`, which provides the authenticated endpoint that agents use to call any AWS API. According to the repository's [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md), `uv` ensures consistent, reproducible installations across development machines.

### How do I pin the MCP server version to avoid supply-chain drift?

Append the version number to the `uvx` command, such as `uvx mcp-proxy-for-aws@1.6.3`. This pins the dependency to a known release, preventing automatic updates that could introduce breaking changes. The version pinning is demonstrated in the Kiro configuration example within the repository's [`README.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/README.md).

### Which plugin should I install for my specific AI agent?

Install `aws-core` for Claude Code, `aws-agents-for-devsecops` for Codex, or the specific plugin listed in your agent’s marketplace. The `aws-core` plugin bundles the MCP configuration and the signing-in skill located at [`plugins/aws-core/skills/signing-in-to-aws/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/signing-in-to-aws/SKILL.md), while other plugins like `aws-agents` provide specialized DevSecOps workflows.

### How long do the AWS credentials remain valid?

The credentials obtained via the `aws-login` skill are short-lived and auto-rotating. As implemented in [`plugins/aws-core/skills/signing-in-to-aws/SKILL.md`](https://github.com/aws/agent-toolkit-for-aws/blob/main/plugins/aws-core/skills/signing-in-to-aws/SKILL.md), they refresh every 15 minutes and remain valid for up to 12 hours, ensuring secure, temporary access for development operations without long-lived keys.