Architecture - mcp-server-aws

Executive Summary

An MCP (Model Context Protocol) server that exposes AWS service operations as MCP tools, enabling AI assistants to interact with AWS infrastructure. Provides 7 tools covering EC2 instance listing, S3 bucket and object operations, Lambda function invocation, CloudWatch metrics retrieval, IAM role listing, and STS identity verification. Uses the AWS SDK v3 with individual service client packages and communicates via stdio transport for integration with MCP clients like Claude Desktop.

Overview

TypeScript

Language

API/Service

Architecture Diagram

MCP Client
Claude Desktop / IDE

| stdio transport |

MCP Server Entry
src/index.ts

ec2_list_instances

s3_list_buckets

s3_get_object

lambda_invoke

cloudwatch_get_metrics

iam_list_roles

sts_get_caller_identity

MCP Tool Handlers

EC2

Lambda

CloudWatch

IAM

STS

AWS Services (via AWS SDK v3)

Component Breakdown

Tool	File	AWS Service	Parameters
ec2_list_instances	`src/tools/ec2_list_instances.ts`	EC2	`region?`, `filters?`
s3_list_buckets	`src/tools/s3_list_buckets.ts`	S3	none
s3_get_object	`src/tools/s3_get_object.ts`	S3	`bucket`, `key`
lambda_invoke	`src/tools/lambda_invoke.ts`	Lambda	`function_name`, `payload?`
cloudwatch_get_metrics	`src/tools/cloudwatch_get_metrics.ts`	CloudWatch	`namespace`, `metric_name`, `dimensions?`, `period?`, `start_time`, `end_time`
iam_list_roles	`src/tools/iam_list_roles.ts`	IAM	`path_prefix?`, `max_items?`
sts_get_caller_identity	`src/tools/sts_get_caller_identity.ts`	STS	none

Data Flow / Request Flow

Client Connection -- MCP client (e.g., Claude Desktop) connects to the server via stdio transport.
Tool Discovery -- Client discovers available tools via the MCP protocol handshake.
Tool Invocation -- Client sends a tool call with name and parameters (validated via Zod schemas).
AWS API Call -- The tool handler creates the appropriate AWS SDK v3 client and makes the API call.
Response -- AWS response is serialized and returned to the MCP client via stdio.

Security Controls

Control	Implementation
AWS Authentication	Standard AWS credential chain: env vars, profiles, IAM roles
Input Validation	Zod schema validation for all tool parameters
Least Privilege	Each tool requires only specific AWS IAM permissions
No Persistent State	Server is stateless; no credentials stored on disk
Transport Security	stdio transport (local process); Docker isolation for remote

Industry Adaptation

Healthcare

AI-assisted HIPAA-compliant infrastructure monitoring. EC2 instance auditing for PHI workloads. CloudWatch alerts for healthcare application SLAs.

Finance

Lambda invocation for real-time transaction processing. IAM role auditing for SOX compliance. CloudWatch metrics for trading system latency.

Government

GovCloud region support. IAM role compliance auditing. S3 bucket policy verification for classified data handling.

Retail

S3 catalog management. Lambda-based order processing triggers. EC2 fleet monitoring during peak sales events.

SaaS

Multi-region EC2 fleet management. S3 tenant data access. CloudWatch dashboards for service health monitoring.

Production Readiness Checklist

Configure AWS credentials (access keys, IAM role, or profile)
Set AWS_REGION for target region
Create IAM policy with least-privilege permissions for required tools
Build TypeScript: npm run build
Test tool invocations against non-production AWS account
Configure MCP client (Claude Desktop) with server path
Deploy via Docker for isolated execution
Set up CloudTrail logging for API call auditing

Configuration / Environment Variables

Variable	Required	Default	Description
`AWS_ACCESS_KEY_ID`	Yes*	--	AWS access key ID (*if not using profile/role)
`AWS_SECRET_ACCESS_KEY`	Yes*	--	AWS secret access key
`AWS_REGION`	No	us-east-1	AWS region
`AWS_PROFILE`	No	--	AWS profile name

Deployment

Standalone

npm install
npm run build
npm start

Docker

docker build -t mcp-server-aws .
docker run \
  -e AWS_ACCESS_KEY_ID=xxx \
  -e AWS_SECRET_ACCESS_KEY=xxx \
  mcp-server-aws

Links

Repository	github.com/your-org/mcp-server-aws
README	README.md
License	MIT License