Orchestrate AWS Operations with Conversational AI

Integrate major large language models (LLMs) like Claude and Cursor AI directly with your Amazon Web Services footprint utilizing the established security framework of Single Sign-On. This conduit empowers natural language interactions to provision, inspect, and manage cloud assets, including EC2 instances and S3 storage.

Core Capabilities

• Account Discovery: Query your AI regarding available AWS organizations and permissible roles: "Which accounts can I access right now?"
• CLI Execution: Invoke arbitrary AWS CLI instructions: "Retrieve the manifest of all production S3 containers."
• Instance Management: Control compute resources conversationally: "Determine the current load factor on hypervisor i-123456789."
• Cross-Account Interoperability: Seamlessly operate across disparate organizational units: "Pivot to the QA boundary and map out its VPC topology."
• Real-time State Polling: Obtain immediate operational feedback: "Report the current operational status of all active compute units."
• Remote System Commands: Dispatch shell scripts via SSM: "Run 'top -b -n 1' on my primary application host via SSM."

Ideal User Profiles

• Infrastructure Guardians (DevOps/SRE) automating tasks across complex, multi-tenant AWS topologies.
• Cloud System Designers requiring rapid, conversational auditing of resource inventories.
• Software Developers accelerating deployment verification and infrastructure debugging via chat interfaces.
• Security Administrators performing compliance checks across various boundaries.

Rapid Implementation Guide

Launch in under 120 seconds:

1. AWS IAM Identity Center Prerequisite

Configure your environment: 1. Activate AWS IAM Identity Center within your primary account. 2. Establish the federation link to your identity provider (IdP). 3. Define and map appropriate permission sets to user groups/individuals. 4. Securely record the SSO Entry Point URL (e.g., https://yourcorp.awsapps.com/start).

2. Initial Authentication Sequence

bash

Configure essential environment variables

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

Initiate the credential acquisition process

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

Inventory accessible organizational units and roles

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

Dispatch a specific AWS management instruction

npx -y @aashari/mcp-server-aws-sso exec-command \ --account-id 123456789012 \ --role-name AuditorRole \ --command "aws s3 ls --summarize"

AI Assistant Integration

For Local Claude Desktop Clients

Modify your configuration file (~/.claude/claude_desktop_config.json):

{ "mcpServers": { "aws-sso-connector": { "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" } } } }

Reload the Claude application; the connection status bar should show the new service handle.

Universal MCP Compatibility

For other agents supporting the MCP standard, install the utility globally:

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

Then configure your agent to use the server via STDIO pipe transport.

System-Wide Configuration File

Persistence across sessions can be achieved via ~/.mcp/configs.json:

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

Alias Note: The configuration key can alternatively be set to the full package name or another alias, like mcp-aws-auth-bridge.

Operational Scenarios (Natural Language Prompts)

Authentication & Inventory

• "Initiate SSO authentication flow and report my current session validity."
• "Display a comprehensive roster of all AWS tenants I can access and the associated permissions policies."

Infrastructure Auditing

• "List all assets tagged 'Production' within account 123456789012."
• "Retrieve the network configuration details for the VPC in the staging environment."

Remote Execution via SSM

• "Execute 'journalctl -xe' on the primary database server associated with instance ID i-abc..."
• "Determine memory utilization across all running compute resources within the primary region using the System Manager Agent."

Protocol Interface Specifications (Click to expand)

### `sso_authenticate` **Mandatory Re-login:** {} **Bypassing Browser Launch:** { "launchBrowser": false } ### `sso_get_status` **Check Credential Freshness:** {} ### `sso_enumerate_tenants` **List Accessible Accounts:** {} ### `sso_invoke_aws_cli` **Query Specific S3 Configuration:** { "accountId": "123456789012", "roleName": "ReadOnly", "command": "aws s3api list-buckets" } **Describe Regional Compute Inventory:** { "accountId": "123456789012", "roleName": "AdminRole", "command": "aws ec2 describe-instances --query 'Reservations[*].Instances[*].[ID, Name, Type]' --output table", "region": "eu-central-1" } ### `sso_invoke_ssm_command` **System Resource Check:** { "instanceId": "i-0a69e80761897dcce", "accountId": "123456789012", "roleName": "OpsEngineer", "command": "df -hT && uptime" }

Communication Protocols

This handler supports dual methodologies for interfacing with consuming agents:

Standard I/O (STDIO) Transport

• The default mechanism for direct MCP agent interaction (e.g., local desktop applications).
• Utilizes process pipes for bidirectional data exchange.

bash

Invoke via STDIO (preferred by native AI clients)

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

HyperText Transfer Protocol (HTTP) Transport

• A robust, concurrent mode suitable for web services or development testing.
• Exposes an endpoint, typically on port 3000 (configurable via PORT variable).
• Data Flow: Server-Sent Events (SSE) are used for asynchronous outbound data.
• Access Point: http://localhost:3000/mcp
• Health Check: http://localhost:3000/

bash

Launching in HTTP server mode

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

Environment Configuration

Transport Controls: - TRANSPORT_MODE: Set to stdio or http (Default: http in standalone mode). - PORT: HTTP binding address (Default: 3000). - DEBUG: Verbosity toggle (Default: false).

AWS Authentication Context: - AWS_SSO_START_URL: Mandatory portal URL. - AWS_SSO_REGION: The region where your Identity Center is provisioned. - AWS_PROFILE: Optional name for profile override.

Command Interface Reference

CLI operations adhere to kebab-case. Consult --help on any subcommand for parameter details (e.g., mcp-aws-auth-bridge login --help).

• login: Establishes SSO session, handles browser interaction (--no-launch-browser).
• status: Verifies current token validity.
• ls-accounts: Enumerates accessible tenants and assumed roles.
• invoke-aws-cli: Executes arbitrary AWS CLI calls (--account-id, --role-name, --command, --region).
• invoke-ssm-command: Executes shell operations remotely on EC2 instances (--instance-id, --account-id, --command).

CLI Execution Examples (Click to expand)

### Authentication **Interactive Login:** bash mcp-aws-auth-bridge login ### Command Invocation **Listing Resources in a Specific Boundary:** bash mcp-aws-auth-bridge invoke-aws-cli \ --account-id 123456789012 \ --role-name AuditorRole \ --command "aws ec2 describe-regions --output text" ### Remote System Interaction **Checking Service Status on a Target Host:** bash mcp-aws-auth-bridge invoke-ssm-command \ --instance-id i-0a69e80761897dcce \ --account-id 123456789012 \ --role-name InfraOps \ --command "systemctl is-active nginx"

Diagnostic Guidance

Token Expiration or SSO Failure

1. Re-Authenticate: Force a fresh token acquisition: bash mcp-aws-auth-bridge login

2. Validate Configuration: Double-check that AWS_SSO_START_URL precisely matches your organization's Identity Center gateway.

Resource Identification Errors ("Tenant/Role Unreachable")

1. Inventory Check: Confirm accessibility via: bash mcp-aws-auth-bridge ls-accounts

2. Parameter Accuracy: Ensure provided Account IDs are 12-digit strings and Role Names are case-sensitive matches to defined permission sets.

SSM Command Failures (EC2 Interaction)

1. Agent Status: The target EC2 instance must have the SSM Agent running.
2. IAM Policy Check: The instance profile must possess the AmazonSSMManagedInstanceCore policy.
3. Execution Role Permissions: The assumed role used by the bridge must have ssm:SendCommand capabilities.

Integration Troubleshooting (AI Client)

1. Configuration Reload: Ensure the host AI application (e.g., Claude Desktop) has been fully restarted after config file modification.
2. Status Indicator: Confirm the expected service handle (e.g., aws-sso-connector) appears in the application's connection dashboard.

Frequently Addressed Inquiries

Security Posture

This mechanism maintains high security standards by: - Operating exclusively within your local execution environment. - Leveraging official AWS security workflows (SSO). - Utilizing short-lived, temporary IAM credentials. - Never relaying sensitive access data externally.

AWS CLI Dependency

While the authentication handshake and listing features are self-contained, the invoke-aws-cli function necessitates a correctly installed and PATH-accessible AWS CLI v2 installation to execute backend AWS API calls.

Multi-Organization Access

Interaction is scoped by the configured AWS_SSO_START_URL. For engagement with distinct AWS organizations, modify the configuration context (environment variables or the system config file) to point to the new SSO portal URL.

Protocol Output Structures (Click to expand)

### Successful Command Response Mapping markdown # ✅ AWS Connector: Operation Synopsis **Boundary Context**: 123456789012 / ReadOnly **Region Scope**: us-east-1 ## Requested Operation aws s3api list-buckets ## Result Payload { "Buckets": [ {"Name": "data-archive-2024", "CreationDate": "2024-01-01T00:00:00Z"}, {"Name": "public-assets", "CreationDate": "2023-05-10T12:30:00Z"} ], "Owner": {"ID": "a1b2c3d4e5f6"} } *Timestamp*: 2025-05-19 06:21:49 UTC ### Error Handling Output Structure markdown # ❌ AWS Connector: Execution Failure **Boundary Context**: 123456789012 / RestrictedRole **Region Scope**: us-east-1 ## Requested Operation aws secretsmanager get-secret-value --secret-id sensitive-key ## Error Type: Authorization Violation The role `RestrictedRole` lacks necessary entitlements for this API call. ## Detailed Exception An error occurred (AccessDeniedException) when calling the GetSecretValue operation: User: arn:aws:sts::... is not authorized to perform: secretsmanager:GetSecretValue on resource: sensitive-key ### Remediation Suggestion Review policies attached to the `RestrictedRole`. Ensure permissions for `secretsmanager:GetSecretValue` are granted. *Timestamp*: 2025-05-19 06:17:49 UTC

Development Environment Setup

bash

Obtain Source Code

git clone https://github.com/aashari/mcp-server-aws-sso.git cd mcp-server-aws-sso

Dependency Resolution

npm install

Local Running Mode (Watch for changes)

npm run dev:server

Support Channels

If standard troubleshooting fails, engage with the community or raise an issue: 1. Official Repository: github.com/aashari/mcp-server-aws-sso 2. Issue Tracking: File detailed bug reports or feature requests via GitHub Issues.

---

Designed to bridge the gap between conversational interfaces and complex cloud governance models.