Implementing Nova Act MCP Server on ECS Fargate

This technical blog post outlines the implementation of a Model Context Protocol (MCP) server for Amazon Nova Act on Amazon ECS Fargate platform as a container, providing browser automation capabilities as a service.

Introduction

Amazon Nova Act is an early research preview AI model and SDK designed to enable developers to build reliable web agents that can perform actions within a web browser. By integrating Nova Act with the Model Context Protocol (MCP), its browser automation capabilities can be standardized and exposed to diverse clients (e.g., AI assistants, web UIs, IDE extensions) through multiple communication channels:

Standard I/O (stdio) for local scripting and CLI tools like Amazon Q Developer CLI & Cline VS Code Extension (open-source)
Server-Sent Events (SSE) via HTTP connection for real-time, bidirectional communication
Streaming HTTP transport (this was recently introduced in the latest MCP specification) for scalable web-based interactions

This implementation deploys Nova Act as a containerized service on Amazon ECS fronted by ALB and uses Server-Sent Events (SSE) via HTTP connection to enable real-time communication.

Note: Amazon Nova Act is only available in the US to request for an API Key, and hence the solution is deployed on AWS in us-east-1 region to ensure compliance.

Architecture Overview

The solution consists of the following components:

MCP Server: A FastAPI application that implements the Model Context Protocol and exposes Nova Act functionality by using FastAPI-MCP
Streamlit Client: A web UI and MCP Client for interacting with the MCP server
AWS Infrastructure: ECS Fargate tasks, ALB, and supporting resources

Deployment Guide

Prerequisites

Before deploying the Nova Act MCP server on ECS, ensure you have:

AWS CLI configured with appropriate credentials
Node.js and npm installed
AWS CDK installed (npm install -g aws-cdk)
Docker installed and running
A valid Nova Act API key

Step 1: Clone the Repository

git clone https://github.com/awsdataarchitect/nova-act-ecs.git

cd nova-act-ecs

Step 2: Export your API Key as environment variable

export NOVA_ACT_API_KEY = your-api-key-here

Step 3: Deploy the CDK Stack

npm install
cdk bootstrap
cdk deploy

Step 4: Access the Application

After deployment completes, the CDK will output the ALB DNS name. You can access:

MCP Server: http://<alb-dns-name>/mcp
Streamlit UI: http://<alb-dns-name>:8501

MCP Server Implementation

The server implements the MCP protocol using fastapi_mcp with the following components:

MCP Endpoints (automatically handled by fastapi_mcp):
- /mcp - SSE endpoint for event streaming
- /mcp/schema - Schema endpoint for method discovery
- /mcp/jsonrpc - JSON-RPC endpoint for method calls
Core API Endpoint:
- /browse - Combined endpoint for all browser automation tasks
Additional Endpoints:
- /health - Used by ALB for health checks
- /logs - Endpoint to retrieve recent server logs

The "browse" Method

The implementation uses a simplified approach with a single "browse" method that combines browser control and instruction execution:

Request Schema

The browse method accepts a flexible request schema that can handle various browsing scenarios:

Response Schema

The response includes detailed information about the browsing session:

Server Features

Single Global Browser Instance: The server maintains a single global Nova Act instance
Headless Mode: Browser always runs in headless mode for ECS compatibility
API Key Management: Retrieves API key from environment variables or AWS Secrets Manager
Structured Data Extraction: Supports schema-based data extraction
Error Handling: Comprehensive error handling and logging
Thread Pool Execution: Runs synchronous Nova Act code in a thread pool to avoid asyncio conflicts
Resource Monitoring: Monitors system resources (CPU, memory) for debugging
Log Buffering: Maintains a circular buffer of recent logs for client display
Console Output Capture: Captures all stdout/stderr output including Nova Act's thinking steps

Key Implementation Details

The server uses a thread pool to run synchronous Nova Act code without blocking the FastAPI event loop:

The server also implements a log capture mechanism to provide real-time logs to clients, including stdout/stderr interception to capture Nova Act's thinking process:

For the full server implementation, see the GitHub repository.

MCP Client Implementation

The client implementation provides a Python interface to the Nova Act MCP server. I've implemented a synchronous (requests) version as its more stable in the Streamlit environment.

Client Features

Connection Management:
- Connects to the server's health endpoint to verify availability
- Manages an HTTP session for all requests
- Handles connection errors gracefully
API Method:
- browse(starting_url, instructions, max_steps_per_instruction, timeout_per_instruction, schema, headless) - Execute a browsing task
Error Handling:
- Proper error propagation
- Detailed error messages
- Connection retry logic
Log Retrieval:
- get_logs(limit) - Retrieve recent server logs

Synchronous Client Implementation

For the full client implementation, see the GitHub repository.

Streamlit UI Implementation

The Streamlit UI provides a user-friendly interface to the Nova Act MCP server:

UI Features

