/aws-profile

name: aws-profile
description: AWS profile management for MCP servers — discover profiles across SSO, Granted, and assumed-role chains, check credential TTL, switch profiles across VS Code and Claude Code MCP configs, and scan AWS Organization accounts.
argument-hint: "[discover|status|switch <profile>|login <profile>|org-scan] [flags]"
title: "AWS Profile Command"
sidebar_label: "aws-profile"
custom_edit_url: null

Manage AWS profiles for MCP server configurations across VS Code (GitHub Copilot) and Claude Code.

Reference: `references/aws-mcp-profiles.md`

---

Interactive Wizard (fires when no mode is provided)

When invoked with no arguments, ask before proceeding:

**Q1 — Mode?**

What do you need?
  1. discover  — list all AWS profiles with type, account ID, env tag, and credential TTL
  2. status    — show which profile each MCP server is using and whether credentials are fresh
  3. switch    — update MCP config files to use a different profile
  4. login     — authenticate and refresh credentials for a specific profile
  5. org-scan  — list all AWS Organization accounts and cross-reference with configured profiles

Enter 1–5 or mode name:

**Q2 — Mode-specific follow-up** (one question, after mode is selected):

• **discover**: `Any filters? (e.g. --expired to show only expired, --type sso, --env prod) — or press enter to list all:`
• **switch**: Read `~/.aws/config` and list available profiles, then ask: `Which profile should MCP servers switch to?`
• **login**: Read `~/.aws/config` and list available profiles, then ask: `Which profile needs authentication?`
• **status**: no follow-up — proceed directly
• **org-scan**: `Which management account profile has organizations:ListAccounts permission? (default: current profile):`

Then proceed into the relevant mode below.

---

Mode: discover

Parse `~/.aws/config` and output a classified profile table with credential TTL.

aws-profile discover [--type sso|assume-role|granted|static] [--env prod|staging|dev] [--account <id>] [--chain] [--expired]

**Output:**

Profile               Type         Account ID    Env Tag    Permission Set    Expires      TTL
prod-platform-eu      sso          123456789     prod       PowerUser         14:32 UTC    47m ✓
staging-assume        assume-role  456789123     staging    -                 13:58 UTC    13m ⚠
dev-sandbox           granted      987654321     dev        Developer         09:00 UTC    EXPIRED ✗
security              static       890123456     -          -                 never        ⚠ rotate

**Steps:**

1. Parse `~/.aws/config` — classify each `[profile name]` block by type:

• SSO: `sso_start_url` present
• Assumed role: `role_arn` + `source_profile`
• Granted: `granted_sso_*` keys or `assume` binary in PATH
• Static: `aws_access_key_id` directly in profile block → warn to rotate

2. Parse credential cache files for expiration timestamps. Field names differ by type:

• SSO (`~/.aws/sso/cache/*.json`): top-level `expiresAt`
• Assumed role (`~/.aws/cli/cache/*.json`): `Credentials.Expiration`
• Granted: no separate cache — SSO-backed profiles use `~/.aws/sso/cache/*.json` (`expiresAt`); role-chained profiles use `~/.aws/cli/cache/*.json` (`Credentials.Expiration`)

Apply traffic-light TTL:

• ✓ Green: >30 min
• ⚠ Amber: 10–30 min
• ✗ Red: <10 min or expired

3. Read `~/.aws-profile-tags.yaml` for env tags. If the file does not exist, generate a starter file:

   # ~/.aws-profile-tags.yaml — edit to correct heuristic guesses
   prod-platform-eu: prod    # detected: name contains 'prod'
   staging-assume: staging   # detected: name contains 'stag'
   dev-sandbox: dev          # detected: name contains 'dev'
   security: shared-services # detected: name contains 'security'

Print: `Generated ~/.aws-profile-tags.yaml — review and correct environment tags.`

4. Apply filters if flags provided.

**With `--chain`** — show full role assumption chain for assumed-role profiles:

staging-assume role chain:
  dev-sso (identity: 111111111)
    └── assume → security-role (222222222)
        └── assume → staging-platform (456789123)  ← this profile

Parse the chain by following `source_profile` → `role_arn` links recursively in `~/.aws/config`.

Reference: `references/aws-mcp-profiles.md` → Profile Type Detection, Credential Lifecycle

---

Mode: status

Show which profile each configured MCP server uses, the credential TTL, and whether the credential method will auto-refresh.

**Note:** `status` reads config files and `~/.aws/sso/cache/` — it does not read the `AWS_PROFILE` shell environment variable, which is per-session and invisible to this command.

aws-profile status [--watch] [--all-hosts]

**Output:**

Profile in MCP configs: prod-platform-eu
  Type: SSO | Account: 123456789 | Permission: PowerUser
  Token expires: 14:32 UTC (47 minutes) ✓

MCP Servers:
  eks-prod-eu      ~/.vscode/mcp.json          credential_process ✓   47m
  cloudwatch       ~/.claude/settings.json      AWS_PROFILE ⚠         47m (will not auto-refresh on expiry)
  eks-prod-us      .vscode/mcp.json            credential_process ✓   47m

⚠ 'cloudwatch' uses raw AWS_PROFILE without credential_process.
  When the token expires, this server will fail silently.
  Fix: add credential_process to the 'prod-platform-eu' profile in ~/.aws/config.
  See: references/aws-mcp-profiles.md → credential_process Pattern

**Steps:**

1. Scan `~/.vscode/mcp.json`, `~/.claude/settings.json`, and `.vscode/mcp.json` (if present in cwd). Extract `AWS_PROFILE` from each server's `env` block. 2. For each unique profile found, parse TTL from `~/.aws/sso/cache/` or `~/.aws/cli/cache/`. 3. Check whether the profile in `~/.aws/config` has `credential_process` configured. Flag servers without it as ⚠. 4. If `--watch`: re-run every 60 seconds. Print a warning when any TTL drops below 30 minutes, and a loud alert when any TTL drops below 10 minutes.