DOCSEARCHbyAlgolia
Submit Docs

Sample Serverless Model Context Protocol (MCP) Servers

repository·main·Indexed 42 days ago

https://github.com/aws-samples/sample-serverless-mcp-servers

A collection of sample implementations for Model Context Protocol (MCP) Servers running on AWS serverless and containerized services, including AWS Lambda and ECS. Features an Agent-to-Agent (A2A) communication system using Python, LangGraph, and AWS Bedrock, supporting asynchronous workflows with push notifications via webhooks.

Tokens
28.5K
Snippets
91
Records
125
Agent score
53%

What's inside Sample Serverless MCP Servers

  1. Overview of A2A Lambda Python - Async with Push Notifications

    main
    A2A (Agent-to-Agent) Lambda Python is an advanced communication system designed for asynchronous AI agent collaboration. It uses the A2A protocol to allow a client agent to send long-running tasks to a server agent via HTTP APIs. Instead of waiting for a response, the client provides a webhook URL, and the server pushes real-time updates (status changes and task artifacts) back to the client as the task progresses. This is built using AWS Lambda, API Gateway, LangGraph, and the A2A SDK.

  2. Overview of Lambda Ops MCP Server capabilities

    main

    The Lambda Ops MCP Server is designed to support AWS Lambda operational tasks through an MCP-compatible interface. Its primary capabilities include:

    • Discovery: Identifying Lambda functions running on deprecated or soon-to-be-deprecated runtimes.
    • Upgrades: Providing a workflow to upgrade functions to supported runtime versions.

    This implementation is intended as a template that can be extended to support other operational scenarios required by your environment.

  3. Overview of Sample Serverless MCP Servers

    main

    This repository provides various sample implementations of Model Context Protocol (MCP) Servers designed for serverless and containerized environments on AWS. The samples cover different runtimes (Python, Node.js) and deployment models (Lambda, ECS) using Infrastructure as Code (Terraform, CDK, SAM).

    Available Samples

    DirectoryRuntimeIaCDescription
    strands-agent-on-lambdaPython (Agent), Node.js (MCP)Terraform, CDKAI Agent using Strands Agents SDK + MCP Server on AWS Lambda with Cognito authentication
    strands-agent-on-lambda-pythonPythonSAMAI Agent using Strands Agents SDK on AWS Lambda
    stateless-mcp-on-lambda-nodejsNode.jsTerraformRemote stateless MCP Server on AWS Lambda and Amazon API Gateway
    stateless-mcp-on-lambda-pythonPythonSAMRemote stateless MCP Server on AWS Lambda and Amazon API Gateway
    stateless-mcp-on-ecs-nodejsNode.jsTerraformRemote stateless MCP Server on Amazon ECS with Application Load Balancer
    stateful-mcp-on-ecs-nodejsNode.jsTerraformRemote stateful MCP Server on Amazon ECS with Application Load Balancer
    stateful-mcp-on-ecs-pythonPythonSAMRemote stateful MCP Server on Amazon ECS with Application Load Balancer
    lambda-ops-mcp-serverNode.jsTerraformLocal MCP Server PoC for discovering and upgrading functions on deprecated runtimes

  4. Understand the MCP server operating modes in `src/mcpserver/server.py`

    main

    The src/mcpserver/server.py file supports three distinct operating modes via the --mode flag:

    1. --mode stdio: Uses the STDIO transport. This is intended for local testing.
    2. --mode streamable-http: Uses Streamable HTTP transport via a FastMCP server.
      • Example endpoint: https://<api-id>.execute-api.<region>.amazonaws.com/dev/mcp/
    3. --mode fastapi: Attaches the FastMCP server to a FastAPI (WSGI) server using a mount point.
      • Example endpoint: https://<api-id>.execute-api.<region>.amazonaws.com/dev/mountpoint/mcp/

    Modes 2 and 3 are functionally similar to the client, but mode 3 introduces an additional path component (the mount point) into the URL.

  5. Understand Stateful vs Stateless MCP Server modes

    main

    MCP Servers can operate in two modes. This project implements the Stateful mode.

    Stateful Mode

    Stateful mode uses a persistent SSE (Server-Sent Events) connection between the MCP Client and the MCP Server. This allows the server to support resumability and proactively send notifications to clients.

    Key Constraints & Solutions:

    • Scaling Limitation: Because the TypeScript MCP Server SDK does not currently support externalizing session info, sessions cannot be synchronized across multiple server instances. If you have multiple ECS tasks, a client session established with one task might fail if subsequent requests hit a different task.
    • Sticky Sessions Solution: To use multiple ECS tasks, you must use an Application Load Balancer (ALB) with cookie-based sticky sessions.
    • Client Support: Since the standard MCP Client SDK does not support cookies by default, this project implements a workaround by injecting cookie support into fetch within src/mcpclient/index.js.

    Stateless Mode

    Stateless mode does not rely on persistent SSE connections for session state, making it easier to scale horizontally across multiple instances without sticky sessions.

  6. How authentication and authorization work in this project

    main

    The system uses a dual-token JWT (bearer token) approach enforced by API Gateway Lambda authorizers to ensure user identity is propagated without relying on LLM responses.

    AI Agent Authorization

    • Provider: HashiCorp Vault OIDC.
    • Token: JWT issued by Vault OIDC where the sub (subject) claim is the user.
    • Validation: Performed by the agent-authorizer using JWKs from the authentication provider.

    Bookings MCP Authorization

    • Provider: Strands Agent.
    • Token: JWT signed by a shared secret. The sub claim is the agent, and the user_id is included as an extra claim.
    • Validation: Performed by the mcp-authorizer using the shared secret.

    This design ensures that the MCP Server is aware of the authorized user context, making all MCP tools user-aware.

  7. Compare Stateful vs Stateless MCP Server models

    main

    When implementing MCP Servers using the Streamable HTTP Transport, you must choose between stateful and stateless models based on your scaling and session requirements.

    Stateful MCP Servers

    Stateful servers maintain session state in memory and keep SSE (Server-Sent Events) connections alive to allow the server to push data to the client.

    • Capabilities: Supports long-lived HTTP GET requests for SSE and connection resumption.
    • Challenges: Difficult to scale horizontally because official MCP SDKs do not yet support external session persistence (e.g., Redis or DynamoDB). If a client is routed to a different instance, the session context is lost.
    • Scaling Workaround: You can use sticky sessions (session affinity) at the Load Balancer level (e.g., cookie-based). Note that because the TypeScript MCP Client SDK uses the fetch API, you may need to implement manual cookie handling to support sticky sessions.

    Stateless MCP Servers

    Stateless servers do not maintain session context between requests.

    • Capabilities: Clients are not expected to resume dropped connections.
    • Benefits: Enables seamless horizontal scaling and works efficiently in highly elastic environments like AWS Lambda or Amazon ECS. This is the recommended model for environments where load distribution is critical.

  8. How User-awareness and Session Management are implemented

    main

    The AI Agent and MCP Server are designed to be fully stateless, externalizing state to maintain scalability on AWS Lambda.

    • Statelessness: Neither the Agent nor the MCP Server maintains internal state.
    • Session Persistence: The AI Agent uses the S3SessionManager class from the Strands SDK to persist session state in Amazon S3.
    • Per-Request Lifecycle: A new Strands Agent instance is created for every request, initialized with the state belonging to the current authenticated user.
    • User-Aware MCP: MCP Clients attached to the AI Agent are created on a per-user basis. They hold user-specific JWTs to communicate with the MCP Server. The MCP Server then propagates this authorized user context into all tools, making the tools themselves user-aware.

  9. How A2A Push Notifications work

    main

    The push notification pattern enables decoupled, asynchronous workflows for long-running AI operations. The lifecycle follows these steps:

    1. Request: The Client sends a POST request to the Server agent including a webhook URL.
    2. Acknowledgment: The Server immediately returns a 202 Accepted status and a unique task ID.
    3. Processing: The Server processes the task asynchronously (e.g., using LangGraph agents).
    4. Push Updates: As the task moves through states (e.g., working, generating response), the Server sends HTTP POST updates to the provided webhook URL.
    5. Completion: The final result (artifact) is pushed to the webhook, notifying the client that the task is finished.

  10. Stateless vs Stateful MCP Server modes

    main

    MCP Servers can operate in two distinct modes:

    Stateless Mode (Used in this sample)

    • Transport: Uses Streamable HTTP.
    • Connection: Clients do not establish persistent SSE (Server-Sent Events) connections.
    • Behavior: Clients will not receive proactive notifications from the server.
    • Scaling: Allows for easy horizontal scaling of the server.

    Stateful Mode

    • Transport: Uses persistent SSE connections.
    • Behavior: Supports proactive notifications from the server.
    • Implementation: For a stateful implementation, refer to the stateful-mcp-on-ecs sample in this repository.

  11. How Authentication and Authorization work in the Strands Agent

    main

    The system uses a multi-layered JWT-based authorization model to ensure user identity is propagated without being inferred from LLM responses.

    • User Authentication: Handled by Amazon Cognito. During deployment, two test users (Alice and Bob) are created with the password Passw0rd@.
    • AI Agent Authorization: The AI Agent expects a JWT issued by Cognito. The subject (sub) of this JWT is the user. Validation is performed by the Agent Authorizer using Cognito-generated JWKs.
    • MCP Domain Authorization: The Bookings MCP requires a JWT generated by the Strands Agent. The subject of this JWT is the agent, and it includes a user_id as an extra claim. This token is signed by a shared secret, and validation is performed by the MCP Authorizer.

    This architecture ensures that both the AI Agent and the MCP Server are aware of the current user and process requests within the correct authorization context.

  12. Understand Stateless vs Stateful MCP Servers

    main

    When choosing an architecture for your MCP server, consider the following trade-offs:

    Stateless Mode (Demonstrated in this sample)

    • Transport: Uses Streamable HTTP.
    • Connectivity: Clients do not establish persistent SSE (Server-Sent Events) connections.
    • Pros: Allows for easy horizontal scaling of the server.
    • Cons: Clients will not receive proactive notifications from the server.

    Stateful Mode

    • Transport: Uses persistent SSE connections.
    • Pros: Supports proactive notifications from the server to the client.
    • Implementation: See the stateful-mcp-on-ecs-nodejs sample in this repository for a reference implementation.