Lza

License Code of Conduct

A Model Context Protocol (MCP) server that enables AI-assisted management of Landing Zone Accelerator on AWS (LZA) deployments through compatible development tools and IDEs.

Documentation: Contributing | Code of Conduct | Security | Changelog | License

Table of Contents

• Overview
• Privacy Notice
• Quick Start
• Build Process
• AWS Permissions
• MCP Client Configuration
• Kiro IDE: Configuration Validation Hook
• Available Tools
• Schema Management
• Universal Configuration
• Configuration Operations
• Pipeline Management
  • Manual Approval (Optional)
• Advanced Topics
• Troubleshooting

Overview

The LZA MCP Server streamlines Landing Zone Accelerator on AWS operations by providing AI-powered assistance for configuration management, pipeline orchestration, and schema discovery. Organizations can reduce operational complexity and accelerate deployment cycles while maintaining security and compliance standards. The server includes specialized tools for merging LZA Universal Configuration templates, enabling rapid deployment of enterprise-ready, compliance-focused baseline environments.

Key Benefits:

• Accelerated Operations: AI-assisted configuration reduces manual effort and deployment time
• Enhanced Accuracy: Schema validation and intelligent search helping prevent configuration errors while providing a reliable tools to discover LZA capabilities
• Operational Visibility: Real-time pipeline monitoring with automated diagnostics
• Security by Design: Comprehensive input validation and least-privilege IAM policies
• Universal Configuration Integration: Streamlined merging of enterprise-ready compliance templates

Architecture: The server operates as a containerized MCP endpoint, invoked by compatible IDEs (Kiro, Claude Desktop) via stdio transport. All AWS operations use temporary credentials following AWS security best practices.

Back to top

Privacy Notice

⚠️ Data Sharing with AI Providers
This MCP server executes AWS API calls using your credentials and shares the response data with your third-party AI model provider (e.g., Kiro CLI, Claude Desktop, Cursor, VS Code, Kiro IDE). Users are responsible for understanding your AI provider's data handling practices and ensuring compliance with your organization's security and privacy requirements when using this tool with AWS resources.

Back to top

Quick Start

Prerequisites

• Container Runtime: Docker or Finch (the build process auto-detects which is available)
• AWS credentials with required IAM permissions
• MCP-compatible IDE (Kiro IDE, Claude Desktop)
• Existing LZA deployment (for pipeline and configuration operations)

📋 Supported LZA Deployments
This MCP server supports LZA deployments using S3-based or CodeCommit-based configuration storage. The default LZA deployment stores configuration files in an S3 bucket (aws-accelerator-config-*). When your pipeline uses CodeCommit as its source, getLzaConfiguration and putLzaConfiguration automatically detect this and use the CodeCommit API instead of S3 — no extra configuration required. You can also explicitly target a CodeCommit repository by passing repository_name (and optionally branch) to either tool.

1. Build Container Image

The build process automatically detects whether Docker or Finch is installed and uses the available runtime:

cd src/lza-mcp-server
make build

Using a specific runtime:

# Force Docker
make build CONTAINER_RUNTIME=docker

# Force Finch
make build CONTAINER_RUNTIME=finch

This generates a container image with embedded LZA schemas for versions v1.12.0 and later (mutable).

What if neither is installed?

The build will fail with a helpful error message directing you to installation resources:

• Docker: https://docs.docker.com/get-docker/
• Finch: https://github.com/runfinch/finch

2. Configure AWS Permissions

Create an IAM role or user with the recommended IAM policy. The policy follows least-privilege principles and supports standard LZA deployments.

⚠️ Security Recommendation
Use temporary credentials via AWS IAM Identity Center instead of long-term access keys. Temporary credentials reduce risk of credential exposure and align with AWS security best practices.

3. Configure AWS Credentials

The extract-aws-credentials.sh script handles credential extraction from your AWS CLI profile and passes them to the container. This script works with most AWS credential sources:

• Static credentials (access key/secret key)
• IAM Identity Center (SSO)
• IAM roles
• Credential process
• Temporary credentials

For IAM Identity Center users, login to your SSO session before starting the MCP server:

aws sso login --profile your-sso-profile

SSO sessions typically expire after 8-12 hours. If the MCP server reports authentication errors, re-run aws sso login to refresh your session.

The script uses aws configure export-credentials to retrieve temporary credentials from your active session and inject them into the container environment.

4. Configure MCP Client

Add the server configuration to your IDE's MCP settings file:

Kiro IDE: .kiro/settings/mcp.json (workspace) or ~/.kiro/settings/mcp.json (global)
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{
  "mcpServers": {
    "awslabs.lza-mcp-server": {
      "command": "<REPO_PATH>/scripts/extract-aws-credentials.sh",
      "args": [
        "docker", "run",
        "--security-opt=no-new-privileges:true",
        "--cap-drop=ALL",
        "--read-only",
        "--tmpfs", "/tmp:rw,noexec,nosuid,size=200m",
        "--rm", "-i",
        "-v", "<CONFIG_PATH>:/app/lza-config:rw",
        "-e", "LZA_CONFIG_HOST_PATH=<CONFIG_PATH>",
        "-e", "AWS_ACCESS_KEY_ID",
        "-e", "AWS_SECRET_ACCESS_KEY",
        "-e", "AWS_SESSION_TOKEN",
        "-e", "AWS_REGION",
        "lza-mcp-server:local"
      ],
      "env": {
        "AWS_PROFILE": "<YOUR_AWS_PROFILE>",
        "AWS_REGION": "<YOUR_AWS_REGION>"
      }
    }
  }
}

Note: To use Finch instead of Docker, replace "docker" with "finch" in the args array.

Configuration Parameters:

• <REPO_PATH>: Full path to cloned repository (e.g., /Users/username/repos/lza-mcp-server)
• <CONFIG_PATH>: Local directory for configuration files (e.g., /Users/username/Documents/lza-config)
  • Recommendation: Place within your IDE workspace for easier file access (e.g., .kiro/lza-config for Kiro IDE)
• <YOUR_AWS_PROFILE>: AWS CLI profile name from ~/.aws/credentials or ~/.aws/config
• <YOUR_AWS_REGION>: AWS region where LZA is deployed (e.g., us-east-1)

Optional Environment Variables:

You can customize the MCP server behavior by adding environment variables to the env section:

"env": {
  "AWS_PROFILE": "<YOUR_AWS_PROFILE>",
  "AWS_REGION": "<YOUR_AWS_REGION>",
  "LZA_PREFIX": "AWSAccelerator",
  "LOG_INSTRUCTIONS": "false",
  "DISABLE_LLM_GUIDANCE": "false"
}

• LZA_PREFIX: The prefix used by your LZA deployment for resource naming (default: AWSAccelerator)
  • LZA uses this prefix to name resources like pipelines, CloudFormation stacks, and SSM parameters
  • If you customized the prefix during LZA installation, set this to match your deployment
  • Example: If your pipeline is named MyOrg-Pipeline, set LZA_PREFIX="MyOrg"
  • This affects:
    • Pipeline name: {LZA_PREFIX}-Pipeline
    • SSM parameter: /accelerator/{LZA_PREFIX}-InstallerStack/version
    • CloudFormation stacks: {LZA_PREFIX}-*
• LOG_INSTRUCTIONS: Enable logging of MCP server instructions at startup (default: false)
  • Set to true, 1, or yes to enable instruction logging
  • Useful for debugging or understanding what instructions are provided to the AI model
  • Instructions are logged at INFO level and include all guidance provided to the model
