How to Wire Claude Code to AWS With Real-Time Docs

Three things are required, in this order:

1. An AWS account with IAM credentials configured on your local machine. If you only want documentation lookups (no API calls, no resource changes), credentials are technically optional — but you will hit the limit of usefulness within minutes. Get credentials.
2. uv installed locally. The toolkit talks to the AWS MCP Server through a SigV4 signing proxy called mcp-proxy-for-aws, which runs under uvx. No separate install of the proxy is required — uvx downloads the latest version each time your client starts.
3. An MCP-compatible AI coding agent. Claude Code, Codex, Cursor, Kiro, Claude Desktop, Windsurf, and Cline all qualify.

On macOS or Linux:

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

On Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Verify the install with uv --version. You will not call uv directly during normal use — your MCP client invokes uvx under the hood.

Three supported methods, in order of recommendation:

1. aws login (recommended for AWS Management Console users, requires AWS CLI v2.32.0 or later). Auto-rotates credentials every 15 minutes. Session valid up to 12 hours.

aws login

1. aws configure sso (recommended for SSO users). Auto-renews via cached refresh tokens. Default session is 1 hour; admins can extend up to 12 hours in IAM Identity Center.

aws configure sso

1. aws configure (IAM users with static keys — not recommended). Static keys do not auto-renew, and AWS recommends rotating them every 90 days.

aws configure

Whichever you pick, verify it works:

aws sts get-caller-identity

You should see your account ID, user/role ARN, and user ID. If this fails, fix it before continuing — every other step depends on it.

If you previously installed aws-api-mcp-server or aws-knowledge-mcp-server, remove them first. Running them alongside the new AWS MCP Server creates duplicate tools that confuse the agent and degrade performance.

Open your MCP client config file and delete any entries for those two servers. Save and restart the client.

Inside Claude Code, run:

/plugin marketplace add aws/agent-toolkit-for-aws
/plugin install aws-core@agent-toolkit-for-aws
/reload-plugins

The aws-core plugin bundles the AWS MCP Server config and a curated set of skills covering service selection, infrastructure-as-code (CDK and CloudFormation), serverless, containers, storage, observability, billing, SDK usage, and deployment.

For specialized work, you can layer additional plugins on top:

• aws-agents — building AI agents on AWS with API Gateway and Bedrock AgentCore
• aws-data-analytics — data lake, analytics, and ETL workflows

Install them the same way: /plugin install aws-agents@agent-toolkit-for-aws.

In your terminal:

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

Then launch Codex and run /plugins to browse and install aws-core.

The AWS MCP Server has two endpoint regions. Pick the one closer to you:

• US East (N. Virginia) — https://aws-mcp.us-east-1.api.aws/mcp
• Europe (Frankfurt) — https://aws-mcp.eu-central-1.api.aws/mcp

The endpoint region determines latency on documentation lookups. The AWS_REGION metadata parameter sets the default region for the AWS operations the agent performs. They can be different — connect to us-east-1 and operate on resources in us-west-2. Without the metadata parameter, operations default to us-east-1.

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

[mcp_servers.aws_mcp]
command = "uvx"
args = [
  "mcp-proxy-for-aws@latest",
  "https://aws-mcp.us-east-1.api.aws/mcp",
  "--metadata", "AWS_REGION=us-west-2"
]
startup_timeout_sec = 60

{
  "mcpServers": {
    "aws-mcp": {
      "command": "uvx",
      "timeout": 100000,
      "transport": "stdio",
      "args": [
        "mcp-proxy-for-aws@latest",
        "https://aws-mcp.us-east-1.api.aws/mcp",
        "--metadata", "AWS_REGION=us-west-2"
      ]
    }
  }
}

After configuring, restart the client.

This is the part that matters most for production teams.

The AWS MCP Server does not require separate IAM permissions to invoke the server itself. Authorization happens at the AWS service level using the same IAM roles and policies you already have. When the agent calls a service, the service authorizes the request exactly as it would for a direct API call.

What is new is that two global condition context keys are automatically added to every request made through the MCP server:

• aws:ViaAWSMCPService — boolean, set to true for any request that passes through any AWS-managed MCP server.
• aws:CalledViaAWSMCP — string, contains the service principal of the specific MCP server (for example, aws-mcp.amazonaws.com).

You can use these in IAM policies and Service Control Policies to distinguish agent-initiated actions from human-initiated actions on the same role. That is the unlock — your developer's IAM identity stays the same, but a policy condition can refuse mutations when the call originated from MCP.

The most useful pattern for team rollout is: let the agent read everything you can read, but block all mutations. Attach a deny statement keyed on aws:ViaAWSMCPService to the developer role.

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DenyAllMutationsViaMCP",
      "Effect": "Deny",
      "Action": [
        "s3:PutObject",
        "s3:DeleteObject",
        "s3:DeleteBucket",
        "ec2:RunInstances",
        "ec2:TerminateInstances",
        "iam:CreateUser",
        "iam:DeleteUser",
        "iam:CreateRole",
        "iam:DeleteRole",
        "iam:AttachRolePolicy",
        "iam:PutRolePolicy"
      ],
      "Resource": "*",
      "Condition": {
        "Bool": {
          "aws:ViaAWSMCPService": "true"
        }
      }
    }
  ]
}

Adapt the Action list to the surface area you want to lock down. For a more aggressive lock, use "Action": "" to deny every* write through MCP and explicitly allow back the ones you want.

If your account talks to multiple AWS-managed MCP servers in the future and you only want to lock down one, scope on aws:CalledViaAWSMCP:

