middy-mcp

0.1.6 verified Sat Apr 25 auth: no javascript

Middy middleware for integrating Model Context Protocol (MCP) servers with AWS Lambda functions. Current version 0.1.6, requires Node.js >= 18.0.0 and Middy >= 6.0.0. Supports API Gateway (REST, HTTP API v2) and ALB proxy integrations, but only compatible with MCP clients using protocol version 2025-03-26 or later. Provides seamless request/response handling within the Middy middleware framework, with TypeScript type definitions included.

Common errors

error Cannot find module '@modelcontextprotocol/sdk' ↓

cause Missing or incorrect import path for the SDK.

fix

Install @modelcontextprotocol/sdk and import from '@modelcontextprotocol/sdk/server/mcp.js'.

error TypeError: middy is not a function ↓

cause Incorrect import of Middy (named instead of default).

fix

Use import middy from '@middy/core' (default import).

error Error: MCP protocol version not supported. Must be at least 2025-03-26. ↓

cause MCP client uses an older protocol version.

fix

Update MCP client to support protocol version 2025-03-26 or later.

Warnings

breaking Only compatible with MCP clients using protocol version 2025-03-26 or later. ↓

fix Ensure MCP client supports version 2025-03-26+

gotcha Cannot be used in a bundle with other middlewares that modify headers due to order issues. ↓

fix Update to v0.1.0+ for header compatibility with other middlewares.

gotcha Requires HTTP error handler middleware to handle thrown HTTP exceptions. ↓

fix Use @middy/http-error-handler after mcpMiddleware.

breaking Requires Middy >= 6.0.0, which introduced breaking changes from earlier versions. ↓

fix Upgrade @middy/core to v6 or later.

deprecated The package uses ESM-only exports – CommonJS require() will not work. ↓

fix Convert project to ESM or use dynamic import().

Install

npm install middy-mcp

yarn add middy-mcp

pnpm add middy-mcp

Imports

default

wrong

const mcpMiddleware = require('middy-mcp');

correct

import mcpMiddleware from 'middy-mcp'

ESM-only package; default export is the middleware function.

McpServer

wrong

import { McpServer } from '@modelcontextprotocol/sdk'

correct

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'

Must import from the specific subpath /server/mcp.js for correct ESM resolution.

middy
wrong
```
import { middy } from '@middy/core'
```
correct
```
import middy from '@middy/core'
```
Default export from @middy/core; named export 'middy' does not exist.

Quickstart

Create a Lambda handler with MCP server and Middy middleware.

import middy from '@middy/core';
import mcpMiddleware from 'middy-mcp';
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

const server = new McpServer({ name: 'MyMCP', 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 }));