• DISABLE_LLM_GUIDANCE: Disable LLM guidance in tool responses and server instructions (default: false)
  • Set to true to strip guidance keys (llm_instructions, next_steps, hint, required_action, instructions_for_assistant, example, troubleshooting, usage_hint) from all tool responses
  • Also disables the server-level instructions passed to FastMCP, returning an empty string
  • Designed for deployments where an external entity owns workflow orchestration outside of the LZA MCP Server
  • When disabled, tool responses contain only operational data (success, error, data, etc.)

Note: The credential extraction script requires your AWS CLI profile to be ready for use. Complete any profile-specific prerequisites before starting your LZA MCP server (e.g., aws sso login for IAM Identity Center profiles).

4. Verify Installation

Restart your IDE and test connectivity:

Use your tools, check my AWS connectivity

The server will verify credentials and report the authenticated identity.

Back to top

Build Process

Schema Generation

The container build includes automated schema processing that powers the schema search and discovery tools. This process runs once during make build and takes approximately 30-60 seconds.

What happens during build:

1. Fetch LZA Releases: Queries GitHub API for available LZA versions
2. Clone Source: Downloads LZA source code for each version
3. Extract Schemas: Copies JSON schemas from source/packages/@aws-accelerator/config/lib/schemas
4. Process Schemas: Resolves $ref references and generates search metadata
5. Embed in Image: Creates version-specific directories at /app/json-schemas/{version}/

Schema enhancements:

• Reference Resolution: All $ref pointers resolved for self-contained schemas
• Search Metadata: Pre-computed indexes for property names, types, patterns, and relationships
• Statistics: Property counts, nesting depth, and complexity metrics

This preprocessing enables sub-second schema searches without runtime analysis overhead.

Build Customization

Control which LZA versions and UC releases are included in the container:

# Default build (v1.12.0 to latest LZA, latest UC) - auto-detects runtime
make build

# Custom LZA version range using Makefile
make build LZA_MIN_VERSION=v1.10.0 LZA_MAX_VERSION=v1.14.0

# Direct build with specific runtime (replace 'docker' with 'finch' if needed)
docker build \
  --build-arg LZA_MIN_VERSION=v1.11.0 \
  --build-arg LZA_MAX_VERSION=v1.13.0 \
  --build-arg LZA_UC_RELEASE=v1.0.0 \
  -t lza-mcp-server:local .

Note: The Makefile auto-detects Docker or Finch. For direct builds, replace docker with finch if using Finch.

Build Arguments:

Argument	Default	Purpose
LZA_MIN_VERSION	v1.12.0	Earliest LZA version to include
LZA_MAX_VERSION	latest	Latest LZA version to include
LZA_UC_RELEASE	latest	Universal Configuration release version

Note: Including more versions increases build time and image size proportionally. Most users only need schemas matching their deployed LZA version.

Back to top

AWS Permissions

The MCP server requires specific IAM permissions for LZA operations. This policy follows AWS least-privilege principles.

🔒 Privacy Consideration
AWS API responses retrieved using these permissions will be shared with your AI model provider. Review your organization's data classification policies before granting access to sensitive AWS resources.

Recommended IAM Policies

Choose the policy that matches your LZA deployment type. All policies follow AWS least-privilege principles.

Deployment Type	Description	Policy
Standard CodePipeline	Default LZA deployment in the management account using CodePipeline and CodeBuild. This is the most common setup.	standard-codepipeline-policy.json
External Pipeline — CodePipeline	LZA deployed from a separate orchestration account using CodePipeline with an Accelerator Qualifier. Includes SSM Automation permissions for triggering deployments.	external-codepipeline-policy.json
External Pipeline — ECS Container	LZA deployed from a separate orchestration account using ECS Fargate tasks with an Accelerator Qualifier. Includes ECS task monitoring, CloudWatch Logs for ECS, and SSM Automation permissions.	external-ecs-container-policy.json

Policy Variables

Replace these placeholders with your deployment values:

All policies:

• ${HOME-REGION}: AWS region where LZA is deployed (e.g., us-east-1)
• ${PARTITION}: AWS partition (aws, aws-us-gov, or aws-cn)

