mcp-aws-manager

AWS operations CLI + MCP stdio server (SSM-first).

This package orchestrates AWS operations (inventory/runtime/remediation) with a normalized output schema and ACTION_REQUIRED guidance. It is not a plain AWS CLI wrapper.

Agent-First Quick Start

Use this as the default flow for agent environments:

npm install -g mcp-aws-manager
mcp-aws-manager --version
mcp-aws-manager setup --force
mcp-aws-manager doctor

Agent Prompt Examples:

Ask in natural language like below; the agent should run fetch/analysis steps as needed.

Give me a fresh full AWS server status summary.

Then try requests like:

Compare current AWS server status with the previous check and show only what changed.

Summarize AWS server status with required actions and high-impact warnings in priority order.

What It Does

• Multi-service inventory: EC2, Lambda, ALB/NLB, ASG, RDS, ElastiCache, Route53, VPC/Subnet/SecurityGroup, ECS, S3, IAM, KMS, CloudWatch, CloudTrail, Config, Secrets Manager, ECR, DynamoDB, SNS, EventBridge, SQS, ACM, Kinesis, MSK, Budgets, Cost Anomaly, EBS, EFS, EKS, API Gateway (REST/v2), CloudFront, WAF, Shield, Step Functions, CloudWatch Logs, X-Ray, Inspector2, Redshift, OpenSearch, Organizations, ControlTower
• SSM state visibility: managed/online status
• Domain analysis pipeline: IaC drift, CI/CD signals, backup/DR posture, security posture, FinOps cost signals, application layer health, incident severity recommendation
• Optional runtime snapshot and SSM remediation
• Mutate surface extension: EC2 + ECS + ASG + RDS + EKS controlled change tools
• Policy-aware routing: mode/surface/schema-tier selection for safer defaults
• Multi-account scaling controls: Organizations AssumeRole fan-out + profile/region sharding
• Manual fallback mode: JSON/CSV server list + PEM SSH/ProxyJump/Bastion runtime snapshot (when AWS auth is unavailable)
• Human-in-the-loop retry flow via ACTION_REQUIRED
• Internal-only execution path (AWS SDK + AWS CLI)
• Presentation layer controls: output profile presets, section/field projection, and client-aware default layout
• Persistent governance log + topology/relationship JSON artifacts
• Optional incident escalation webhook dispatch with local incident payload artifact

When To Use This Project

Use mcp-aws-manager when you need an operations workflow MCP, not just generic AWS API access.

• Choose this project for deterministic inventory/runtime/remediation loops.
• Choose this project when ACTION_REQUIRED guidance and operator artifacts are required.
• For broad ad-hoc AWS API control only, an umbrella API-style AWS MCP may be enough.

See detailed comparison and product boundaries in:

• docs/MCP_DIFFERENTIATION.md

Quick Comparison

| Selection Point | mcp-aws-manager | Umbrella API-style AWS MCP | |---|---|---| | Primary goal | Deterministic operations workflow (inventory/runtime/remediation) | Broad ad-hoc API/tool access | | Tool exposure model | Fixed gateway 3-tool (capabilities_summary, capabilities_detail, gateway_execute) | Many direct service/action tools | | Change safety | Built-in confirmation/policy gates for mutate paths | Depends on each tool/server policy | | Response contract | Normalized (ok/summary/records/requiredActions/meta) | Varies by implementation | | Best fit | Reproducible ops loops with operator guidance | Exploratory or wide API probing |

For full rationale and boundaries, see docs/MCP_DIFFERENTIATION.md and docs/MCP_DIFFERENTIATION_KO.md.

API Coverage Snapshot

• AWS API total: no fixed official single number, but the action surface is on the order of tens of thousands across services (and continuously expanding).
• Current implementation scope is not "all AWS APIs".
• AWS SDK service clients used: 49
• AWS SDK operation calls used: 95
• AWS CLI commands used: 1 (aws sso login --profile <profile>)
• Note: enterprise controls (policy gate/rollback/governance verification) remain in place while inventory coverage has been expanded.

Current 95 AWS SDK operations:

• STS: GetCallerIdentity
• EC2: DescribeRegions, DescribeInstances, DescribeVpcs, DescribeSubnets, DescribeSecurityGroups, StartInstances, StopInstances, RebootInstances, DescribeIamInstanceProfileAssociations, AssociateIamInstanceProfile, ReplaceIamInstanceProfileAssociation
• SSM: DescribeInstanceInformation, DescribeParameters, SendCommand, GetCommandInvocation
• Lambda: ListFunctions
• ELBv2: DescribeLoadBalancers, DescribeTargetGroups
• Auto Scaling: DescribeAutoScalingGroups, SetDesiredCapacity
• RDS: DescribeDBInstances, StartDBInstance, StopDBInstance, RebootDBInstance
• ElastiCache: DescribeCacheClusters
• Route53: ListHostedZones, ListResourceRecordSets
• ECS: ListClusters, DescribeClusters, ListServices, DescribeServices, UpdateService
• S3: ListBuckets, GetBucketLocation
• IAM: ListRoles
• KMS: ListKeys, DescribeKey
• CloudWatch: DescribeAlarms
• CloudTrail: DescribeTrails
• AWS Config: DescribeConfigurationRecorders, DescribeConfigurationRecorderStatus, DescribeDeliveryChannels, DescribeConfigRules, DescribeComplianceByConfigRule
• Secrets Manager: ListSecrets
• ECR: DescribeRepositories
• DynamoDB: ListTables, DescribeTable
• SNS: ListTopics
• EventBridge: ListEventBuses
• SQS: ListQueues, GetQueueAttributes
• ACM: ListCertificates, DescribeCertificate
• Kinesis: ListStreams, DescribeStreamSummary
• MSK: ListClustersV2
• AWS Budgets: DescribeBudgets
• EBS: DescribeVolumes
• EFS: DescribeFileSystems
• EKS: ListClusters, DescribeCluster, DescribeNodegroup, UpdateNodegroupConfig
• API Gateway (REST): GetRestApis
• API Gateway v2: GetApis
• CloudFront: ListDistributions
• WAFv2: ListWebACLs
• Shield: ListProtections
• Step Functions: ListStateMachines
• CloudWatch Logs: DescribeLogGroups
• X-Ray: GetGroups
• Inspector2: ListFindings
• Redshift: DescribeClusters
• OpenSearch: ListDomainNames, DescribeDomain
• Organizations: ListAccounts
• ControlTower: ListLandingZones
• CloudFormation: DescribeStacks
• CodePipeline: ListPipelines, ListPipelineExecutions
• CodeBuild: ListProjects, ListBuildsForProject, BatchGetBuilds
• CodeDeploy: ListApplications, ListDeploymentGroups, ListDeployments, BatchGetDeployments
• AWS Backup: ListBackupPlans, ListProtectedResources
• SecurityHub: GetFindings
• GuardDuty: ListDetectors, ListFindings
• Cost Explorer: GetCostAndUsage, GetAnomalies, GetSavingsPlansUtilization, GetReservationCoverage

Binaries

• CLI: mcp-aws-manager
• MCP stdio server (single-entry; default: --surface all): mcp-aws-manager-mcp

mcp-aws-manager-mcp uses gateway routing with selectable surface scope:

mcp-aws-manager-mcp --surface all
mcp-aws-manager-mcp --surface readonly
mcp-aws-manager-mcp --surface mutate

Agent-Assisted First-Time Setup

Use this flow for new users.

1. Install and bootstrap:

npm.cmd install -g mcp-aws-manager@latest
mcp-aws-manager

Bootstrap registers the default single MCP server for detected clients:

• mcp-aws-manager (single-entry, --surface all)
• Runtime command is auto-resolved for host stability.
• Windows priority: absolute mcp-aws-manager-mcp.cmd
• macOS/Linux priority: absolute mcp-aws-manager-mcp binary
• Fallback: node <installed-package>/bin/mcp-aws-manager-mcp.js
• Last fallback (ephemeral npx context): pinned npx -y -p mcp-aws-manager@<version> mcp-aws-manager-mcp

Optional explicit registration:

mcp-aws-manager setup
mcp-aws-manager setup --clients cursor
mcp-aws-manager setup --clients codex
mcp-aws-manager setup --clients claude

Default behavior (setup/bootstrap without --clients) auto-detects installed clients and registers only detected CLIs.

Compatibility note:

• Cursor is registered through MCP config file sync (~/.cursor/mcp.json and platform user config path) to avoid editor tab side effects from cursor mcp ....
• Claude can be registered via config sync even when claude CLI is not in PATH, when a Claude config path (for example macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Linux ~/.config/Claude/claude_desktop_config.json, or ~/.claude/claude_desktop_config.json) or install footprint is detected. You can force the path with CLAUDE_MCP_CONFIG_PATH.
• If another editor-style client does not expose stable CLI mcp subcommands, setup/doctor returns manual configuration required instead of running unsafe subcommands.

2. Health check:

mcp-aws-manager doctor

Default behavior (doctor without --clients) auto-detects installed clients and skips non-installed CLIs.

3. Configure AWS auth (SSO recommended):

aws configure sso --profile default
aws sso login --profile default

4. Verify identity:

aws sts get-caller-identity --profile default

5. Run discovery:

mcp-aws-manager discover --profiles default --no-progress

If blocked, follow one ACTION_REQUIRED item, then retry the same command.

If AWS auth is not available, use manual fallback:

mcp-aws-manager discover --manual-server-list ./servers.csv --pem-paths C:\keys\prod.pem --no-progress

GUI report is generated by default (auto path: workspace/home aws-inventory.html):

mcp-aws-manager discover --profiles default --no-progress

GUI includes:

• summary cards (records/services/profiles/regions/EC2/SSM/public-IP/issues)
• tab view (Report, Diagrams, Evidence, Inventory)
• detailed markdown report (report.md) with per-resource-type sections
• topology diagram (Profile -> Region -> Type -> Resource)
• relationship diagram (DNS / TargetGroup-ALB / ASG heuristic links)
• focused server/resource selector with per-resource detail and focused relation diagram (focus.svg)
• evidence view and export (evidence.json)
• diagram export (diagram.drawio, topology.svg, relationship.svg)
• downloaded artifacts include generation timestamp in filename (for example report-20260304-113000.md)

Custom path / open behavior:

mcp-aws-manager discover --profiles default --html-out ./inventory.html --open-html --no-progress

By default, HTML open is enabled. Use --no-open-html to disable.

Manual MCP Client Configuration (Fallback)

Use this only when automatic bootstrap/setup registration is unavailable.

1. Local repository (development):

{
  "mcpServers": {
    "mcp-aws-manager": {
      "command": "node",
      "args": [
        "<repo>/bin/mcp-aws-manager-mcp.js",
        "--surface",
        "all"
      ],
      "cwd": "<repo>"
    }
  }
}

2. Global npm install (manual fallback):

Windows (recommended):

{
  "mcpServers": {
    "mcp-aws-manager": {
      "command": "C:\\Users\\<user>\\AppData\\Roaming\\npm\\mcp-aws-manager-mcp.cmd",
      "args": ["--surface", "all"]
    }
  }
}

macOS/Linux:

{
  "mcpServers": {
    "mcp-aws-manager": {
      "command": "mcp-aws-manager-mcp",
      "args": ["--surface", "all"]
    }
  }
}

3. npx (without global install):

{
  "mcpServers": {
    "mcp-aws-manager": {
      "command": "npx",
      "args": ["-y", "-p", "mcp-aws-manager", "mcp-aws-manager-mcp", "--surface", "all"]
    }
  }
}

User Confirmation Required

These are normally the only manual steps (agent-guided):

• SSO browser login and MFA confirmation
• IAM permission approval in organization account
• For EC2 runtime visibility: attach AmazonSSMManagedInstanceCore and keep SSM Agent/network healthy

Agent retry loop (recommended):

1. Execute tool call.
2. If requiresUserAction=false, summarize and finish.
3. If requiresUserAction=true, present one requiredActions[] item and ask user to complete it.
4. When user confirms completion, retry using guidance.retryTool + guidance.retryArgs.
5. Repeat until requiresUserAction=false.

MCP Tool Usage

Run single-entry MCP server (default: --surface all):

mcp-aws-manager-mcp

Choose exposure profile:

• mcp-aws-manager-mcp --surface all|readonly|mutate (gateway-only)

Gateway model (tools/list) exposes exactly 3 tools:

• capabilities_summary
• capabilities_detail
• gateway_execute

Gateway call flow:

1. Call capabilities_summary to receive operation categories and operationId list.
2. Call capabilities_detail with one operationId to inspect execution contract.
3. Call gateway_execute with { "operationId": "...", "args": { ... } }.

Typical operationId families:

• Discovery: discover.aws_inventory_basic, discover.aws_inventory_advanced, discover.aws_inventory_summary, discover.aws_inventory_detail, discover.list_bedrock_endpoints, discover.list_sagemaker_endpoints.
• Mutation: mutate.ec2_start_instances, mutate.ec2_stop_instances, mutate.ec2_reboot_instances, mutate.ec2_apply_instance_profile, mutate.ec2_rollback_last_change, mutate.ecs_update_service_desired_count, mutate.asg_set_desired_capacity, mutate.rds_start_instances, mutate.rds_stop_instances, mutate.rds_reboot_instances, mutate.eks_update_nodegroup_scaling.
• Governance/System: governance.verify_chain, system.get_server_runtime, system.cli_help.

Gateway execute examples:

• Discovery summary: { "operationId": "discover.aws_inventory_summary", "args": { "profiles": ["default"], "regions": ["ap-southeast-1"] } }
• Discovery detail: { "operationId": "discover.aws_inventory_detail", "args": { "profiles": ["default"], "regions": ["ap-southeast-1"], "resourceTypes": ["ec2"], "limit": 50 } }
• AI/ML read: { "operationId": "discover.list_bedrock_endpoints", "args": { "profile": "default", "region": "us-east-1", "metricWindowMinutes": 60 } }
• Mutation: { "operationId": "mutate.ec2_start_instances", "args": { "profile": "default", "region": "ap-southeast-1", "instanceIds": ["i-123"], "userConfirmation": "yes" } }

Discover operation notes:

• discover.aws_inventory_basic uses a compact input schema.
• discover.aws_inventory_advanced exposes full inventory/runtime options.
• discover.aws_inventory_summary is summary-first and returns selector hints.
• discover.aws_inventory_detail returns filtered/paged detailed records (resourceTypes, resourceIds, offset, limit).
• Output layout options are supported: outputProfile, sections, includeFields, excludeFields, rendererTemplate.
• Routing/control options are supported: mode, schemaTier, userConfirmation, profileShard, regionShard, orgRoleName, orgAccountIds, orgIncludeAllAccounts, orgMaxAccounts, enterprisePolicyPath, approvalTicket, changeReason.
• Evidence/output artifact options are supported: topologyOutPath, relationshipsOutPath, governanceLogPath, verifyGovernanceChain, incidentWebhookUrl, incidentWebhookTimeoutMs, incidentWebhookAuthHeader, incidentWebhookToken, incidentOutPath.
• workingDirectory is checked against allowlist roots (cwd, home, and optional MCP_AWS_ALLOWED_WORKDIRS).
• Structured JSON logs are emitted to stderr; control verbosity with LOG_LEVEL=error|warn|info|debug (default: info).

