Registry / http-networking / mcp-http-server

mcp-http-server

JSON →
library1.2.4jsnpmunverified

mcp-http-server is a high-performance HTTP server designed specifically for the Model Context Protocol (MCP) ecosystem, providing robust transport for both standard HTTP POST and Server-Sent Events (SSE). It offers flexible routing configurations, allows access to HTTP headers within the MCP server context, and supports custom Express-style middleware for extending server logic. The package currently maintains a stable version 1.2.4, suggesting a mature and consistent API for its core functionality. While originating from the broader UI-TARS-desktop project on GitHub, its specific release cadence appears independent of the more rapid beta iterations seen in related `@agent-tars` components. Key differentiators include its dual support for stateful and stateless modes for streamable HTTP, making it suitable for diverse real-time communication needs where MCP interactions are central.

npm install mcp-http-server
INSTALL
IMPORT
SIG · MCP-HTTP-SERVER
M
mcp-http-server
http-networkingjavascriptv1.2.4
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

startSseAndStreamableHttpMcpServer
import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';
const { startSseAndStreamableHttpMcpServer } = require('mcp-http-server');
This package primarily targets ESM and TypeScript environments. While CommonJS `require` might work in some setups, `import` is the recommended pattern for type safety and modern Node.js module resolution.
MiddlewareFunction
import type { MiddlewareFunction } from 'mcp-http-server';
Type import for defining custom Express-style middleware functions to be used with the server.
RoutesConfig
import type { RoutesConfig } from 'mcp-http-server';
Type import for configuring custom server endpoint paths and prefixes.

Initializes and starts a high-performance HTTP+SSE server for the Model Context Protocol (MCP) on port 3000, demonstrating basic setup with a minimal MCP server instance, access to request headers, and graceful shutdown.

import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server'; import { Server } from '@modelcontextprotocol/sdk/server'; // Assumed correct import path for the SDK // In a real application, createMcpServerInstance might involve more complex logic // like setting up tools, agents, or database connections. For this example, // we use a minimal MCP Server instance from the SDK. const createMcpServerInstance = async (params: { headers: Record<string, string> }) => { console.log('Received request headers:', params.headers); // Return a new instance of an MCP Server (e.g., from @modelcontextprotocol/sdk/server) return new Server( { name: 'my-mcp-server', version: '1.1.0' }, { capabilities: { tools: {} } } // Minimal capabilities for the example ); }; const main = async () => { try { const server = await startSseAndStreamableHttpMcpServer({ port: 3000, host: '::', // Listen on all available network interfaces stateless: true, // Default to true, as per docs, enables streamable HTTP // Optionally add custom Express middlewares or route configurations: // middlewares: [ (req, res, next) => { console.log('Middleware hit:', req.method, req.url); next(); } ], // routes: { prefix: '/api/v1', mcp: '/my-mcp-endpoint' }, createMcpServer: createMcpServerInstance, }); console.log(`MCP HTTP Server running on http://localhost:3000. Access MCP endpoint at http://localhost:3000/mcp`); // Example: Keep the process alive. In a production app, handle graceful shutdown. process.on('SIGINT', async () => { console.log('Shutting down MCP HTTP server...'); // Add server.close() logic if available in the returned server object process.exit(0); }); } catch (error) { console.error('Failed to start MCP HTTP Server:', error); process.exit(1); } }; main();
Debug
Known issues
gotchaThe server defaults to listening on port 8080 if no `port` parameter is explicitly provided in the configuration. This might lead to `EADDRINUSE` errors if another process is already using that port.
fix
Always explicitly set the `port` in the `startSseAndStreamableHttpMcpServer` configuration object, for example: `{ port: 3000 }`.
affects: >=1.0.0
gotchaCustom Express-style middlewares, if provided in the `middlewares` array, must correctly call `next()` to pass control to the subsequent middleware or route handler. Failing to call `next()` will cause requests to hang indefinitely.
fix
Ensure all custom middleware functions explicitly call `next()` at the end of their logic, or terminate the request using methods like `res.end()` or `res.send()` if they are designed to send a response.
affects: >=1.0.0
gotchaWhen customizing `routes` using the `routes` parameter, ensure you understand how the `prefix` interacts with the individual `mcp`, `message`, and `sse` paths. Misconfigurations or incorrect client requests can lead to unexpected 404 (Not Found) errors.
fix
Test your custom routes thoroughly. Remember that `prefix` is prepended to other paths. The server automatically handles leading/trailing slashes, so `/api/v1/` and `/api/v1` for a prefix are typically equivalent.
affects: >=1.0.0
gotchaThe `createMcpServer` factory function is a critical parameter and expects an instance of an MCP server. The provided examples and typical usage strongly suggest using `@modelcontextprotocol/sdk/server`. If this peer dependency is not installed or incorrectly used, it will lead to runtime errors.
fix
Install `@modelcontextprotocol/sdk/server` if you intend to use the official MCP server implementation: `npm install @modelcontextprotocol/sdk/server`. Ensure `createMcpServer` returns a valid MCP server instance.
affects: >=1.0.0
Errors
Common errors & fixes
Error: listen EADDRINUSE: address already in use :::3000
The specified port (e.g., 3000) for the MCP HTTP server is already being used by another process on your system.
fix
Choose a different port for the `mcp-http-server` (e.g., `port: 4000`) or identify and terminate the process currently occupying the port.
TypeError: createMcpServer is not a function
The `createMcpServer` parameter was either omitted or provided with a non-function value in the `startSseAndStreamableHttpMcpServer` configuration object.
fix
Ensure `createMcpServer` is a valid asynchronous function that returns an MCP server instance, as demonstrated in the quickstart example.
Cannot find module '@modelcontextprotocol/sdk/server'
The `@modelcontextprotocol/sdk/server` package, commonly required by implementations of the `createMcpServer` factory function, has not been installed as a dependency.
fix
Install the necessary dependency: `npm install @modelcontextprotocol/sdk/server`.
405 Method Not Allowed
The `/mcp` and `/message` endpoints are primarily designed for POST requests (MCP HTTP transport and SSE message endpoint respectively). GET requests to these paths are not allowed by default unless specifically configured for an SSE stream.
fix
Ensure your client is making POST requests to the `/mcp` or `/message` endpoints as intended for data submission. For SSE connections, clients should initiate a GET request to the `/sse` endpoint.
Upgrade
Version history
1.2.4latest on npm
Audit
Dependencies
@modelcontextprotocol/sdk/serverrequiredRequired to create instances of the MCP server, which is passed to the `createMcpServer` factory function.
expressoptionalUsed internally for middleware support; custom middlewares are Express-style.
Agent activity
3 hits · last 30 days
node
2
Amazon
1
Resources