Standard CodePipeline:

• ${MANAGEMENT_ACCOUNT}: AWS management account ID (12-digit number)
• ${ACCELERATOR_PREFIX}: LZA resource prefix (default: aws-accelerator)

External Pipeline (CodePipeline and ECS Container):

• ${ORCHESTRATION_ACCOUNT}: AWS orchestration account ID where the external pipeline runs (12-digit number)
• ${QUALIFIER}: Accelerator Qualifier set during LZA container/external deployment (e.g., my-lza)

Permission Scope

Service	Purpose	Reference
STS	Identity verification for connectivity checks	AWS STS Documentation
SSM	Retrieve deployed LZA version, discover deployment qualifiers, and scan version parameters from Parameter Store	AWS Systems Manager Parameters
SSM Automation	Start and monitor LZA deployments via SSM Automation documents (external pipelines only)	SSM Automation
S3	Read/write LZA configuration files in config bucket (S3-backed deployments)	S3 Bucket Policies
CodeCommit	Read and write LZA configuration files when the pipeline uses a CodeCommit source (GetFolder, GetBlob, GetBranch, CreateCommit); GetPipeline is used to auto-detect the source type	AWS CodeCommit
KMS	Encrypt/decrypt configurations using LZA KMS key	AWS KMS Key Policies
CodePipeline	Monitor and trigger LZA pipeline executions; list pipelines for deployment type detection (external pipelines); inspect source action to auto-detect CodeCommit repositories	CodePipeline Monitoring
CodeBuild	Retrieve build project details for diagnostics (CodePipeline deployments only)	CodeBuild Projects
ECS	List clusters for deployment type detection; monitor ECS Fargate task status (ECS container deployments)	Amazon ECS
CloudWatch Logs	Access build or deployment logs for error analysis	CloudWatch Logs

Note: The KMS policy uses alias-based access control (kms:ResourceAliases) for maintainability. This approach allows key rotation without policy updates, following AWS KMS best practices.

CodeCommit Configuration Source

If your LZA pipeline uses CodeCommit as its source, the CodeCommitConfigAccess statement included in the standard and external CodePipeline policies grants the required permissions. Replace ${REPOSITORY_NAME} with your CodeCommit repository name (e.g., aws-accelerator-config).

Action	Purpose
codecommit:GetFolder	Walk the repository directory tree to list up to 1,000 items
codecommit:GetBlob	Fetch individual file contents by blob ID
codecommit:GetBranch	Retrieve the HEAD commit ID before writing
codecommit:CreateCommit	Commit all configuration files in a single operation

The codepipeline:GetPipeline permission (already present in both CodePipeline policies) is used to auto-detect whether the pipeline's source action is CodeCommit — no additional permissions are needed for auto-detection.

Note: CodeCommit is not applicable to ECS container deployments, which always use S3 for configuration storage.

Back to top

MCP Client Configuration

Configuration File Locations

IDE	Configuration Path
Kiro IDE	.kiro/settings/mcp.json (workspace) ~/.kiro/settings/mcp.json (global)
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

Complete Configuration Example

{
  "mcpServers": {
    "awslabs.lza-mcp-server": {
      "command": "/Users/jsmith/repos/lza-mcp-server/scripts/extract-aws-credentials.sh",
      "args": [
        "docker", "run",
        "--security-opt=no-new-privileges:true",
        "--cap-drop=ALL",
        "--read-only",
        "--tmpfs", "/tmp:rw,noexec,nosuid,size=200m",
        "--rm", "-i",
        "-v", "/Users/jsmith/Documents/lza-config:/app/lza-config:rw",
        "-e", "LZA_CONFIG_HOST_PATH=/Users/jsmith/Documents/lza-config",
        "-e", "AWS_ACCESS_KEY_ID",
        "-e", "AWS_SECRET_ACCESS_KEY",
        "-e", "AWS_SESSION_TOKEN",
        "-e", "AWS_REGION",
        "-e", "FASTMCP_LOG_LEVEL=INFO",
        "-e", "ENABLE_UC_MERGE=false",
        "lza-mcp-server:local"
      ],
      "env": {
        "AWS_PROFILE": "lza-role-mcp-policy-attached",
        "AWS_REGION": "us-east-1"
      },
      "disabled": false,
      "autoApprove": [
        "checkAwsConnectivity",
        "listLzaSupportedVersions",
        "searchJsonSchema",
        "getFullSchema",
        "getDeploymentStatus",
        "getLzaConfiguration"
      ]
    }
  }
}

