Serverless MCP Orchestrator with AWS Lambda & SAM

This repository furnishes a fully serverless realization of the Model Context Protocol stack, utilizing AWS Lambda functions managed via the Serverless Application Model (SAM).

Primary Interfaces

This architecture exposes two distinct operational planes:

1. Administrative Plane (Configuration & Setup):

   • Cataloging and publishing MCP functions/tools.
   • Configuration of access policies (IAM).
   • Infrastructure provisioning via SAM.

2. Runtime Plane (Client Interaction):

   • Establishing continuous, streaming connections (SSE).
   • Dispatching invocation requests (commands).
   • Receiving asynchronous result streams.

Architectural Topology

Visualize the data flow with this Mermaid diagram:

graph TD
  Client --> MCP[("Core MCP Handler\n(/sse & /message)")]
  MCP -->|R/W State| SessionStore[(Session DynamoDB)]
  MCP -->|Lookup Registrations| RegistryStore[(Registration DynamoDB)]
  MCP -->|Execute Tool| RegisteredFn["Dynamically Invoked Lambda Tool"]

  Admin[System Operator] --> RegistryFn[("Registration Handler\n(/register)")]
  RegistryFn -->|Write Config| RegistryStore

• The Core MCP Handler loads tool metadata from the Registry Store upon initialization.
• Session persistence is maintained in the Session Store.
• Tool execution involves dynamic invocation of the registered Lambda ARN.

Administrator Configuration Procedures

This guide addresses operational staff responsible for deployment and access management.

Deployment Script Execution

npx @markvp/mcp-lambda-sam deploy

This CLI workflow prompts for essential parameters: - Deployment identifier (for stack isolation) - Target AWS Region - Optional network segmentation (VPC settings)

Authorization Scheme

Access to the public Function URLs requires appropriate IAM authorization.

• Admins: Must possess permissions to invoke the mcp-registration function endpoint.
• Consumers: Must possess permissions to invoke the primary mcp function endpoint (for SSE/messaging).

Permissions can be established via inline IAM policies or the AWS CLI add-permission command.

Granting Invocation Rights (AWS CLI Example)

For the registration endpoint:

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

For the runtime endpoint (SSE/message):

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

Ensure placeholders for function names are substituted correctly.

Configuration Endpoint Operations

Use these HTTP verbs against the registration URL to govern the tool catalog:

Onboarding a New Service

awscurl -X POST ${REGISTRATION_URL}/register \
  --region ap-southeast-2 \
  --service lambda \
  -H "Content-Type: application/json" \
  -d '{
    "type": "tool",
    "name": "data_processor",
    "description": "Utility for data manipulation",
    "lambdaArn": "arn:aws:lambda:region:account:function:name",
    "parameters": { "payload": "object" }
  }'

Modification

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

Removal

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

Inventory Retrieval

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

Required Administrator Access Policies

Administrators require invocation permissions structured as follows:

{
  "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"
      }
    }
  }]
}

Client Usage Guide

This section details the necessary steps for end-users interacting with the live MCP system.

Essential Client Authorization

Clients must possess the following IAM privileges to interact with the runtime service:

{
    "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"
                }
            }
        }
    ]
}

Initiating a Streaming Session

1. Connect via EventSource (SSE):

const sse = new EventSource(SSE_URL, {
  headers: { 
    Authorization: 'AWS4-HMAC-SHA256 ...', // Must adhere to AWS SigV4 standards
  }
});

sse.onmessage = (event) => {
  console.log(JSON.parse(event.data));
};

The initial streamed event will contain the assigned sessionId, critical for subsequent command submissions.

Submitting Operational Commands

Use a POST request to the /message endpoint, referencing the active session:

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": "req-456",
    "method": "data_processor",
    "params": { "payload": "data_input" }
  }'

Troubleshooting and Support

Common HTTP Response Failures

• 401: Credentials invalid or absent.
• 403: Authorization policies deny access.
• 404: Session identifier is unrecognized or expired.
• 429: Request throttling limit reached.

Diagnostic Checklist

1. Connectivity Diagnostics:

   • Validate AWS credential validity.
   • Review attached IAM permissions.
   • Confirm network path accessibility.

2. Execution Failures:

   • Confirm session ID validity and activity.
   • Validate the submitted JSON-RPC method matches registered tool specifications.
   • Check parameter structure conformity with the registered schema.

Prerequisites

This toolchain necessitates the following prerequisites:

• Operational AWS Command Line Interface (CLI).
• Installed AWS SAM CLI utility.
• Node.js runtime, version 20.x or newer.
• An active AWS tenancy provisioned with rights to create:
  • Lambda compute resources
  • DynamoDB persistent storage
  • IAM security constructs
  • (Potentially) SQS messaging infrastructure

Deployment Strategies via AWS SAM CLI

To deploy this infrastructure using the SAM CLI:

1. Obtain the SAM CLI installer: https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html
2. Verification in PATH: bash sam --version
3. Build and deploy: bash sam build sam deploy --guided
4. Follow the interactive prompts for stack naming, region selection, and capability assertions.

Subsequent deployments can omit --guided to reuse saved settings.

Installation Modalities

Deployment can be achieved through four methods:

Method 1: AWS Serverless Application Repository (SAR)

This offers the simplest deployment path:

• Navigate to the SAR Console.
• Search for the identifier: mcp-lambda-sam.
• Select Deploy.
• Configure required template parameters (e.g., StackIdentifier).

CLI deployment via SAR utilizes a change set creation:

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

Method 2: Direct NPX Execution

npx @markvp/mcp-lambda-sam deploy

This triggers the guided deployment workflow described previously.

Method 3: Programmatic Inclusion

Install the package via NPM:

npm install @markvp/mcp-lambda-sam

Consumption example:

import { deploy } from '@markvp/mcp-lambda-sam';

deploy(); 

Method 4: Local Development Iteration

Install dependencies locally:

npm install

To apply local modifications:

npm run deploy

Development Lifecycle

# Dependency setup
npm install

# Code quality check
npm run lint

# Execution of unit/integration tests
npm test

# Artifact generation
npm run build

# Infrastructure deployment
npm run deploy

Publishing Artifacts to SAR

For contributors updating the source:

1. Package assets for SAR consumption:

npm run package:sar

1. Upload the package:

npm run publish:sar

1. Make the application publicly discoverable (one-time action in AWS Console):
2. Navigate to SAR, select the application.
3. Modify the sharing policy to grant serverlessrepo:CreateCloudFormationTemplate access to the principal * within your region/account ARN scope.

Licensing Information

This project is governed under the MIT License.

Collaboration Guidelines

We welcome contributions: 1. Fork this repository. 2. Initiate a new feature branch. 3. Commit your enhancements. 4. Push the feature branch. 5. Submit a Pull Request for review.

WIKIPEDIA NOTE: XMLHttpRequest (XHR) serves as a JavaScript API enabling browser applications to issue HTTP transactions to a server subsequent to page loading. This capability is foundational to Asynchronous JavaScript and XML (Ajax) interactions. Historically, server interaction relied solely on full page reloads via form submission or link navigation. XHR was conceived around 2000 by Microsoft Outlook developers and first shipped in IE5 (1999), initially using proprietary ActiveXObject identifiers (e.g., "Msxml2.XMLHTTP"). By IE7 (2006), the standardized XHR identifier was universally adopted across major rendering engines (Gecko, Safari, Opera). The W3C formalized the specification in 2006, with Level 2 additions (cross-site access, progress monitoring) later integrated. Development stewardship is currently managed by WHATWG. Standard usage involves object instantiation, configuration via the open() method (specifying method, URI, and async mode), setting event handlers, and initiating the transaction with send(). Response data is typically found in responseText upon reaching state 4 (completion). Advanced features permit header customization, binary data upload, and partial response streaming.