Runtime introspection:

• In gateway mode, use gateway_execute with operationId: "system.get_server_runtime".
• Runtime payload includes current surface, exposed operations/tools, confirmation policy, and response contract metadata.

Example tool args:

{
  "profiles": ["default"],
  "regions": ["ap-northeast-2"],
  "profileShard": { "index": 1, "total": 2 },
  "regionShard": { "index": 1, "total": 3 },
  "orgRoleName": "OrganizationAccountAccessRole",
  "orgIncludeAllAccounts": false,
  "orgAccountIds": ["111111111111", "222222222222"],
  "orgMaxAccounts": 25,
  "includeLambda": true,
  "includeIac": true,
  "includeCicd": true,
  "includeBackupDr": true,
  "includeSecurity": true,
  "includeFinops": true,
  "includeApplication": true,
  "includeIncident": true,
  "mode": "observe",
  "schemaTier": "advanced",
  "publicOnly": true,
  "runtimeSnapshot": true,
  "outputProfile": "operator",
  "sections": ["overview", "runtime", "application", "actions"],
  "includeFields": ["resourceType", "resourceId", "state", "ssmOnline", "runtimeSnapshotStatus"],
  "excludeFields": ["runtimeSnapshotOutput"],
  "clientProfile": "codex",
  "rendererTemplate": "compact",
  "userConfirmation": "yes",
  "topologyOutPath": "C:\\tmp\\topology.json",
  "relationshipsOutPath": "C:\\tmp\\relationships.json",
  "governanceLogPath": "C:\\tmp\\governance.jsonl",
  "incidentWebhookUrl": "https://example.com/hooks/oncall",
  "incidentWebhookAuthHeader": "Authorization",
  "incidentWebhookToken": "Bearer ***",
  "incidentOutPath": "C:\\tmp\\incident.json",
  "htmlOutPath": "C:\\tmp\\inventory.html",
  "openHtml": true,
  "manualServerListPath": "C:\\tmp\\servers.csv",
  "pemPaths": ["C:\\keys\\prod.pem"],
  "sshUser": "ec2-user",
  "sshPort": 22,
  "sshConnectTimeoutSec": 8,
  "autoSsoLogin": true,
  "noProgress": true
}

Action Codes

Common ACTION_REQUIRED codes:

• SSO_LOGIN_NEEDED
• AWS_CREDENTIALS_REQUIRED
• IAM_PERMISSION_REQUIRED
• AWS_OPERATION_FAILED
• SSM_ROLE_OR_AGENT_REQUIRED
• INSTANCE_HAS_PROFILE
• IAM_PROFILE_ASSOCIATION_FAILED
• CHANGE_CONFIRMATION_REQUIRED
• CHANGE_NOT_CONFIRMED
• APPROVAL_TICKET_REQUIRED
• APPROVAL_TICKET_INVALID
• CHANGE_REASON_REQUIRED
• ENTERPRISE_POLICY_NOT_FOUND
• ENTERPRISE_POLICY_INVALID
• ENTERPRISE_POLICY_BLOCKED_ACTION
• ENTERPRISE_POLICY_DISCOVER_REMEDIATION_BLOCKED
• ENTERPRISE_POLICY_BLOCKED_PROFILE
• ENTERPRISE_POLICY_BLOCKED_REGION
• ENTERPRISE_POLICY_BATCH_TOO_LARGE
• INCIDENT_WEBHOOK_DISPATCH_FAILED
• GOVERNANCE_LOG_WRITE_FAILED
• GOVERNANCE_CHAIN_BROKEN
• GOVERNANCE_LOG_NOT_FOUND
• GOVERNANCE_LOG_INVALID_JSON
• GOVERNANCE_CHAIN_HASH_MISMATCH
• GOVERNANCE_CHAIN_PREV_HASH_MISMATCH
• IAC_CLOUDFORMATION_PERMISSION_REQUIRED
• CICD_CODEPIPELINE_PERMISSION_REQUIRED
• CICD_CODEBUILD_PERMISSION_REQUIRED
• CICD_CODEDEPLOY_PERMISSION_REQUIRED
• BACKUP_PERMISSION_REQUIRED
• BACKUP_COVERAGE_REVIEW_REQUIRED
• SECURITY_POSTURE_PERMISSION_REQUIRED
• SECURITY_CONFIG_PERMISSION_REQUIRED
• SECURITY_INSPECTOR2_PERMISSION_REQUIRED
• SECURITY_ACM_PERMISSION_REQUIRED
• SECURITY_ACM_CERT_EXPIRING
• FINOPS_COST_EXPLORER_PERMISSION_REQUIRED
• INCIDENT_ESCALATION_RECOMMENDED
• WORKING_DIRECTORY_INVALID
• WORKING_DIRECTORY_NOT_FOUND
• WORKING_DIRECTORY_NOT_DIRECTORY
• WORKING_DIRECTORY_NOT_ALLOWED
• SSM_RUNCOMMAND_PERMISSION_REQUIRED
• LAMBDA_LIST_PERMISSION_REQUIRED
• ELBV2_LIST_PERMISSION_REQUIRED
• ASG_LIST_PERMISSION_REQUIRED
• RDS_LIST_PERMISSION_REQUIRED
• ELASTICACHE_LIST_PERMISSION_REQUIRED
• ROUTE53_LIST_PERMISSION_REQUIRED
• VPC_LIST_PERMISSION_REQUIRED
• ECS_LIST_PERMISSION_REQUIRED
• S3_LIST_PERMISSION_REQUIRED
• IAM_LIST_PERMISSION_REQUIRED
• KMS_LIST_PERMISSION_REQUIRED
• SNS_LIST_PERMISSION_REQUIRED
• EVENTBRIDGE_LIST_PERMISSION_REQUIRED
• SQS_LIST_PERMISSION_REQUIRED
• ACM_LIST_PERMISSION_REQUIRED
• KINESIS_LIST_PERMISSION_REQUIRED
• MSK_LIST_PERMISSION_REQUIRED
• CLOUDWATCH_LIST_PERMISSION_REQUIRED
• EBS_LIST_PERMISSION_REQUIRED
• EFS_LIST_PERMISSION_REQUIRED
• EKS_LIST_PERMISSION_REQUIRED
• APIGATEWAY_LIST_PERMISSION_REQUIRED
• APIGATEWAYV2_LIST_PERMISSION_REQUIRED
• CLOUDFRONT_LIST_PERMISSION_REQUIRED
• WAF_LIST_PERMISSION_REQUIRED
• SHIELD_LIST_PERMISSION_REQUIRED
• STEPFUNCTIONS_LIST_PERMISSION_REQUIRED
• CLOUDWATCH_LOGS_LIST_PERMISSION_REQUIRED
• XRAY_LIST_PERMISSION_REQUIRED
• INSPECTOR2_LIST_PERMISSION_REQUIRED
• REDSHIFT_LIST_PERMISSION_REQUIRED
• OPENSEARCH_LIST_PERMISSION_REQUIRED
• ORGANIZATIONS_LIST_PERMISSION_REQUIRED
• CONTROLTOWER_LIST_PERMISSION_REQUIRED
• MANUAL_SERVER_LIST_EMPTY
• MANUAL_SERVER_HOST_REQUIRED
• WEB_IDENTITY_CONFIG_REQUIRED
• WEB_IDENTITY_TOKEN_FILE_NOT_FOUND
• PEM_KEY_NOT_FOUND
• BASTION_PEM_KEY_NOT_FOUND
• PEM_MAPPING_REQUIRED
• SSH_CLIENT_NOT_FOUND
• SSH_AUTH_OR_CONNECT_FAILED

ACTION_REQUIRED metadata includes:

• severity
• owner
• autoFixable

Response Contract

• Runtime contract fields are included in every tool response:
  • meta.schemaVersion
  • meta.compatibility
  • meta.responseType
• View envelope (CLI JSON / MCP parsed payload) includes:
  • outputProfile
  • sections
  • fields
  • view.records
  • rawNormalized (always included for re-processing stability)
  • schema / schemaVersion
• Contract schema: schemas/mcp-tool-response.schema.json
• Compatibility policy: docs/RESPONSE_COMPATIBILITY_POLICY.md

Recommended approach:

• SSO (IAM Identity Center) for human operators (recommended)
• Access Key only as a local fallback when SSO is unavailable
• For CI/CD automation, prefer IAM Role/OIDC over long-lived user keys

Why SSO is preferred:

• Avoids storing long-lived keys on local machines
• Makes MFA/session-expiry behavior consistent
• Improves centralized access revocation and auditability

Prerequisites:

• AWS CLI v2
• IAM Identity Center configured in the organization account
• Target account + permission set assignment completed

SSO setup:

aws configure sso --profile default
aws sso login --profile default
aws sts get-caller-identity --profile default

Access key setup (fallback):

aws configure --profile default
aws sts get-caller-identity --profile default

OIDC/WebIdentity setup (CI/CD or Kubernetes):

export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/oidc-workload-role
export AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
aws sts get-caller-identity

CLI option equivalent:

mcp-aws-manager discover \
  --auth-mode web-identity \
  --web-identity-role-arn arn:aws:iam::123456789012:role/oidc-workload-role \
  --web-identity-token-file /var/run/secrets/eks.amazonaws.com/serviceaccount/token

Quick checks:

aws configure list-profiles
aws configure list --profile default
aws ec2 describe-regions --profile default

Frequent errors:

• Missing the following required SSO configuration values Re-run aws configure sso --profile default and complete all prompts.
• Unable to locate credentials SSO session expired or credentials are missing. Run aws sso login --profile default or reconfigure access keys.
• AccessDenied / not authorized The profile is valid, but IAM permission set/policy is insufficient for the requested API.

Auth modes:

• auto (default): uses profile by default, but can switch to WebIdentity when token+role are provided.
• profile: always uses AWS profile credentials (fromIni).
• web-identity: always uses OIDC/WebIdentity token path (fromTokenFile).

Recommended selection:

• Human operator workstation: profile + SSO login.
• CI/CD or Kubernetes workload identity: web-identity.
• Mixed environments: keep auto and pass explicit fields when needed.

Profile/SSO path:

aws configure sso --profile prod-admin
aws sso login --profile prod-admin
mcp-aws-manager discover --profiles prod-admin --regions us-east-1 --auth-mode profile

WebIdentity path:

export AWS_ROLE_ARN=arn:aws:iam::123456789012:role/oidc-workload-role
export AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/eks.amazonaws.com/serviceaccount/token
mcp-aws-manager discover --auth-mode web-identity --regions us-east-1

Gateway/mutation and AI-read input fields:

• authMode
• webIdentityRoleArn
• webIdentityTokenFile
• webIdentitySessionName (optional)

Input precedence:

• explicit tool input/CLI option
• MCP_AWS_WEB_IDENTITY_*
• AWS_ROLE_ARN / AWS_WEB_IDENTITY_TOKEN_FILE

Common auth-related ACTION_REQUIRED:

• WEB_IDENTITY_CONFIG_REQUIRED
• WEB_IDENTITY_TOKEN_FILE_NOT_FOUND
• AWS_CREDENTIALS_REQUIRED

Runtime snapshot route selection:

• AWS-managed EC2 (manualInput=false): SSM RunCommand path.
• Manual server list (manualInput=true): SSH path.
• SSH path uses:
  • ssh-pem (direct key)
  • ssh-proxyjump (--ssh-proxy-jump)
  • ssh-bastion (--ssh-bastion-*, internally via ProxyCommand)

Manual list + direct PEM example:

mcp-aws-manager discover \
  --manual-server-list ./servers.json \
  --pem-paths ~/.ssh/target.pem \
  --runtime-snapshot

Manual list + ProxyJump example:

mcp-aws-manager discover \
  --manual-server-list ./servers.json \
  --pem-paths ~/.ssh/target.pem \
  --ssh-proxy-jump [email protected] \
  --runtime-snapshot

Manual list + Bastion key split example:

mcp-aws-manager discover \
  --manual-server-list ./servers.json \
  --pem-paths ~/.ssh/target.pem \
  --ssh-bastion-host bastion.example.com \
  --ssh-bastion-user ec2-user \
  --ssh-bastion-port 22 \
  --ssh-bastion-pem-path ~/.ssh/bastion.pem \
  --runtime-snapshot

Manual server JSON fields (optional per host):

• host/publicIp/privateIp/publicDns
• sshUser, sshPort, pemPath
• proxyJump or sshProxyJump
• bastionHost, bastionUser, bastionPort, bastionPemPath

Common access-path ACTION_REQUIRED:

• MANUAL_SERVER_HOST_REQUIRED
• PEM_MAPPING_REQUIRED
• BASTION_PEM_KEY_NOT_FOUND
• SSH_AUTH_OR_CONNECT_FAILED

State file default:

• ~/.mcp-aws-manager/integrations.json

List/show:

mcp-aws-manager integration list
mcp-aws-manager integration show

Configure + enable:

mcp-aws-manager integration configure pagerduty --set routingKey=XXXX --enable

Policy pack:

mcp-aws-manager integration policy show
mcp-aws-manager integration policy set strict_change

Doctor:

mcp-aws-manager integration doctor
mcp-aws-manager integration doctor --check-live --timeout-ms 8000

Discover-time overrides:

• --integration-config <path>
• --integration-timeout-ms <n>
• --policy-pack <balanced|strict_change|readonly_only>
• --policy-override

• --profiles <a,b,c>
• --regions <a,b,c>
• --profile-shard <index/total>
• --region-shard <index/total>
• --org-role-name <role-name>
• --org-account-ids <a,b,c>
• --org-include-all-accounts
• --org-max-accounts <n>
• --instance-ids <id1,id2>
• --include-lambda
• --include-ec2 / --no-ec2
• --include-alb / --no-include-alb
• --include-asg / --no-include-asg
• --include-rds / --no-include-rds
• --include-elasticache / --no-include-elasticache
• --include-route53 / --no-include-route53
• --include-vpc / --no-include-vpc
• --include-ecs / --no-include-ecs
• --include-s3 / --no-include-s3
• --include-iam / --no-include-iam
• --include-kms / --no-include-kms
• --include-cloudwatch / --no-include-cloudwatch
• --include-cloudtrail / --no-include-cloudtrail
• --include-config / --no-include-config
• --include-secrets / --no-include-secrets
• --include-parameter-store / --no-include-parameter-store
• --include-ecr / --no-include-ecr
• --include-dynamodb / --no-include-dynamodb
• --include-sns / --no-include-sns
• --include-eventbridge / --no-include-eventbridge
• --include-sqs / --no-include-sqs
• --include-acm / --no-include-acm
• --include-kinesis / --no-include-kinesis
• --include-msk / --no-include-msk
• --include-budgets / --no-include-budgets
• --include-cost-anomaly / --no-include-cost-anomaly
• --include-ebs / --no-include-ebs
• --include-efs / --no-include-efs
• --include-eks / --no-include-eks
• --include-apigateway / --no-include-apigateway
• --include-apigatewayv2 / --no-include-apigatewayv2
• --include-cloudfront / --no-include-cloudfront
• --include-waf / --no-include-waf
• --include-shield / --no-include-shield
• --include-step-functions / --no-include-step-functions
• --include-cloudwatch-logs / --no-include-cloudwatch-logs
• --include-xray / --no-include-xray
• --include-inspector2 / --no-include-inspector2
• --include-redshift / --no-include-redshift
• --include-opensearch / --no-include-opensearch
• --include-organizations / --no-include-organizations
• --include-controltower / --no-include-controltower
• --include-iac / --no-include-iac
• --include-cicd / --no-include-cicd
• --include-backup-dr / --no-include-backup-dr
• --include-security / --no-include-security
• --include-finops / --no-include-finops
• --include-application / --no-include-application
• --include-incident / --no-include-incident
• --incident-force-escalate
• --mode <auto|observe|change|incident>
• --schema-tier <auto|basic|advanced>
• --auth-mode <auto|profile|web-identity>
• --web-identity-role-arn <arn>
• --web-identity-token-file <path>
• --web-identity-session-name <name>
• --user-confirmation <yes|no>
• --enterprise-policy <path>
• --approval-ticket <id>
• --change-reason <text>
• --policy-pack <balanced|strict_change|readonly_only>
• --policy-override
• --integration-config <path>
• --integration-timeout-ms <n>
• --public-only
• --managed-only
• --auto-remediate-ssm
• --ssm-instance-profile-name <name> / --ssm-instance-profile-arn <arn>
• --allow-replace-profile
• --runtime-snapshot / --no-runtime-snapshot
• --snapshot-profile <quick|standard|deep>
• --output-profile <operator|audit|exec|finops|incident|compact|auditable>
• --sections <overview,inventory,runtime,application,iac,cicd,backupDr,security,finops,incident,actions,governance>
• --include-fields <a,b,c>
• --exclude-fields <a,b,c>
• --client-profile <codex|claude|cursor|operator>
• --renderer-template <default|compact>
• --snapshot-timeout <seconds>
• --snapshot-concurrency <n>
• --snapshot-max-kb <n>
• --manual-server-list <path> (JSON/CSV)
• --pem-paths <a,b,c>
• --ssh-user <name>
• --ssh-port <port>
• --ssh-connect-timeout <seconds>
• --ssh-proxy-jump <user@host[:port][,hop2...]>
• --ssh-bastion-host <host>
• --ssh-bastion-user <user>
• --ssh-bastion-port <port>
• --ssh-bastion-pem-path <path>
• --html-out <path> (default: auto path, workspace/home aws-inventory.html)
• --topology-out <path> (default: auto path, workspace/home aws-topology.json)
• --relationships-out <path> (default: auto path, workspace/home aws-relationships.json)
• --governance-log <path> (default: auto path, workspace/home mcp-aws-governance-log.jsonl)
• --verify-governance-chain / --no-verify-governance-chain
• --incident-webhook-url <url>
• --incident-webhook-timeout-ms <n>
• --incident-webhook-auth-header <name>
• --incident-webhook-token <token>
• --incident-out <path>
• --open-html (open; default is on)
• --no-open-html (disable auto-open)
• --auto-sso-login / --no-auto-sso-login
• --format <json|csv|markdown|html>
• --out <path>

Governance verification command:

mcp-aws-manager governance verify --governance-log ./mcp-aws-governance-log.jsonl --strict

Client Smoke Automation

Run cross-client smoke checks:

npm run smoke:clients
npm run smoke:clients:strict
node scripts/smoke-clients.js --clients codex,claude --json-out ./smoke-report.json

• Default mode reports status and exits 0.
• --strict exits non-zero when any selected client is not healthy.

AWS E2E Scenario Automation

Run real-account scenario checks (permission/region/recovery path):

npm run e2e:aws -- --profile default --region us-east-1 --out-dir ./.e2e-aws
npm run e2e:aws:strict -- --profile default --region us-east-1

Current scenarios include:

• baseline observe contract (schema + rawNormalized)
• invalid region handling
• mutable confirmation gate (missing / yes)
• incident escalation artifact generation
• enterprise policy approval-ticket enforcement
• governance chain verification (governance verify --strict)

The E2E runner validates:

• baseline observe flow (JSON contract + rawNormalized)
• invalid region handling path
• mutable discover confirmation gate (CHANGE_CONFIRMATION_REQUIRED)
• confirmation-approved path (--user-confirmation yes)
• forced incident escalation payload artifact (INCIDENT_ESCALATION_RECOMMENDED)

Minimum permissions depend on enabled features.

• Core inventory: ec2:DescribeRegions, ec2:DescribeInstances
• Lambda: lambda:ListFunctions
• ALB/TargetGroups: elasticloadbalancing:DescribeLoadBalancers, elasticloadbalancing:DescribeTargetGroups
• ASG: autoscaling:DescribeAutoScalingGroups
• RDS: rds:DescribeDBInstances
• ElastiCache: elasticache:DescribeCacheClusters
• Route53: route53:ListHostedZones, route53:ListResourceRecordSets
• VPC/Subnet/SecurityGroup: ec2:DescribeVpcs, ec2:DescribeSubnets, ec2:DescribeSecurityGroups
• ECS: ecs:ListClusters, ecs:DescribeClusters, ecs:ListServices, ecs:DescribeServices
• S3: s3:ListAllMyBuckets, s3:GetBucketLocation
• IAM: iam:ListRoles
• KMS: kms:ListKeys, kms:DescribeKey
• ACM: acm:ListCertificates, acm:DescribeCertificate
• Kinesis: kinesis:ListStreams, kinesis:DescribeStreamSummary
• MSK: kafka:ListClustersV2
• CloudWatch: cloudwatch:DescribeAlarms
• EBS: ec2:DescribeVolumes
• EFS: elasticfilesystem:DescribeFileSystems
• EKS: eks:ListClusters, eks:DescribeCluster
• API Gateway: apigateway:GET
• CloudFront: cloudfront:ListDistributions
• WAFv2: wafv2:ListWebACLs
• Shield: shield:ListProtections
• Step Functions: states:ListStateMachines
• CloudWatch Logs: logs:DescribeLogGroups
• X-Ray: xray:GetGroups
• Inspector2: inspector2:ListFindings
• Redshift: redshift:DescribeClusters
• OpenSearch: es:ListDomainNames, es:DescribeDomain
• Organizations: organizations:ListAccounts
• ControlTower: controltower:ListLandingZones
• CI/CD analysis: codepipeline:ListPipelines, codepipeline:ListPipelineExecutions, codebuild:ListProjects, codebuild:ListBuildsForProject, codebuild:BatchGetBuilds, codedeploy:ListApplications, codedeploy:ListDeploymentGroups, codedeploy:ListDeployments, codedeploy:BatchGetDeployments
• Security analysis extension: config:DescribeConfigRules, config:DescribeComplianceByConfigRule, acm:ListCertificates, acm:DescribeCertificate
• FinOps analysis extension: ce:GetSavingsPlansUtilization, ce:GetReservationCoverage
• Runtime snapshot: ssm:SendCommand, ssm:GetCommandInvocation, ssm:DescribeInstanceInformation
• Auto-remediation: ec2:AssociateIamInstanceProfile, optional ec2:ReplaceIamInstanceProfileAssociation, iam:PassRole
• Mutate tool extension:
  • ECS: ecs:DescribeServices, ecs:UpdateService
  • ASG: autoscaling:SetDesiredCapacity
  • RDS: rds:StartDBInstance, rds:StopDBInstance, rds:RebootDBInstance
  • EKS: eks:DescribeNodegroup, eks:UpdateNodegroupConfig
• Organizations fan-out (optional): organizations:ListAccounts, sts:AssumeRole (target account role trust required)

Manual fallback mode:

• Inventory uses user-provided server list file (no AWS API required)
• Runtime snapshot supports direct PEM SSH and ProxyJump/Bastion routing (--ssh-proxy-jump, --ssh-bastion-*)

Related Docs

Document status:

• Canonical (keep synchronized with implementation): README.md, docs/RESPONSE_COMPATIBILITY_POLICY.md

• Reference (detail/positioning): docs/IMPLEMENTATION_INTEGRATIONS.md, docs/MCP_DIFFERENTIATION.md, docs/MCP_DIFFERENTIATION_KO.md, workflow/AGENT_WORKING_CONTEXT_KO.md, docs/RECORDS_FIELD_REFERENCE_KO.md

• README_KO.md: Korean overview and quick start

• docs/IMPLEMENTATION_INTEGRATIONS.md: API/CLI integration inventory

• docs/MCP_DIFFERENTIATION.md: differentiation from existing AWS MCP servers

• docs/MCP_DIFFERENTIATION_KO.md: Korean differentiation guide and selection criteria

• workflow/AGENT_WORKING_CONTEXT_KO.md: agent-focused implementation invariants, gateway loop, and operation catalog quick reference

• docs/RECORDS_FIELD_REFERENCE_KO.md: full records[] field reference (292 fields)

• docs/RESPONSE_COMPATIBILITY_POLICY.md: response schema/version compatibility rules

• schemas/mcp-tool-response.schema.json: canonical tool response JSON schema