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

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

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, the command connects to the AWS MCP endpoint and accepts region metadata:

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:

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

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

If the marketplace index is stale, update it first:

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

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.

Authenticate with AWS

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

/aws-core:login

Alternatively, for the AWS Agents plugin, use:

/aws-agents:login

As documented in 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:

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, 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.

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, 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, they refresh every 15 minutes and remain valid for up to 12 hours, ensuring secure, temporary access for development operations without long-lived keys.

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