How to Set Up Amazon Q Developer(Kiro) with the Amazon ECS MCP Server for Deployment and Troubleshooting

Amazon ECS MCP Server changes this workflow by giving AI assistants access to contextual information about your ECS environment through the Model Context Protocol (MCP). When connected to Amazon Q Developer, you can investigate ECS deployments and troubleshoot failures using natural-language questions directly from your development environment.

Aman Patel

DevOps Engineer | AWS & Cloud Infrastructure Specialist | Kubernetes | CI/CD | Automation Expert

Published Aug 13, 2026

Last modified Aug 13, 2026

Prerequisites

Before starting, you'll need:

An AWS account
An Amazon ECS cluster and service
AWS CLI
Python 3.10+
uv
Amazon Q Developer
An AWS CLI profile with access to the ECS environment

AWS's ECS MCP getting-started documentation lists Python 3.10+, uv, and a configured AWS CLI as prerequisites.

You can verify your environment:

1
2
3
python3 --version
uv --version
aws configure list

On Windows, you can use:

1
2
3
python --version
uv --version
aws configure list

Make sure the AWS profile you intend to use points to the correct AWS account and region.

Install Amazon Q Developer CLI on macOS and Linux

For this ECS MCP hands-on lab, we'll use the Kiro CLI, the current command-line successor to the Amazon Q Developer CLI.

The CLI runs directly from your terminal and supports MCP integrations, making it suitable for connecting an AI coding assistant to the Amazon ECS MCP Server.

1. Install on macOS

Open Terminal and run:

1
curl -fsSL https://cli.kiro.dev/install | bash

This is the official Kiro CLI installation command for macOS and Linux.

After installation, restart your terminal or reload your shell:

1
source ~/.zshrc

Then verify the installation:

1
kiro-cli --version

You should get output similar to:

1
kiro-cli 1.x.x

You can also check where the binary was installed:

1
which kiro-cli

For example:

1
/Users/<username>/.local/bin/kiro-cli

Apple Silicon vs Intel

You don't need to manually choose a separate installer when using the official installation command.

Check your Mac architecture with:

1
uname -m

Apple Silicon:

1
arm64

Intel:

1
x86_64

The installer handles the appropriate CLI installation.

2. Install on Linux

The easiest approach is also the official installation command:

1
curl -fsSL https://cli.kiro.dev/install | bash

Reload your shell:

1
source ~/.bashrc

Then verify:

1
kiro-cli --version

Check the executable:

1
which kiro-cli

Ubuntu/Debian Alternative

For Ubuntu, AWS/Kiro also provides a .deb package.

Download it:

1
wget https://desktop-release.q.us-east-1.amazonaws.com/latest/kiro-cli.deb

Install it:

1
sudo dpkg -i kiro-cli.deb

If dependencies are required:

1
sudo apt-get install -f

Then:

1
kiro-cli --version

Kiro documents the .deb installation method for Ubuntu.

3. Start Kiro CLI

Once installed, run:

1
kiro-cli

You can also start directly in your project directory:

1
2
cd ~/projects/my-ecs-app
kiro-cli

Kiro CLI will start an interactive terminal session.

4. Login with AWS Builder ID

For an individual hands-on lab, AWS Builder ID is the simplest authentication method.

Run:

1
kiro-cli login

The CLI will start the authentication process.

On a normal local machine, it will open your browser. The current Kiro CLI authentication flow supports:

AWS Builder ID
IAM Identity Center
Google
GitHub
Organization identity providers

Select:

1
AWS Builder ID

Then complete the login in your browser.

After successful authentication, return to the terminal.

5. Verify the Login

Run:

1
kiro-cli whoami

You should see information indicating that you're logged in with Builder ID.

For example:

1
2
3
4
Logged in with Builder ID

Profile:
builder-id-username

The whoami command is the recommended way to check the current authentication state.

You can also get JSON output:

1
kiro-cli whoami --format json

or:

1
kiro-cli whoami --format json-pretty

6. Start an AI Chat

After logging in, start the CLI:

1
kiro-cli

Or from your project:

1
2
cd ~/projects/ecs-demo
kiro-cli

Then ask:

1
What is Amazon ECS?

Try an AWS troubleshooting question:

1
What are the common causes of an ECS deployment failure?

You should now be able to interact with the AI assistant directly from your terminal.

7. Remote Linux / EC2 / SSH Login

If you're installing the CLI on a remote Linux machine, such as an EC2 instance, SSH server, or development server, the browser may not be available on that machine.

Use device-flow authentication:

1
kiro-cli login --use-device-flow

The CLI will display a URL and a one-time code.

You'll see something similar to:

1
2
3
4
5
6
7
Open this URL in your browser:

https://...

Enter this code:

ABCD-EFGH

Open the URL on your local computer.

Enter the displayed code and complete the Builder ID authentication.

The CLI will automatically detect the successful authentication. Kiro documents device flow specifically for SSH and other remote environments.

8. Login with IAM Identity Center

If you're using an organization-managed Amazon Q/Kiro environment, use IAM Identity Center.

For example:

1
2
3
4
kiro-cli login \
  --license pro \
  --identity-provider https://my-org.awsapps.com/start \
  --region us-east-1

Replace:

1
https://my-org.awsapps.com/start

with the Start URL provided by your AWS administrator.

Replace:

1
us-east-1

with the AWS Region where your organization's IAM Identity Center directory is configured.

Kiro documents this as the enterprise authentication method.

9. Logout

To sign out:

1
kiro-cli logout

You can then log in again:

1
kiro-cli login

Kiro's logout command clears authentication credentials while preserving agent and MCP configuration.

10. Quick Verification

At this point, run:

1
kiro-cli --version

Then:

1
kiro-cli whoami

Then:

1
kiro-cli

Your setup should look like:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
┌──────────────────────────────┐
│       macOS / Linux          │
│                              │
│   kiro-cli                   │
│       │                      │
│       ├── Builder ID         │
│       │   or                 │
│       │   IAM Identity       │
│       │   Center             │
│       │                      │
│       └── MCP                │
│             │                │
│             ▼                │
│       ECS MCP Server         │
│             │                │
│             ▼                │
│       Amazon ECS             │
└──────────────────────────────┘

11. Important: Kiro Login Is Not AWS CLI Login

This is important for the ECS MCP lab.

Running:

1
kiro-cli login

authenticates you to the Kiro/Amazon Q experience.

It does not configure your AWS CLI credentials.

You should separately verify AWS access:

1
aws sts get-caller-identity

Or, if you're using a named profile:

1
aws sts get-caller-identity --profile ecs-dev

The two authentication mechanisms serve different purposes:

1
2
3
4
5
6
7
8
9
10
11
Kiro CLI
   │
   └── kiro-cli login
          │
          └── Authenticates AI assistant

AWS CLI
   │
   └── aws sts get-caller-identity
          │
          └── Authenticates AWS API access

We'll use the AWS CLI identity when configuring the ECS MCP connection.

12. Final Verification

Run these commands:

1
kiro-cli --version

1
kiro-cli whoami

1
aws --version

1
aws sts get-caller-identity

If all four commands work, your machine is ready for the next step.

The next step is to configure ECS MCP in Kiro CLI, for example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
Developer
    │
    ▼
kiro-cli
    │
    ▼
MCP configuration
    │
    ▼
mcp-proxy-for-aws
    │
    ▼
Amazon ECS MCP Server
    │
    ├── ECS deployments
    ├── ECS services
    ├── ECS tasks
    ├── Service events
    ├── CloudWatch logs
    ├── Network configuration
    └── Deployment troubleshooting

Step 13: Configure AWS Credentials

The ECS MCP Server needs to access your AWS resources through your AWS identity.

For example:

1
aws configure --profile ecs-dev

Then verify:

1
aws sts get-caller-identity --profile ecs-dev

You should see your AWS account and identity information.

For example:

1
2
3
4
5
{
    "UserId": "AIDXXXXXXXXXXXX",
    "Account": "123456789012",
    "Arn": "arn:aws:iam::123456789012:user/developer"
}

For production environments, prefer IAM roles, IAM Identity Center, or other short-lived credentials instead of storing long-lived access keys.

Step 14: Configure IAM Permissions

The ECS MCP Server requires permissions to retrieve information from your ECS environment.

AWS documents two approaches:

Use ReadOnlyAccess plus the MCP-specific permissions.
Create a granular custom policy containing only the required permissions.

The MCP-specific permissions include:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "MCPServerAccess",
      "Effect": "Allow",
      "Action": [
        "ecs-mcp:InvokeReadOnlyTools",
        "ecs-mcp:UseMcp"
      ],
      "Resource": "*"
    }
  ]
}

AWS also documents the underlying service permissions required by individual ECS MCP tools. For example, retrieving ECS service events requires ecs:DescribeServices, while fetching task logs also requires logs:FilterLogEvents.

For a troubleshooting-focused setup, start with read-only permissions.

This is important because an AI assistant should initially be able to inspect and diagnose your infrastructure without automatically modifying production resources.

Step 15: Configure the ECS MCP Server

Amazon Q Developer supports MCP servers through its MCP configuration.

For Q Developer in the IDE, MCP configuration can be managed through the Q interface or configuration files. AWS documents global and workspace-level configurations, including:

1
~/.aws/amazonq/default.json

and:

1
.amazonq/default.json

Legacy mcp.json configuration is also supported in applicable setups.

The Amazon ECS MCP Server is exposed through a regional endpoint such as:

1
https://ecs-mcp.us-west-2.api.aws/mcp

The ECS MCP documentation uses mcp-proxy-for-aws to provide the authenticated bridge to the managed ECS MCP endpoint.

For example, an MCP configuration can look like this:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "mcpServers": {
    "ecs-mcp": {
      "disabled": false,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://ecs-mcp.us-west-2.api.aws/mcp",
        "--service",
        "ecs-mcp",
        "--profile",
        "ecs-dev",
        "--region",
        "us-west-2"
      ]
    }
  }
}

Replace:

1
us-west-2

with your ECS region and:

1
ecs-dev

with your AWS CLI profile.

For Windows, AWS documents a Windows-specific uvx configuration using mcp-proxy-for-aws.exe.

Step 16: Verify the MCP Connection

Restart your IDE or Amazon Q session after configuring the server.

Amazon Q provides commands such as:

1
/tools

to inspect available tools. AWS also documents MCP configuration and status commands for the Q CLI.

You can start with a simple question:

1
List all ECS clusters in my AWS account.

If the connection is working, Amazon Q should be able to retrieve your ECS clusters.

Try:

1
Show me the services running in my production cluster.

You can then ask:

1
Show me the deployment status of my web-service in production.

At this point, Amazon Q is no longer answering only from general AWS knowledge. It can use the ECS MCP tools to retrieve information from your actual ECS environment.

# ai # kiro # kiro-agent # aws-ai-chips # mcp-integration

Any opinions in this article are those of the individual author and may not reflect the opinions of AWS.

Enjoyed reading this content? Let the author know!

Your likes, comments, shares, and saves help creators reach more builders.

Loading recommendations

Loading article

Builder Center

How to Set Up Amazon Q Developer(Kiro) with the Amazon ECS MCP Server for Deployment and Troubleshooting

Aman Patel

Prerequisites

1. Install on macOS

Apple Silicon vs Intel

2. Install on Linux

Ubuntu/Debian Alternative

3. Start Kiro CLI

4. Login with AWS Builder ID

5. Verify the Login

6. Start an AI Chat

7. Remote Linux / EC2 / SSH Login

8. Login with IAM Identity Center

9. Logout

10. Quick Verification

11. Important: Kiro Login Is Not AWS CLI Login

12. Final Verification

Step 13: Configure AWS Credentials

Step 14: Configure IAM Permissions

Step 15: Configure the ECS MCP Server

Step 16: Verify the MCP Connection