Lambda Sam
    Lambda Sam

    Lambda Sam

    An AWS Serverless Application Model that operates as an MCP server via serverless AWS resources

    2.2

    GitHub Stats

    Stars

    11

    Forks

    3

    Release Date

    4/10/2025

    about 2 months ago

    Detailed Description

    MCP Lambda SAM

    Model Context Protocol (MCP) implementation using AWS Lambda and SAM.

    Overview

    This project provides a serverless implementation of the Model Context Protocol, with two distinct interfaces:

    1. System Configuration (Administrative):

      • Registration of MCP tools, resources, and prompts
      • IAM permission management
      • Infrastructure setup and configuration
    2. System Usage (Client):

      • Establishing SSE connections
      • Sending commands
      • Receiving streaming responses

    Architecture

    Mermaid Diagram

    You can visualize the system using this Mermaid syntax:

    graph TD
      Client --> MCP[/"MCP Lambda\n(/sse & /message)"/]
      MCP -->|read/write| SessionTable[(Session Table)]
      MCP -->|query| RegistrationTable[(Registration Table)]
      MCP -->|invoke| RegisteredLambda["Registered Lambda Tool"]
    
      Admin[Administrator] --> RegistrationLambda[/"Registration Lambda\n(/register)"/]
      RegistrationLambda -->|write| RegistrationTable
    
    • The MCP Lambda reads registrations from the Registration Table on startup and when handling requests.
    • It uses the Session Table to persist session state.
    • It invokes registered Lambda tools dynamically using the ARNs stored in the Registration Table.

    System Configuration Guide (Administrators)

    This section is for system administrators who need to configure and manage the MCP server.

    Deployment

    npx @markvp/mcp-lambda-sam deploy
    

    The command will interactively prompt for administrative configuration:

    • Stack name (for multiple instances)
    • AWS Region
    • VPC configuration (optional)

    Permissions Overview

    To access MCP endpoints, users and clients must have IAM permission to invoke the relevant Function URLs.

    • Administrators: must be allowed to invoke the mcp-registration function URL
    • Clients: must be allowed to invoke the mcp function URL

    You can grant access using either an IAM policy or aws lambda add-permission (see below).

    Assigning Permissions via AWS CLI

    To grant permission to invoke the registration function URL:

    aws lambda add-permission \
      --function-name <registration-function-name> \
      --statement-id allow-registration \
      --action lambda:InvokeFunctionUrl \
      --principal "*" \
      --function-url-auth-type IAM
    

    To grant permission to invoke the MCP function URL (SSE and message):

    aws lambda add-permission \
      --function-name <mcp-function-name> \
      --statement-id allow-mcp \
      --action lambda:InvokeFunctionUrl \
      --principal "*" \
      --function-url-auth-type IAM
    

    Replace <registration-function-name> and <mcp-function-name> with the actual Lambda function names.

    Registration API

    Use these endpoints to manage MCP tools, resources, and prompts:

    Register a New Tool

    awscurl -X POST ${REGISTRATION_URL}/register \
      --region ap-southeast-2 \
      --service lambda \
      -H "Content-Type: application/json" \
      -d '{
        "type": "tool",
        "name": "example",
        "description": "Example tool",
        "lambdaArn": "arn:aws:lambda:region:account:function:name",
        "parameters": {
          "input": "string"
        }
      }'
    

    Update Registration

    awscurl -X PUT ${REGISTRATION_URL}/register/{id} \
      --region ap-southeast-2 \
      --service lambda \
      -d '...'
    

    Delete Registration

    awscurl -X DELETE ${REGISTRATION_URL}/register/{id} \
      --region ap-southeast-2 \
      --service lambda
    

    List Registrations

    awscurl ${REGISTRATION_URL}/register \
      --region ap-southeast-2 \
      --service lambda
    

    Required IAM Permissions

    For Administrators

    Administrators need these permissions to manage registrations:

    {
      "Version": "2012-10-17",
      "Statement": [{
        "Effect": "Allow",
        "Action": "lambda:InvokeFunctionUrl",
        "Resource": "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp-registration",
        "Condition": {
          "StringEquals": {
            "lambda:FunctionUrlAuthType": "AWS_IAM"
          }
        }
      }]
    }
    
    

    System Usage Guide (Clients)

    This section is for clients who want to use the MCP server.

    Required IAM Permissions

    Clients need these permissions to use the MCP server:

    {
        "Version": "2012-10-17",
        "Statement": [
            {
                "Effect": "Allow",
                "Action": "lambda:InvokeFunctionUrl",
                "Resource": [
                    "arn:aws:lambda:${region}:${account}:function:${stack-id}-mcp",
                ],
                "Condition": {
                    "StringEquals": {
                        "lambda:FunctionUrlAuthType": "AWS_IAM"
                    }
                }
            }
        ]
    }
    

    Connecting to the Server

    1. Establish SSE Connection:
    const sse = new EventSource(SSE_URL, {
      headers: {
        Authorization: 'AWS4-HMAC-SHA256 ...', // Must be AWS SigV4 signed
      }
    });
    
    sse.onmessage = (event) => {
      console.log(JSON.parse(event.data));
    };
    

    Example cURL for SSE

    awscurl -X GET "${MCP_URL}/sse" \
      --region ap-southeast-2 \
      --service lambda
    

    The first event will include a sessionId. Use this when sending messages.

    1. Send Commands:
    awscurl -X POST "${MCP_URL}/message?sessionId=session-123" \
      --region ap-southeast-2 \
      --service lambda \
      -H "Content-Type: application/json" \
      -d '{
        "jsonrpc": "2.0",
        "id": "1",
        "method": "example",
        "params": {
          "input": "hello"
        }
      }'
    

    Error Handling

    Common Client Errors

    • 401: Invalid/missing AWS credentials
    • 403: Insufficient permissions
    • 404: Invalid session ID
    • 429: Rate limit exceeded

    Troubleshooting

    1. Connection Issues:

      • Verify AWS credentials
      • Check IAM permissions
      • Ensure network connectivity
    2. Command Execution Errors:

      • Verify session ID is active
      • Check command format matches tool registration
      • Ensure parameters match schema

    Requirements

    • AWS CLI installed and configured
    • AWS SAM CLI installed
    • Node.js 20.x or later
    • An AWS account with permissions to create:
      • Lambda functions
      • DynamoDB tables
      • IAM roles
      • SQS queues

    AWS SAM CLI Setup

    To deploy this application locally or to AWS using the AWS SAM CLI:

    1. Install the AWS SAM CLI: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
    2. Ensure it's available in your PATH:
      sam --version
      
    3. Build and deploy the application:
      sam build
      sam deploy --guided
      
    4. Follow the prompts to configure the stack name, region, capabilities, and parameter overrides.

    You can rerun sam deploy without --guided to use saved configuration.

    Installation

    You can install and deploy this application in four ways:

    1. Using AWS Serverless Application Repository (SAR)

    The easiest way to deploy the MCP server is through the AWS Serverless Application Repository (SAR):

    • Go to the SAR Console
    • Search for mcp-lambda-sam by Mark Van Proctor
    • Click Deploy
    • Set your parameters:
      • StackIdentifier: Unique ID for this MCP server instance
      • VpcEnabled: Set to true if deploying in a VPC
      • VpcId and SubnetIds: Provide only if VpcEnabled is true
    • Follow the prompts to deploy

    Alternatively, you can deploy from the AWS CLI:

    aws serverlessrepo create-cloud-formation-change-set \
      --application-id arn:aws:serverlessrepo:ap-southeast-2:522814717816:applications/mcp-lambda-sam \
      --stack-name your-stack-name \
      --capabilities CAPABILITY_IAM \
      --parameter-overrides '[{"name":"StackIdentifier","value":"your-stack-id"}]'
    

    2. Using npx (CLI)

    npx @markvp/mcp-lambda-sam deploy
    

    The command will interactively prompt for administrative configuration:

    • Stack name (for multiple instances)
    • AWS Region
    • VPC configuration (optional)

    3. Programmatic Usage with Install

    Install the package:

    npm install @markvp/mcp-lambda-sam
    

    After installing the package, you can use it programmatically:

    import { deploy } from '@markvp/mcp-lambda-sam';
    
    // Usage example
    deploy();
    

    4. Local Development and Deployment

    Install the package:

    npm install @markvp/mcp-lambda-sam
    

    After making development changes, you can deploy it manually:

    npm run deploy
    

    Development

    # Install dependencies
    npm install
    
    # Lint
    npm run lint
    
    # Run tests
    npm test
    
    # Build
    npm run build
    
    # Deploy
    npm run deploy
    

    Publishing to SAR

    If you're contributing to this project and need to publish updates to SAR:

    1. Package the application:
    npm run package:sar
    
    1. Publish to SAR:
    npm run publish:sar
    
    1. Make the application public (one-time setup):
      • Go to AWS Console > Serverless Application Repository
      • Select the application
      • Click "Share" and choose "Public"
      • Apply the following sharing policy:
      {
          "Version": "2012-10-17",
          "Statement": [
              {
                  "Effect": "Allow",
                  "Principal": "*",
                  "Action": "serverlessrepo:CreateCloudFormationTemplate",
                  "Resource": "arn:aws:serverlessrepo:${region}:${account-id}:applications/mcp-lambda-sam"
              }
          ]
      }
      

    License

    MIT

    Contributing

    1. Fork the repository
    2. Create your feature branch
    3. Commit your changes
    4. Push to the branch
    5. Create a new Pull Request

    About the Project

    This app has not been claimed by its owner yet.

    Claim Ownership

    Receive Updates

    Security Updates

    Get notified about trust rating changes

    to receive email notifications.