{"id":11275,"library":"mcp-http-server","title":"MCP HTTP Server","description":"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.","status":"active","version":"1.2.4","language":"javascript","source_language":"en","source_url":"https://github.com/bytedance/UI-TARS-desktop","tags":["javascript","typescript"],"install":[{"cmd":"npm install mcp-http-server","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-http-server","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-http-server","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required to create instances of the MCP server, which is passed to the `createMcpServer` factory function.","package":"@modelcontextprotocol/sdk/server","optional":false},{"reason":"Used internally for middleware support; custom middlewares are Express-style.","package":"express","optional":true}],"imports":[{"note":"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.","wrong":"const { startSseAndStreamableHttpMcpServer } = require('mcp-http-server');","symbol":"startSseAndStreamableHttpMcpServer","correct":"import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';"},{"note":"Type import for defining custom Express-style middleware functions to be used with the server.","symbol":"MiddlewareFunction","correct":"import type { MiddlewareFunction } from 'mcp-http-server';"},{"note":"Type import for configuring custom server endpoint paths and prefixes.","symbol":"RoutesConfig","correct":"import type { RoutesConfig } from 'mcp-http-server';"}],"quickstart":{"code":"import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';\nimport { Server } from '@modelcontextprotocol/sdk/server'; // Assumed correct import path for the SDK\n\n// In a real application, createMcpServerInstance might involve more complex logic\n// like setting up tools, agents, or database connections. For this example,\n// we use a minimal MCP Server instance from the SDK.\nconst createMcpServerInstance = async (params: { headers: Record<string, string> }) => {\n  console.log('Received request headers:', params.headers);\n  // Return a new instance of an MCP Server (e.g., from @modelcontextprotocol/sdk/server)\n  return new Server(\n    { name: 'my-mcp-server', version: '1.1.0' },\n    { capabilities: { tools: {} } } // Minimal capabilities for the example\n  );\n};\n\nconst main = async () => {\n  try {\n    const server = await startSseAndStreamableHttpMcpServer({\n      port: 3000,\n      host: '::', // Listen on all available network interfaces\n      stateless: true, // Default to true, as per docs, enables streamable HTTP\n      // Optionally add custom Express middlewares or route configurations:\n      // middlewares: [ (req, res, next) => { console.log('Middleware hit:', req.method, req.url); next(); } ],\n      // routes: { prefix: '/api/v1', mcp: '/my-mcp-endpoint' },\n      createMcpServer: createMcpServerInstance,\n    });\n    console.log(`MCP HTTP Server running on http://localhost:3000. \nAccess MCP endpoint at http://localhost:3000/mcp`);\n\n    // Example: Keep the process alive. In a production app, handle graceful shutdown.\n    process.on('SIGINT', async () => {\n      console.log('Shutting down MCP HTTP server...');\n      // Add server.close() logic if available in the returned server object\n      process.exit(0);\n    });\n  } catch (error) {\n    console.error('Failed to start MCP HTTP Server:', error);\n    process.exit(1);\n  }\n};\n\nmain();","lang":"typescript","description":"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."},"warnings":[{"fix":"Always explicitly set the `port` in the `startSseAndStreamableHttpMcpServer` configuration object, for example: `{ port: 3000 }`.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"Custom 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"When 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The `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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Choose a different port for the `mcp-http-server` (e.g., `port: 4000`) or identify and terminate the process currently occupying the port.","cause":"The specified port (e.g., 3000) for the MCP HTTP server is already being used by another process on your system.","error":"Error: listen EADDRINUSE: address already in use :::3000"},{"fix":"Ensure `createMcpServer` is a valid asynchronous function that returns an MCP server instance, as demonstrated in the quickstart example.","cause":"The `createMcpServer` parameter was either omitted or provided with a non-function value in the `startSseAndStreamableHttpMcpServer` configuration object.","error":"TypeError: createMcpServer is not a function"},{"fix":"Install the necessary dependency: `npm install @modelcontextprotocol/sdk/server`.","cause":"The `@modelcontextprotocol/sdk/server` package, commonly required by implementations of the `createMcpServer` factory function, has not been installed as a dependency.","error":"Cannot find module '@modelcontextprotocol/sdk/server'"},{"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.","cause":"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.","error":"405 Method Not Allowed"}],"ecosystem":"npm"}