{"id":17622,"library":"express-mcp-handler","title":"Express MCP Handler","description":"Express-mcp-handler is a middleware library designed to integrate the Model Context Protocol (MCP) into Express.js applications. It facilitates seamless communication between large language models (LLMs) and external tools or data sources by providing standardized handling for MCP requests. The package is currently in version 0.3.0, indicating it is in early development and its API may evolve rapidly, though it appears actively maintained. Key differentiators include its ability to manage stateful, stateless, and Server-Sent Events (SSE) based MCP interactions, offering a flexible solution for various integration patterns. Built with TypeScript, it provides a type-safe API, enhancing reliability and developer experience. It also offers customizable options for error handling, session management, and lifecycle hooks, making it adaptable to complex application requirements, and directly plugs into existing Express routes.","status":"active","version":"0.3.0","language":"javascript","source_language":"en","source_url":"https://github.com/jhgaylor/express-mcp-handler","tags":["javascript","express","mcp","model-context-protocol","middleware","typescript"],"install":[{"cmd":"npm install express-mcp-handler","lang":"bash","label":"npm"},{"cmd":"yarn add express-mcp-handler","lang":"bash","label":"yarn"},{"cmd":"pnpm add express-mcp-handler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for Express.js application integration.","package":"express","optional":false},{"reason":"Provides the core Model Context Protocol server functionality.","package":"@modelcontextprotocol/sdk","optional":false},{"reason":"Likely used for schema validation within the MCP SDK or handler logic.","package":"zod","optional":false}],"imports":[{"note":"The package is ESM-first and primarily designed for modern Node.js environments (>=18).","wrong":"const statelessHandler = require('express-mcp-handler').statelessHandler;","symbol":"statelessHandler","correct":"import { statelessHandler } from 'express-mcp-handler';"},{"note":"This is a named export, not a default export. Ensure correct destructuring.","wrong":"import statefulHandler from 'express-mcp-handler';","symbol":"statefulHandler","correct":"import { statefulHandler } from 'express-mcp-handler';"},{"note":"Used for handling MCP over Server-Sent Events (SSE) specific endpoints.","wrong":"const { sseHandler } = require('express-mcp-handler');","symbol":"sseHandler","correct":"import { sseHandler } from 'express-mcp-handler';"}],"quickstart":{"code":"import express from 'express';\nimport { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';\nimport { statelessHandler } from 'express-mcp-handler';\n\nconst app = express();\napp.use(express.json());\n\n// Create a factory function that returns a new McpServer instance for each request\nconst serverFactory = () => new McpServer({\n  name: 'my-mcp-server',\n  version: '1.0.0',\n  // Add tool definitions here, e.g.:\n  // tools: [\n  //   {\n  //     id: 'getCurrentTime',\n  //     description: 'Gets the current time.',\n  //     inputSchema: z.object({}),\n  //     outputSchema: z.object({ time: z.string() }),\n  //     handler: async () => ({ time: new Date().toISOString() }),\n  //   },\n  // ],\n});\n\n// Mount the stateless handler on a POST endpoint\napp.post('/mcp', statelessHandler(serverFactory));\n\napp.listen(3000, () => {\n  console.log('Express MCP server running on port 3000');\n});","lang":"typescript","description":"This example demonstrates how to set up a basic Express server and integrate the `statelessHandler` to process Model Context Protocol (MCP) requests. It uses a server factory to create a new `McpServer` instance for each incoming request, ensuring isolated handling."},"warnings":[{"fix":"Refer to the GitHub repository and changelog for updates before upgrading. Pin exact versions for stability in production.","message":"As the package is currently in version 0.x.x, the API is subject to change without a major version bump. Users should expect potential breaking changes in minor or patch releases.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Run `npm install express @modelcontextprotocol/sdk zod` to satisfy peer dependency requirements.","message":"This package requires `express`, `@modelcontextprotocol/sdk`, and `zod` as peer dependencies. They must be installed separately alongside `express-mcp-handler`.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure your project's Node.js version is 18.0.0 or greater. Update your Node.js environment if necessary.","message":"The package targets Node.js version 18.0.0 or higher. Running on older Node.js versions may lead to compatibility issues or unexpected behavior due to modern JavaScript features and ESM support.","severity":"gotcha","affected_versions":"<=0.3.0"},{"fix":"Carefully review the documentation for each handler (`statelessHandler`, `statefulHandler`, `sseHandler`) to understand whether it expects a `McpServer` instance or a function that creates one per request. The quickstart demonstrates a factory for `statelessHandler`.","message":"The `statelessHandler` typically expects a 'server factory' function that returns a new `McpServer` instance per request, while `statefulHandler` can often use a single, pre-configured `McpServer` instance. Incorrectly providing a factory where an instance is expected, or vice-versa, can lead to unexpected session management or state issues.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Install the required peer dependencies: `npm install express @modelcontextprotocol/sdk zod`.","cause":"Missing peer dependency installation.","error":"Error: Cannot find package 'express' (or @modelcontextprotocol/sdk, zod) imported from ..."},{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import` statements. If using TypeScript, ensure your `tsconfig.json` targets a modern `module` resolution (e.g., `\"ES2022\"` or `\"Node16\"`).","cause":"Attempting to `require()` an ESM-only module in a CommonJS context or mixing module systems incorrectly.","error":"TypeError: (0 , express_mcp_handler_1.statelessHandler) is not a function"},{"fix":"Convert your calling code to use ES Modules with `import` statements. If this is not feasible, consider a build step like Babel or Webpack to handle module transformations, or ensure your `package.json` specifies `\"type\": \"module\"` for relevant files.","cause":"You are trying to `require()` this package which is an ES Module, but `require()` only works for CommonJS modules.","error":"ERR_REQUIRE_ESM: Must use import to load ES Module: ...express-mcp-handler/dist/index.js"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}