Unifying Conversational AI with AWS Resource Governance via SSO

This utility bridges your preferred large language model interfaces (like Claude, Cursor, etc.) directly to your Amazon Web Services tenancy. By utilizing AWS IAM Identity Center (SSO), it facilitates secure, temporary credential federation, allowing natural language instructions to translate into AWS API calls or shell operations against managed resources.

Core Capabilities

Deploy the power of Generative AI to govern your cloud environment:

• Identity Verification: Query your accessible AWS accounts and role mappings through conversational prompts.
• Automated Command Execution: Issue complex aws cli instructions against specified accounts and roles.
• Instance Control (via SSM): Remotely execute system-level shell commands on targeted EC2 compute instances using AWS Systems Manager.
• Multi-Tenancy Navigation: Seamlessly pivot context between distinct AWS environments (e.g., Development, Production) specified in your SSO assignment.
• Operational Monitoring: Extract runtime status and configuration details from active cloud assets.

Ideal Users & Use Cases

This tool is engineered for professionals deeply involved in AWS operations:

• Cloud Operations Teams (SRE/DevOps): Accelerating infrastructure audit, configuration checks, and cross-account reconciliation.
• Solution Architects: Rapidly validating resource topologies across various organizational units.
• Software Developers: Triggering deployments or verifying service health using verbal commands.
• Security Administrators: Auditing principal access and security configurations across the enterprise cloud footprint.

Deployment Sequence (Bootstrap)

Integrate this functionality in under 120 seconds:

Phase 1: Configure AWS SSO

