This repository contains sample implementations of MCP (Model Context Protocol) servers across multiple runtimes and deployment targets, including stateless and stateful variants. The stateless examples demonstrate horizontal scaling by running MCP servers that do not persist session context between requests, while the stateful examples illustrate how persistent sessions can be managed within a single instance. The included samples leverage common orchestrators and IaC tools (Terraform, AWS CDK, and SAM) to deploy servers on AWS services such as Lambda, API Gateway, and ECS. You can select a specific sample to study the MCP server implementation patterns, room on how to handle Streamable HTTP Transport, and how to set up SSE-based long-lived connections for real-time message streaming. Each folder provides its own deployment steps; for hands-on testing, pick a stateless Lambda or ECS example to quickly validate MCP interactions in a cloud environment. Tools available across the samples include MCP message handling, session management (stateless vs stateful), and transport compatibility with Streamable HTTP Transport.

Prerequisites:

• A modern Node.js and npm installation for Node-based samples
• Python 3.8+ for Python-based samples
• AWS CLI configured with appropriate permissions for deploying Lambda, ECS, API Gateway, and related resources
• Terraform, AWS CDK, or SAM installed if you plan to deploy via IaC as shown in the samples

Step-by-step:

1. Clone the repository: git clone <repository-url> cd <repository-root>

2. Choose a sample to explore (e.g., stateless-mcp-on-lambda-nodejs) and install dependencies: cd stateless-mcp-on-lambda-nodejs npm install

   or if the sample uses a Python layer, install via python package manager

3. Review the deployment tooling used in the sample:

   • If Terraform is used, ensure Terraform is installed and run the init/apply steps in the sample folder (e.g., terraform init && terraform apply).
   • If SAM is used, use sam build and sam deploy according to the folder’s README instructions.
   • If AWS CDK is used, install dependencies and run cdk bootstrap, cdk deploy as instructed in the sample.

4. Run the MCP server locally (if supported by the sample) or deploy to the cloud environment per the folder’s guidance. Typical local run (Node.js sample) might look like: node stateless-mcp-on-lambda-nodejs/server.js

5. Observe and test the MCP endpoints, ensuring the Streamable HTTP Transport connections (SSE) can be established and resumed per the MCP spec. Adjust environment variables as needed per your deployment (see mcp_config env placeholders).

Tips and common issues:

• Stateless vs Stateful: Stateless MCP servers scale horizontally but do not retain session state. If you need resumable sessions, consider a stateful setup or implement a manual session store (e.g., Redis) at the load balancer level.
• SSE connections: Long-lived HTTP GET requests are used to push messages. Ensure your environment and proxies allow persistent connections; some cloud load balancers or proxies may drop idle SSE connections.
• Environment variables: Each sample may require specific configuration (region, MCP ecosystem identifiers, or transport settings). The provided mcp_config includes placeholders; replace them with your actual deployment values.
• IaC tooling: The repo includes Terraform, SAM, and CDK examples. Use the tooling you are most comfortable with and align with your deployment target (Lambda, ECS, etc.).
• Node.js vs Python runtimes: Some samples mix runtimes (e.g., Node.js MCP with Python agents). Follow the folder README for the exact runtime expectations and integration steps.
• Logging and observability: Enable CloudWatch Logs (Lambda) or container logs (ECS) to monitor MCP message flows and session state transitions. Ensure appropriate IAM permissions for any resources your MCP servers access.