---
name: aws-mcp-server
description: How to use the AWS MCP Server effectively — the single authenticated endpoint that lets an agent run AWS CLI/API calls, execute sandboxed Python, search and read live AWS documentation, and retrieve skills. Use when configuring the AWS MCP Server, deciding between a scripted run and a direct call, paginating list operations, working across multiple regions or profiles, or writing IAM policies that scope what the agent may do (aws:ViaAWSMCPService and aws:CalledViaAWSMCP condition keys) with CloudWatch and CloudTrail visibility.
license: Apache-2.0
metadata:
  source: agent-toolkit-for-aws
---

# Using the AWS MCP Server

The AWS MCP Server is a managed, remote endpoint reached through a local stdio
proxy (`uvx mcp-proxy-for-aws@<version> https://aws-mcp.us-east-1.api.aws/mcp`).
This plugin's `mcp.json` registers it as the server named `aws-mcp`. It gives an
agent secure access to AWS through one authenticated tool surface, with
CloudWatch metrics and CloudTrail logging on every request.

## What it exposes

- **AWS API/CLI coverage** — interact with any of 300+ AWS services and 15,000+
  API actions through a single tool, with no local AWS CLI install required.
- **Sandboxed script execution** — write and run Python in an isolated
  environment (no local filesystem or network access) to orchestrate multi-step
  operations, transform data, and paginate. Prefer this for anything beyond a
  single call.
- **Live documentation** — search and read current AWS docs, user guides, and
  API references, so you handle services newer than your training cutoff.
- **Skill retrieval** — discover and load curated skills at runtime instead of
  pre-installing everything.

## Authentication model

- **Docs and skills work unauthenticated.** Documentation search and skill
  retrieval need no AWS credentials.
- **API calls need IAM credentials.** For anything that reads or mutates AWS
  resources, the user must have AWS credentials configured (e.g. `aws configure`
  or `aws sso login`) in their environment; the proxy signs requests with them.
  Never handle raw credential values yourself — reference profiles by name.
- Set the working region via the `--metadata AWS_REGION=<region>` argument in
  `mcp.json` (this plugin defaults to `us-west-2`), or per call.

## Working patterns

- **List then describe.** List operations return identifiers only. Follow up with
  describe/get calls for full detail; never infer state from names alone.
- **Always paginate.** If a response carries a pagination token, the results are
  incomplete — page through every page before reporting counts or conclusions.
- **Multi-region / multi-profile.** For "all regions" or multiple accounts, query
  each region and profile explicitly and aggregate; do not assume one region
  represents the account.
- **Prefer a script for multi-step work.** One sandboxed Python run that does
  list → filter → describe is cheaper and more reliable than many round-trips.

## Governing what agents can do

The server tags agent-initiated calls so you can govern them separately from
human actions:

- `aws:CalledViaAWSMCP` — true when a request came through the AWS MCP Server.
- `aws:ViaAWSMCPService` — use in IAM policies and SCPs to scope agent behavior.

Example policy intent: allow read-only actions through the MCP server even when
the underlying role can write, so an agent can *suggest* production changes but
not *execute* them. Pair this with CloudWatch metrics and CloudTrail logs to
monitor and audit agent activity.

## Version pinning

Pin the proxy to a specific version (e.g. `mcp-proxy-for-aws@1.6.3`) for
reproducible behavior, and check PyPI periodically for newer stable releases
before bumping.