Ensure your AWS IAM Identity Center (SSO) is fully established: 1. Activate IAM Identity Center within your primary AWS organization account. 2. Integrate your chosen identity provider (IdP) solution. 3. Define organizational units, permission sets, and map users/groups to target AWS accounts. 4. Capture the canonical AWS SSO Portal Access URL (e.g., https://yourcorp.awsapps.com/start).

Phase 2: Initiate Authentication Flow

Execute the login process which initiates the browser-based SSO redirect for token acquisition:

bash

Define critical environment variables for authentication targeting

export AWS_SSO_START_URL="https://your-company.awsapps.com/start" export AWS_REGION="us-east-1"

Authenticate and cache session tokens

npx -y @aashari/mcp-server-aws-sso login

Inspect discovered account/role inventory

npx -y @aashari/mcp-server-aws-sso ls-accounts

Example: Run an inventory check in a target environment

npx -y @aashari/mcp-server-aws-sso exec-command \ --account-id 123456789012 \ --role-name AuditorRole \ --command "aws iam list-users"

AI Assistant Integration Methods

Integration for Claude Desktop Clients

Modify the local configuration file (~/.claude/claude_desktop_config.json) to register this server as an available external tool (aws-sso):

{ "mcpServers": { "aws-sso": { "command": "npx", "args": ["-y", "@aashari/mcp-server-aws-sso"], "env": { "AWS_SSO_START_URL": "https://your-company.awsapps.com/start", "AWS_REGION": "us-east-1" } } } }

Upon relaunching the Claude application, the tool endpoint should appear as "🔗 aws-sso" in the interface.

Global Installation for Broader MCP Support

For environments supporting the Model Context Protocol via standard I/O streams:

bash npm install -g @aashari/mcp-server-aws-sso

Configure your specific AI environment to pipe STDIN/STDOUT to this executable.

Persistent Configuration File

Define system-wide defaults in ~/.mcp/configs.json to avoid repeating environment variables:

{ "aws-sso": { "environments": { "AWS_SSO_START_URL": "https://your-company.awsapps.com/start", "AWS_REGION": "us-east-1", "DEBUG": "false" } } }

Alias Note: The configuration system recognizes "@aashari/mcp-server-aws-sso" or "mcp-server-aws-sso" as valid keys interchangeably with "aws-sso".

Operational Scenarios & Example Prompts

🔐 Credential & Discovery Operations

• "Initiate AWS SSO authentication and confirm current session validity."
• "Enumerate all AWS account identifiers I am authorized to access."
• "Display the roles available for assumption within the Production account."

🛠️ Standard AWS Resource Querying

• "Within account 123456789012, list all S3 storage containers under the ReadOnly permission set."
• "Retrieve the configuration details for all active EC2 virtual machines running in us-west-2."
• "Detail the Virtual Private Clouds (VPCs) configured in the Staging environment."

🖥️ Remote System Management (SSM/EC2)

• "Execute the command 'df -h' on instance ID i-1234567890abcdef0 using the InfraOps role."
• "Run a full system status check (uptime, free -m) across all designated application servers."

Transport Architecture

This gateway supports dual communication protocols depending on deployment needs:

1. Standard I/O (STDIO) Transport

This is the default method when invoked directly by local desktop AI clients. It relies on piped communication conforming to the MCP protocol specification.

bash

Explicitly forcing STDIO mode

TRANSPORT_MODE=stdio npx @aashari/mcp-server-aws-sso

2. Networked (HTTP) Transport

For standalone server operation or web-based integrations, the tool launches an HTTP listener (defaulting to port 3000).

• Data Stream: Uses Server-Sent Events (SSE) for asynchronous responses.
• Access Point: http://localhost:3000/mcp
• Health Check: http://localhost:3000/

bash

Launching in HTTP mode

TRANSPORT_MODE=http npx @aashari/mcp-server-aws-sso

Environment Variables Control

Variable	Purpose	Default	Context
TRANSPORT_MODE	Defines I/O method (stdio or http)	http (server) / stdio (client)	Transport
PORT	HTTP Listener Port	3000	Transport
DEBUG	Verbose logging activation	false	General
AWS_SSO_START_URL	Mandatory SSO Portal Entry Point	(Must be set)	Authentication
AWS_SSO_REGION	Region associated with the SSO configuration	(Must be set)	Authentication
AWS_REGION	Default region for CLI actions (if not specified in command)	(None)	AWS Context

Command Line Interface Reference

All execution commands are accessed via kebab-case syntax after the primary utility name (e.g., mcp-aws-sso). Detailed flags are available via --help.

• login: Initiates SSO token acquisition. Use --no-launch-browser for headless environments.
• status: Verifies current credential validity.
• ls-accounts: Outputs the discovered IAM Identity Center account/role inventory.
• exec-command: Executes generic AWS CLI operations, requiring account-id, role-name, and the full command string.
• ec2-exec-command: Specialized command for SSM payload execution on target EC2 instances, requiring instance-id, account-id, role-name, and the shell command.

Common Remediation Strategies

Session Invalidation or Authentication Failure

If tokens lapse or fail verification:

1. Force Re-authentication: Rerun the initial login procedure.
2. Configuration Integrity Check: Double-check environment variables, especially AWS_SSO_START_URL, against the browser portal URL.

Resource Resolution Issues (Account/Role Not Found)

1. Inventory Check: Execute mcp-aws-sso ls-accounts to validate the exact string names being used.
2. ID Format: Ensure account identifiers are precisely 12 numeric digits.

Execution Failures (AWS CLI Dependency)

1. Prerequisite: AWS CLI v2 must be installed and accessible in the execution environment's PATH for exec-command functionality.
2. Self-Test: Verify manual execution: aws sts get-caller-identity.

SSM Command Failures on EC2 Target

1. SSM Agent Health: Confirm the target EC2 instance has a running SSM Agent.
2. IAM Instance Profile: Verify the instance's assigned IAM role possesses the AmazonSSMManagedInstanceCore policy.
3. Permission Boundary: Ensure the assumed role has necessary ssm:SendCommand permissions.

Security and Privacy Considerations

This tool prioritizes least-privilege and local execution:

• Execution Context: All processing and credential handling occur exclusively on the local host.
• Data Transit: No operational data or credentials leave your local environment unless explicitly routed by the AI assistant framework.
• Credential Lifecycle: Utilizes temporary, short-lived session tokens derived from AWS SSO, which naturally expire.
• Scope Limitation: Access is strictly limited to the roles explicitly assigned through your IAM Identity Center permissions.