🧠 serverless-mcp-server
About
A super simple Model Context Protocol (MCP) server deployed on AWS Lambda and exposed via Amazon API Gateway, deployed with Serverless Framework.
Details
- Author
- eleva
- GitHub stars
- 17
- Downloads
- 233
- Categories
- Cloud Service
Jump to
- Minimal MCP server setup using @modelcontextprotocol/sdk
- Deployed as a single AWS Lambda function
- HTTP POST endpoint exposed via API Gateway at /mcp
- Supports local development via serverless-offline
- Includes a simple example tool (add) with JSON‑RPC interaction
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
🧠 serverless-mcp-serverCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install dependencies with npm install, optionally install the open-source Serverless CLI globally (npm install -g osls), then run locally using serverless-offline (npm sls offline) or deploy to AWS with sls deploy. The endpoint is POST /mcp. Test with the MCP inspector or curl; an example add tool is included.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"\ud83e\udde0 serverless-mcp-server": {
"serverless-mcp-server": {
"command": "npx",
"args": [
"@modelcontextprotocol/inspector",
"node",
"src/index.mjs"
]
}
}
}
}McpServers
{
"serverless-mcp-server": {
"command": "npx",
"args": [
"@modelcontextprotocol/inspector",
"node",
"src/index.mjs"
]
}
}🧠 serverless-mcp-server
A super simple Model Context Protocol (MCP) server deployed on AWS Lambda and exposed via Amazon API Gateway, deployed with Serverless Framework. This skeleton is based on the awesome work of Frédéric Barthelet: which has developed a middy middleware for Model Context Protocol (MCP) server integration with AWS Lambda functions in this repoLong story
📖Read the full article here on dev.to🛠 Features
- 🪄 Minimal MCP server setup using @modelcontextprotocol/sdk - 🚀 Deployed as a single AWS Lambda function - 🌐 HTTP POST endpoint exposed via API Gateway at /mcp - 🔄 Supports local development via serverless-offline - 🧪 Includes a simple example tool (add) with JSON-RPC interaction📦 Project Structure
serverless-mcp-server/
├── src/ # Source code
│ └── index.js # MCP server handler
├── .gitignore # Git ignore file
├── package.json # Project dependencies
├── package-lock.json # Project lock file
├── README.md # This documentation file
└── serverless.yml # Serverless Framework config
🛠 Prerequisites
- Node.js v22+ - Open Source Serverless or Serverless Framework v3+ - Serverless Offline🚀 Getting Started
1. Install dependencies:
npm install
2. Install open source severless globally (if not already installed):
npm install -g osls
3. Run Locally with serverless-offline
npm sls offline
Local endpoint will be available at:
POST http://localhost:3000/dev/mcp
Note that the /dev/ stage is added by default when using serverless-offline, reflecting Api Gateway V1 (REST API) behavior.
Switch to Api Gateway V2 (HTTP API)
If you want to use API Gateway V2, you can change theserverless.yml file to use httpApi instead of http in the events section. This will allow you to use HTTP APIs instead of REST APIs.
This will allow you to use HTTP APIs instead of REST APIs.
functions:
mcpServer:
handler: src/index.handler
events:
- httpApi:
path: mcp
method: post
Local endpoint will be available at:
POST http://localhost:3000/mcp
Note that the /dev/ stage is not needed when using API Gateway V2.
Note you should change test curl and postman requests accordingly.
🧪 Test with MCP inspector
Run
npx @modelcontextprotocol/inspector node src/index.mjs
This will start the MCP inspector on port 6274. You can then open the inspector in your browser at
http://127.0.0.1:6274.Configure parameters in the inspector:
- Select
HTTP Streamable as Transport Type- Set
URL to http://localhost:3000/dev/mcp- Click connect
You'll be able to see the list of tools and their parameters in the inspector.
🧪 Test with curl requests
List tools
curl --location 'http://localhost:3000/dev/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json' \
--header 'jsonrpc: 2.0' \
--data '{
"jsonrpc": "2.0",
"method": "tools/list",
"id": 1
}'
➕ Use the add Tool
curl --location 'http://localhost:3000/dev/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json' \
--header 'jsonrpc: 2.0' \
--data '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "add",
"arguments": {
"a": 5,
"b": 3
}
}
}'
🧪 Test with jest
There are some basic tests included in the __tests__ folder. You can run them with:
npm run test
🧬 Code Breakdown
This code is based on the awesome work of Frédéric Barthelet: which has developed a middy middleware for Model Context Protocol (MCP) server integration with AWS Lambda functions in this reposrc/index.js
import middy from "@middy/core";
import httpErrorHandler from "@middy/http-error-handler";
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { z } from "zod";
import mcpMiddleware from "middy-mcp";
const server = new McpServer({
name: "Lambda hosted MCP Server",
version: "1.0.0",
});
server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
content: [{ type: "text", text: String(a + b) }],
}));
export const handler = middy()
.use(mcpMiddleware({ server }))
.use(httpErrorHandler());
📡 Deploy to AWS
Just run:
sls deploy
🔖 Quotes
This repository has been quoted in the following newsletters: - Serverless Advocate Newsletter #33 by Lee Gilmore (AWS Hero)📘 License
MIT — feel free to fork, tweak, and deploy your own version!Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
