first commit

Author: aal80

README.md

@@ -1 +1,50 @@
-# simple-mcp-server-on-lambda
+# Simple MCP Server on Lambda
+
+A simple MCP Server running natively on AWS Lambda and Amazon API Gateway without any extra bridging components or custom transports. This is now possible thanks to the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http) transport introduced in v2025-03-26. 
+
+Architecture is as simple as it gets: 
+![](architecture.png)
+
+## Prereqs
+
+* AWS CLI
+* Terraform 
+
+## Instructions
+
+Install dependencies:
+```bash
+cd src
+npm install
+cd ..
+```
+
+Bootstrap server and set env var with MCP Server endpoint:
+```bash
+cd terraform
+terraform init
+terraform plan
+terraform apply
+export SIMPLE_MCP_SERVER_ENDPOINT=$(terraform output --raw endpoint_url) 
+cd ..
+```
+
+> Note: It might take a few seconds for API Gateway endpoint to become operational. 
+
+
+Run client:
+```bash
+node src/client.js
+```
+
+Observe the response:
+```bash
+> node client.js
+> listTools response:  { tools: [ { name: 'ping', inputSchema: [Object] } ] }
+> callTool:ping response:  { content: [ { type: 'text', text: 'pong' } ] }
+```
+
+## Learn about mcp
+[Intro](https://modelcontextprotocol.io/introduction)
+
+[Protocol specification](https://modelcontextprotocol.io/specification/2025-03-26)

src/client.js

@@ -0,0 +1,23 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const ENDPOINT_URL = process.env.SIMPLE_MCP_SERVER_ENDPOINT;
+console.log(`Connecting ENDPOINT_URL=${ENDPOINT_URL}`);
+
+const transport = new StreamableHTTPClientTransport(new URL(ENDPOINT_URL));
+
+const client = new Client({
+    name: "node-client",
+    version: "0.0.1"
+})
+
+await client.connect(transport);
+const tools = await client.listTools();
+console.log(`listTools response: `, tools);
+
+const result = await client.callTool({
+    name: "ping"
+});
+console.log(`callTool:ping response: `, result);
+
+await client.close();

src/logging.js

@@ -0,0 +1,36 @@
+import log4js from 'log4js';
+import { unlinkSync } from 'fs';
+
+const LOG_FILE = './server.log';
+
+// try { unlinkSync(LOG_FILE); } catch (e) { };
+
+const layout = {
+    type: 'pattern',
+    // pattern: '%[%d{hh:mm:ss.SSS} %p [%f{1}:%l:%M] %m%]'
+    pattern: '%[%p [%f{1}:%l:%M] %m%]'
+}
+
+log4js.configure({
+    appenders: {
+        stdout: {
+            type: 'stdout',
+            enableCallStack: true,
+            layout
+        },
+        file: {
+            type: 'file',
+            filename: LOG_FILE,
+            enableCallStack: true,
+            layout
+        }
+    },
+    categories: {
+        default: {
+            appenders: ['stdout'],
+            // appenders: ['file'],
+            level: 'debug',
+            enableCallStack: true
+        }
+    }
+});

src/mcpServer.js

@@ -0,0 +1,24 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const mcpServer = new McpServer({
+  name: "simple-mcp-server-on-lambda",
+  version: "0.0.1"
+}, {
+  capabilities: {
+    tools: {}
+  }
+});
+
+mcpServer.tool("ping", ()=>{
+  return {
+    content: [
+      {
+        type: "text",
+        text: "pong"
+      }
+    ]
+  }
+});
+
+export default mcpServer;

src/package.json

@@ -0,0 +1,13 @@
+{
+    "type": "module",
+    "author": "Anton Aleksandrov",
+    "license": "Apache-2.0",
+    "description": "A simple MCP Server running on AWS Lambda",
+    "dependencies": {
+      "@codegenie/serverless-express": "^4.16.0",
+      "@modelcontextprotocol/sdk": "^1.10.1",
+      "express": "^5.1.0",
+      "log4js": "^6.9.1"
+    }
+  }
+  

src/server.js

@@ -0,0 +1,92 @@
+import './logging.js';
+import log4js from 'log4js';
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { InitializeRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import mcpServer from './mcpServer.js';
+
+const l = log4js.getLogger();
+
+const app = express();
+app.use(express.json());
+app.use((req, res, next) => {
+    l.debug(`> ${req.method} ${req.originalUrl}`);
+    l.debug(req.body);
+    res.set('Access-Control-Allow-Origin', '*');
+    res.set('Access-Control-Allow-Headers', '*');
+    return next();
+});
+
+// Map to store transports by session ID
+const transports = {};
+
+// Handle POST requests for client-to-server communication
+app.post('/mcp', async (req, res) => {
+    const sessionId = req.headers['mcp-session-id'];
+    let transport;
+
+    if (sessionId && transports[sessionId]) {
+        l.debug(`found existing transport for sessionId=${sessionId}`);
+        transport = transports[sessionId];
+    } else if (!sessionId && isInitializeRequest(req.body)) {
+        l.debug(`creating new transport`);
+        transport = new StreamableHTTPServerTransport({
+            //sessionIdGenerator: () => undefined,
+            // ^ this should be used for fully sessionless connections,
+            // but there's currently a bug preventing it. Waiting for next
+            // SDK release to be fixed. In the meanwhile, let's use sessions. 
+            
+            sessionIdGenerator: () => randomUUID(),
+            enableJsonResponse: true,
+            onsessioninitialized: (sessionId) => {
+                l.debug(`transport.onsessioninitialized sessionId=${sessionId}`);
+                transports[sessionId] = transport;
+            }
+        });
+
+        await mcpServer.connect(transport);
+    } else {
+        l.debug(`Invalid request, no sessionId`);
+        res.status(400).json({
+            jsonrpc: '2.0',
+            error: {
+                code: -32000,
+                message: 'Bad Request: No valid session ID provided',
+            },
+            id: null,
+        });
+        return;
+    }
+
+    await transport.handleRequest(req, res, req.body);
+});
+
+function isInitializeRequest(body) {
+    const isInitial = (data) => {
+        const result = InitializeRequestSchema.safeParse(data)
+        return result.success
+    }
+    if (Array.isArray(body)) {
+        return body.some(request => isInitial(request))
+    }
+    return isInitial(body)
+}
+
+// Handle GET requests for server-to-client notifications via SSE
+app.get('/mcp', (req, res) => {
+    res.status(405).set('Allow', 'POST').send('Method Not Allowed');
+});
+
+// Handle DELETE requests for session termination
+app.delete('/mcp', (req, res) => {
+    res.status(405).set('Allow', 'POST').send('Method Not Allowed');
+});
+
+const port = 3000;
+app.listen(port, () => {
+    l.debug(`Listening on http://localhost:${port}`);
+});
+
+import serverlessExpress from '@codegenie/serverless-express';
+export const handler = serverlessExpress({ app });

terraform/apigateway.tf

@@ -0,0 +1,50 @@
+resource "aws_api_gateway_rest_api" "api" {
+    name = "simple-mcp-server"
+}
+
+resource "aws_api_gateway_resource" "mcp" {
+    rest_api_id = aws_api_gateway_rest_api.api.id
+    parent_id = aws_api_gateway_rest_api.api.root_resource_id
+    path_part = "mcp"
+}
+
+resource "aws_api_gateway_method" "any" {
+    rest_api_id = aws_api_gateway_rest_api.api.id
+    resource_id = aws_api_gateway_resource.mcp.id
+    authorization = "NONE"
+    http_method = "ANY"
+}
+
+resource "aws_api_gateway_integration" "lambda" {
+    rest_api_id = aws_api_gateway_rest_api.api.id
+    resource_id = aws_api_gateway_resource.mcp.id
+    http_method = aws_api_gateway_method.any.http_method
+    integration_http_method = "POST"
+    type = "AWS_PROXY"
+    uri = aws_lambda_function.simple_mcp_server.invoke_arn
+}
+
+resource "aws_lambda_permission" "apigateway" {
+    statement_id = "AllowExecutionFromAPIGateway"
+    action = "lambda:InvokeFunction"
+    function_name = aws_lambda_function.simple_mcp_server.function_name
+    principal = "apigateway.amazonaws.com"
+    source_arn = "${aws_api_gateway_rest_api.api.execution_arn}/*/*/*"
+}
+
+resource "aws_api_gateway_deployment" "api" {
+    rest_api_id = aws_api_gateway_rest_api.api.id
+    depends_on = [aws_api_gateway_method.any, aws_api_gateway_integration.lambda]
+    lifecycle {
+      create_before_destroy = true
+    }
+    triggers = {
+      redeployment = timestamp() //always
+    }
+}
+
+resource "aws_api_gateway_stage" "dev" {
+    rest_api_id = aws_api_gateway_rest_api.api.id
+    deployment_id = aws_api_gateway_deployment.api.id
+    stage_name = "dev"
+}

terraform/lambda.tf

@@ -0,0 +1,38 @@
+resource "aws_iam_role" "simple_mcp_server" {
+  name = "simple-mcp-server"
+  assume_role_policy = jsonencode({
+    Version = "2012-10-17"
+    Statement = [
+      {
+        Action = "sts:AssumeRole"
+        Effect = "Allow"
+        Principal = {
+          Service = "lambda.amazonaws.com"
+        }
+      }
+    ]
+  })
+}
+
+resource "aws_iam_role_policy_attachment" "simple_mcp_server" {
+  role       = aws_iam_role.simple_mcp_server.name
+  policy_arn = "arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole"
+}
+
+data "archive_file" "simple_mcp_server" {
+  type        = "zip"
+  source_dir  = "${path.root}/../src"
+  output_path = "${path.root}/tmp/function.zip"
+}
+
+resource "aws_lambda_function" "simple_mcp_server" {
+  function_name    = "simple_mcp_server"
+  filename         = data.archive_file.simple_mcp_server.output_path
+  source_code_hash = data.archive_file.simple_mcp_server.output_base64sha256
+  role             = aws_iam_role.simple_mcp_server.arn
+  handler          = "server.handler"
+  runtime          = "nodejs22.x"
+  memory_size      = 512
+  timeout          = 30
+}
+

terraform/outputs.tf

@@ -0,0 +1,3 @@
+output "endpoint_url" {
+    value = "${aws_api_gateway_stage.dev.invoke_url}/${aws_api_gateway_resource.mcp.path_part}"
+}

terraform/provider.tf

@@ -0,0 +1,17 @@
+terraform {
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = "us-east-1"
+  default_tags {
+    tags = {
+      Project = "simple-mcp-server-on-lambda"
+    }
+  }
+}