Single Form Interface: Combines URL and instruction inputs in one form
Schema Builder: UI for creating extraction schemas (Boolean, Text, Product Info, List Items, Custom)
Execution Options: Configure max steps and timeout
Result Display: Formatted display of execution results and parsed responses
History Tracking: Maintains a record of previous operations and results
Live Logs Display: Shows real-time server logs in a scrollable window
Amazon-Specific Examples: Pre-configured examples for common Amazon shopping tasks

Live Logs Display

A key feature of the UI is the live logs display, which shows the server's output in real-time, including Nova Act's thinking process:

This feature helps users understand what's happening behind the scenes, especially during long-running operations:

Debugging: See exactly what Nova Act is doing in real-time
Progress Tracking: Monitor the progress of browser automation tasks
Error Identification: Quickly identify issues when operations fail
Transparency: Understand the steps Nova Act takes to complete instructions

UI Screenshot

For the full UI implementation, see the GitHub repository.

AWS CDK Infrastructure

The AWS CDK infrastructure code creates all the necessary resources for deploying the Nova Act MCP server and client on Amazon ECS.

Infrastructure Components

VPC and Networking:
- VPC with public subnets
- Internet Gateway
- Security Groups for ECS tasks and ALB
ECS Resources:
- ECS Cluster
- Fargate Task Definitions for server and client
- ECS Services for server and client
Load Balancing:
- Application Load Balancer (ALB) with increased idle timeout (300 seconds)
- Target Groups for server and client with increased deregistration delay
- Listener Rules for routing traffic
Storage and Secrets:
- ECR Repository for Docker images
- Secrets Manager for API key storage

ALB Configuration for Long-Running Operations

To support long-running operations and SSE connections, the ALB is configured with extended timeouts:

For the full infrastructure implementation, see the GitHub repository.

Integration with VS Code Cline Extension

The Nova Act MCP server can also be used with the VS Code Cline extension:

Install the Cline extension from the VS Code marketplace
Configure the extension to use your MCP server:

This configuration enables the browse MCP tool in Cline, allowing you to execute browser automation tasks directly from your IDE as shown below:

Troubleshooting

Connection Issues

ALB Connection Timeouts:
- Check ALB security group allows inbound traffic on port 80
- Verify that the ALB health checks are passing
- Ensure the ECS tasks are running and registered with the target group
- Important: For SSE (Server-Sent Events) connections, increase the ALB idle timeout (default is 60 seconds)
- Configure the ALB target group's deregistration delay to match long-running operations
API Key Issues:
- Verify the API key is correctly stored in Secrets Manager
- Check server logs for API key retrieval errors
- Ensure the ECS task role has permission to read the secret
Browser Control Issues:
- Check server logs for browser initialization errors
- Verify that Playwright is correctly installed in the container
- Ensure the ECS task has sufficient memory and CPU resources

Handling 504 Gateway Timeout Errors

The Nova Act MCP server uses Server-Sent Events (SSE) for real-time communication, which can lead to 504 Gateway Timeout errors from the ALB if operations take longer than the default timeout settings. To address this:

Increase ALB Idle Timeout:

Implement Client-Side Retry Logic:

Use Synchronous Client in Streamlit:

If you're experiencing "Timeout context manager should be used inside a task" errors in Streamlit, switch to the synchronous client implementation using the requestslibrary instead of aiohttp (I was using aiohttp earlier, but is not used in this current version).

Cleanup

To delete all AWS resources provisioned via CDK, run:

cdk destroy

This ensures that no unnecessary infrastructure is left running and helps avoid additional costs.

Conclusion

This implementation of a Nova Act MCP server on Amazon ECS provides a scalable, containerized solution for browser automation. By leveraging the Model Context Protocol and a simplified API with a single "browse" method, it enables seamless integration with various clients, including AI assistants, Streamlit UIs, VS Code extensions (Cline, Cursor), and hopefully soon with the Amazon Q Developer CLI. Currently at the time of writing, Amazon Q Developer CLI only supports MCP tools that are hosted locally via stdio protocol and does not support MCP tools via sse over http protocol.

Although I haven't tried the other popular MCP supported clients like Claude Code, Claude for Desktop, LibreChat, LangChain (MCP adapter module), and JetBrains with Cascade/Windsurf, I invite you to test the Nova Act MCP server using these MCP clients and let me know your feedback.

Key benefits of this architecture include:

Simplicity: A single method handles all browser automation tasks
Scalability: ECS Fargate services can scale based on demand
Security: API keys are securely stored in AWS Secrets Manager
Reliability: Health checks and auto-healing ensure high availability
Monitoring: CloudWatch integration provides visibility into performance
Transparency: Real-time logs show Nova Act's thinking process
Integration: Works with VS Code Cline extension

This solution can be extended to support multiple concurrent browser sessions, additional automation capabilities, and integration with other AWS services like Step Functions for complex workflows.

Site Terms, Privacy, and more.