{
  "Effect": "Deny",
  "Action": ["s3:DeleteBucket", "s3:DeleteObject"],
  "Resource": "*",
  "Condition": {
    "StringEquals": {
      "aws:CalledViaAWSMCP": "aws-mcp.amazonaws.com"
    }
  }
}

If you previously configured permissions using aws-mcp:InvokeMcp, aws-mcp:CallReadOnlyTool, or aws-mcp:CallReadWriteTool, remove those permissions — they no longer have any effect. If you used them to deny access, you must replace them with the new aws:ViaAWSMCPService / aws:CalledViaAWSMCP condition keys above.

Restart your MCP client. Wait a minute or two for the proxy to download and the server to initialize on first connection.

Then ask the agent a simple question:

What AWS Regions are available?

If the agent returns a real list of regions, the connection is working. If it returns a generic answer or claims it cannot reach AWS, the MCP server is not connected — check your AWS credentials and the client logs.

In Kiro CLI, you can also list installed MCP servers and tools:

/mcp
/tools

You should see tools named aws___search_documentation and aws___retrieve_skill (and others) listed.

If you applied the deny policy from Lesson 9, verify it works:

List my S3 buckets. — should succeed

>

Delete the bucket named test-bucket-12345. — should fail with an AccessDenied error

If both behave as expected, your guardrail is live.

AWS has not publicly documented specific concurrent-connection or per-second rate limits for the AWS MCP Server in its official launch documentation as of May 2026. The launch announcement and toolkit docs describe IAM-based access controls and CloudWatch metrics for monitoring, but no published numbers. Treat any quota figure circulating from launch coverage as directional, not contractual, until AWS documents it officially.

Practical implication for team rollout:

1. Before rolling out beyond a small pilot, build a CloudWatch dashboard for the AWS MCP Server's metrics (visible under the AWS/MCP namespace once you have traffic flowing).
2. Watch for elevated latency on aws___search_documentation and aws___retrieve_skill tool calls — those are the highest-volume calls and the first place throttling will surface.
3. If you start seeing sustained throttling errors as the team grows, file a quota increase request through AWS Support — but expect AWS to publish formal quotas via Service Quotas before that path matures.
4. Underlying AWS service quotas still apply per-call. For example, CloudTrail's LookupEvents is rate-limited at two requests per second per account per region — the MCP Server does not exempt you from those.

The point: do not assume infinite throughput just because no quota is documented. Watch the metrics, and pace your rollout to your observed headroom.

Start narrow, widen later:

1. Day 1. Install for a single pilot developer. Apply the read-only-through-MCP deny policy at the IAM role level. Have them use the agent for documentation lookup, service selection guidance, and read-only troubleshooting (CloudWatch logs, CloudFormation stack status).
2. Week 1. Roll out to the broader team with the same read-only restriction. Watch CloudTrail logs filtered by the new aws:CalledViaAWSMCP condition to see what the team is actually using the agent for.
3. Week 2 onward. Loosen specific actions where the team has demonstrated clear, repeated value — for example, allow cloudformation:CreateChangeSet (preview only, no apply) once developers are comfortable. Keep destructive actions (s3:DeleteBucket, iam:DeleteRole, ec2:TerminateInstances) denied through MCP indefinitely unless there is an explicit case for unlocking them.
4. Audit continuously. CloudTrail logs every agent action with the developer's IAM identity attached, plus the new MCP condition keys. Build a CloudWatch dashboard or run periodic queries against the CloudTrail logs to monitor agent behavior and catch unexpected patterns.

The point is: you can roll out the toolkit without granting any new permissions. The agent operates inside whatever box you already trust the developer to operate inside, and you can shrink that box specifically for agent-initiated calls without touching the developer's normal access.

The single most common failure: expired credentials.

| Error | Cause | Fix |

| --- | --- | --- |

| ExpiredTokenException | Session token expired (default 1 hour for SSO) | Refresh credentials via aws login or aws configure sso, then restart your MCP client |

| UnrecognizedClientException | Credentials revoked, malformed, or from a deleted IAM user | Verify with aws sts get-caller-identity, regenerate if needed |

| InvalidSignatureException | SigV4 signature mismatch — usually clock skew | Sync your system clock, then retry |

| No AWS credentials found | Credentials never configured | Go back to Lesson 3 |

If your agent stops using AWS tools mid-session, expired credentials are the first thing to check. The MCP server is not initialized again until your client restarts with valid credentials.

Static IAM access keys are the worst experience because they do not auto-renew. aws login and aws configure sso both renew silently in the background. If your team is hitting credential expiry every hour, that is the fix — not "increase the session length manually."

If the agent is answering AWS questions from its training data instead of calling MCP tools, two likely causes:

1. The MCP server failed to initialize. Check your client's MCP server status panel or logs. Restart the client.
2. Skills are not loaded. For Cursor/Claude Desktop/Kiro setups (no plugin), you also need to install skills separately:

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

The plugin install in Claude Code and Codex bundles skills automatically, so this step is only for manual configurations.

Recap

You should now have:

• The AWS Agent Toolkit installed in your AI coding agent
• Working AWS credentials with auto-renewal
• An IAM deny policy that restricts agent mutations through MCP
• A team rollout plan that starts read-only and widens deliberately
• A verification flow that confirms the connection works

The two-region MCP server (us-east-1, eu-central-1) is currently the only operational footprint to be aware of — the agent can still operate on resources in any region, just through one of those two endpoints.

For the broader context of why AWS shipped this and what problems it solves, see our news explainer.