Security Flags

The configuration includes container security hardening:

• --security-opt=no-new-privileges:true: Prevents privilege escalation
• --cap-drop=ALL: Removes all Linux capabilities
• --read-only: Makes root filesystem read-only
• --tmpfs /tmp: Provides writable temp space with noexec

These flags mitigate container escape vulnerabilities. Keep Docker/Finch updated for latest security patches.

Environment Variables

Variable	Purpose	Example
LZA_CONFIG_HOST_PATH	Local path for configuration files (must match volume mount)	/Users/jsmith/Documents/lza-config
AWS_PROFILE	AWS CLI profile name for role with LZA MCP policy attached	lza-role-mcp-policy-attached
AWS_REGION	Default AWS region	us-east-1
FASTMCP_LOG_LEVEL	Logging verbosity	INFO, DEBUG
ENABLE_UC_MERGE	Enable Universal Configuration merge tools	false (default), true
LOG_INSTRUCTIONS	Log MCP server instructions at startup	false (default), true
DISABLE_LLM_GUIDANCE	Strip LLM guidance keys from tool responses and disable server instructions. Use when an external entity owns workflow orchestration outside of the LZA MCP Server	false (default), true
ENABLE_S3_DIFF	Enable S3 diff retrieval in deployment status (planned future LZA feature)	false (default), true

Note: Setting ENABLE_UC_MERGE=true enables 9 additional tools for UC merge workflows but consumes more of the available context window. Only enable this when you need UC merge functionality to keep context usage efficient.

Auto-Approved Tools

The autoApprove list includes read-only operations that don't modify AWS resources:

• Configuration retrieval and inspection
• Schema searches and discovery
• Pipeline status monitoring
• AWS connectivity verification

Tools that modify resources (startDeployment, uploadConfigurationToS3) require explicit approval for safety.

Kiro IDE: Configuration Validation Hook

For Kiro IDE users, a recommended agent hook is provided at hooks/lza-config-validation.kiro.hook. This hook triggers on every prompt and ensures the agent validates all LZA configuration changes against the correct schema before suggesting them — preventing invalid properties or values from reaching your pipeline.

Installation:

Copy the hook file into your workspace's .kiro/hooks/ directory:

cp hooks/lza-config-validation.kiro.hook .kiro/hooks/

Once in place, the hook automatically instructs the agent to call getDeployedLzaVersion() and searchJsonSchema()/getFullSchema() before suggesting any changes to LZA configuration files (accounts-config.yaml, network-config.yaml, global-config.yaml, iam-config.yaml, security-config.yaml, organization-config.yaml).

Schema Integrity Validation

The server validates schema integrity at startup using SHA-256 checksums. This protects against tampering or corruption of embedded LZA schemas. If validation fails, the server refuses to start with a clear error message.

Back to top

Available Tools

AWS Services

checkAwsConnectivity
Verifies AWS credentials and reports authenticated identity. Use this to confirm AWS connectivity with a IAM credentials before performing operations.

getDeployedLzaVersion
Retrieves the currently deployed LZA version from SSM Parameter Store. Use this to identify the correct schema version for searches.

Configuration Management

getMinimumConfiguration
Generates minimal LZA configuration templates for new deployments. Templates include required accounts and baseline settings.

