CloudAgent Deploy MCP Server

An MCP (Model Context Protocol) server for deploying CloudFormation infrastructure via backend API. This server eliminates the need for local AWS credentials by routing all CloudFormation operations through a secure backend API with cross-account role assumption.

Features

• 🔐 No Local AWS Credentials Required - All operations use backend API with cross-account role assumption
• 🏗️ Full CloudFormation Support - Deploy, validate, delete, and monitor stacks
• ⚡ Advanced Validation - Security and compliance rules with property suggestions
• 📋 Stack Management - List stacks, get status, and track outputs
• 🎯 Smart Detection - Automatically detects CloudFormation templates in projects
• 🌐 Static Site Support - Handles both infrastructure and static deployments

Installation

cd cloudagent-deploy
npm install
npm run build

Configuration

Environment Variables (Recommended)

export CLOUDAGENT_API_ENDPOINT="https://your-api-gateway-url.execute-api.region.amazonaws.com/prod"
export CLOUDAGENT_API_KEY="your-api-key-here"
export CLOUDAGENT_PROJECT_ROOT="/path/to/your/projects"  # Optional

Configuration File

Create .cloudagent-deploy.json in your project directory:

{
  "apiEndpoint": "https://your-api-gateway-url.execute-api.region.amazonaws.com/prod",
  "apiKey": "your-api-key-here",
  "projectRoot": "/path/to/your/projects"
}

Usage

MCP Tools Available

1. deploy

Deploy a project to the cloud. Automatically detects CloudFormation templates and provides appropriate deployment options.

Parameters:

• directory (required): Full absolute path to project directory
• outputDir (optional): Relative path to build output directory
• projectName (optional): Name for the deployment

2. validate-infrastructure

Validate CloudFormation templates against security and compliance rules.

Parameters:

• template (required): CloudFormation template content (YAML or JSON)
• stackName (required): Name for the CloudFormation stack

3. deploy-infrastructure

Deploy CloudFormation templates via backend API.

Parameters:

• template (required): CloudFormation template content
• stackName (required): Name for the CloudFormation stack
• parameters (optional): Stack parameters
• tags (optional): Stack tags
• capabilities (optional): CloudFormation capabilities

4. delete-infrastructure

Delete CloudFormation stacks.

Parameters:

• stackName (required): Name of stack to delete

5. get-stack-status

Get status and outputs of CloudFormation stacks.

Parameters:

• stackName (required): Name of stack to check

6. list-stacks

List all CloudFormation stacks.

Parameters: None

Backend API Integration

This MCP server integrates with a backend CloudFormation API that provides:

• Cross-Account Role Assumption: No local AWS credentials needed
• Advanced Validation: Security rules and property suggestions
• Stack Lifecycle Management: Create, update, delete, monitor
• User Authentication: API key-based access control

API Endpoints Used

• POST /cfn/validate - Validate CloudFormation templates
• POST /cfn/deploy - Deploy CloudFormation stacks
• POST /cfn/delete - Delete CloudFormation stacks
• GET /cfn/status - Get stack status and outputs
• GET /cfn/list - List user's stacks

Security Features

• 🔐 No Local Credentials: All AWS operations via backend API
• 🛡️ Role-Based Access: Cross-account IAM role assumption
• 🔍 Template Validation: Security and compliance checks
• 📝 Audit Trail: All operations logged via backend
• 🎯 Scoped Permissions: Limited to CloudFormation operations

Development

# Watch mode for development
npm run dev

# Build for production
npm run build

# Test the server
npm test

Example Usage in Cursor

1. Configure your API endpoint and key
2. Open a project with CloudFormation templates
3. Use MCP tools to validate and deploy infrastructure
4. Monitor stack status and outputs
5. Delete stacks when no longer needed

Troubleshooting

Configuration Issues

• Ensure CLOUDAGENT_API_ENDPOINT and CLOUDAGENT_API_KEY are set
• Verify API endpoint URL is correct
• Check API key has valid permissions

Validation Errors

• Review CloudFormation template syntax
• Address security and compliance warnings
• Use property suggestions from validation output

Deployment Failures

• Check CloudFormation stack events in AWS console
• Verify IAM permissions for backend role
• Review template resource configurations

Architecture

MCP Client (cloudagent-deploy) 
    ↓ HTTP/HTTPS
Backend API Gateway
    ↓ Lambda Invocation  
CloudFormation Lambda Function
    ↓ STS AssumeRole
User's AWS Account
    ↓ CloudFormation API
AWS Resources (S3, EC2, RDS, etc.)

This architecture ensures enterprise-grade security while providing a seamless deployment experience without local AWS credential management.