getLzaConfiguration
Retrieves current LZA configuration for inspection or modification. Automatically selects the config source: if the pipeline's source action is CodeCommit (or repository_name is provided), files are fetched via the CodeCommit API; otherwise a ZIP is downloaded from S3. Supports standard and external pipeline deployments via qualifier. Accepts optional repository_name and branch parameters to target a specific CodeCommit repository directly.

putLzaConfiguration
Uploads configuration files back to the LZA config source. Automatically selects the destination: CodeCommit (single CreateCommit with all files) or S3 (ZIP upload), matching the source used by getLzaConfiguration. Supports standard and external pipeline deployments via qualifier. Accepts optional repository_name, branch, and commit_message parameters for CodeCommit destinations.

readLzaConfigFile
Reads a file from the extracted LZA configuration directory. Validates paths for security and provides context-aware guidance.

updateLzaConfigFile
Updates an LZA configuration file in the extracted configuration directory. Supports three mutually exclusive modes: updating existing values via dot-notation paths, inserting new items into YAML lists, or deleting keys/list items. Includes validation for CIDR ranges, ASN values, and VPC mask lengths.

createLzaConfigFile
Creates a new YAML or JSON configuration file in the extracted LZA configuration directory. Useful for adding IAM policy files (JSON), custom configuration files, or any additional files needed by the LZA configuration. Supports configurable JSON indentation.

Pipeline Management

startDeployment
Starts an LZA deployment. Supports standard CodePipeline, external CodePipeline ({qualifier}-pipeline), and ECS container deployments ({qualifier}-RunEngine SSM Automation). When a qualifier is provided, checks both CodePipeline and SSM Automation and starts whichever exists.

getDeploymentStatus
Monitors deployment status and execution progress. Supports both standard CodePipeline and ECS container deployments. Returns real-time status for all pipeline stages, and when a qualifier is provided, checks both CodePipeline and ECS container logs. Also detects pending approval actions and returns the approval token, stage name, action name, review diff, and change context.

diagnoseDeploymentErrors
Diagnoses failed LZA deployments. Supports both standard CodePipeline and ECS container deployments. Analyzes logs and provides troubleshooting guidance.

submitManualApproval
Approves or rejects a pending manual approval action. Requires the approval_token, approval_stage_name, and approval_action_name from getDeploymentStatus.

Schema Search

listLzaSupportedVersions
Lists all LZA versions with embedded schemas. Use this to identify the correct version for schema searches.

searchJsonSchema
Searches LZA configuration schemas by property names, patterns, or complexity. Requires explicit lza_version parameter.

getFullSchema
Retrieves complete schema definitions or specific properties. Supports filtering by property path for targeted queries.

Universal Configuration Merge (Optional)

Enable with ENABLE_UC_MERGE=true to access UC merge workflow tools:

• validateLzaForUcMerge: Validate LZA installation compatibility
• get_uc_releases: Discover available UC release versions
• get_uc_network_models: Compare network deployment models
• start_uc_merge_session: Initialize UC merge session
• readUcFile: Read UC files from merge session
• updateUcFile: Update UC files in merge session
• getUcNetworkCustomizationGuide: Get customization guidance
• copyUcToLzaConfig: Copy UC configuration to LZA directory

Back to top

Schema Management

Schemas are generated during container build. See Build Process for build details and customization options.

Multi-Version Support

The server supports multiple LZA versions simultaneously:

• Search schemas for specific versions
• Compare configurations across releases
• Match schemas to deployed LZA version
• Access latest LZA schemas automatically

File Structure

/app/json-schemas/
├── v1.12.0/
│   ├── accounts-config-schema.json
│   ├── global-config-schema.json
│   ├── iam-config-schema.json
│   ├── network-config-schema.json
│   ├── organization-config-schema.json
│   ├── security-config-schema.json
│   └── combined.json
├── v1.13.0/
│   └── ...
└── v1.14.0/
    └── ...

Using Schema Tools

All schema tools require explicit version specification: