npmpackage.info

Gathering detailed insights and metrics for mcp-http-server

Gathering detailed insights and metrics for mcp-http-server

mcp-http-server - 1.2.2 | npmpackage.info

mcp-http-server

The Open-sourced Multimodal AI Agent Stack connecting Cutting-edge AI Models and Agent Infra.

1.2.2

15,153

Apache-2.0

TypeScript

41.67 kB

Installations

npm install mcp-http-server

Developer Guide

BETA

Typescript

Yes

Module System

CommonJS, ESM

Node Version

22.15.0

NPM Version

10.9.2

Pull Requests

Open

15

Total

543

Closed

35

Merged

493

Issues

Open

190

Total

356

Closed

166

Releases

27

v0.2.2

Updated on Jul 09, 2025

🚀 Introducing Agent TARS CLI

@agent-tars@0.2.9

Updated on Jul 03, 2025

Agent-TARS-v1.0.0-alpha.10

Agent-TARS-v1.0.0-alpha.10

Updated on Jun 28, 2025

v0.2.1

Updated on Jun 25, 2025

v0.2.0

Updated on Jun 11, 2025

v0.1.3

Updated on Jun 07, 2025

View All 27 releases

Languages

8

TypeScript

MDX

JavaScript

CSS

Less

HTML

Shell

Dockerfile

TypeScript (92.09%)

MDX (4.09%)

JavaScript (1.63%)

CSS (1.52%)

Less (0.32%)

HTML (0.22%)

Shell (0.06%)

Dockerfile (0.06%)

Developer

Download Statistics

Total Downloads

0

Last Day

0

Last Week

0

Last Month

0

Last Year

0

GitHub Statistics

Apache-2.0 License

15,153 Stars

556 Commits

1,349 Forks

137 Watchers

102 Branches

41 Contributors

Updated on Jul 13, 2025

Maintainers

1

View All 41 Contributors

Package Meta Information

Latest Version

1.2.2

Package Id

mcp-http-server@1.2.2

Unpacked Size

41.67 kB

Size

10.60 kB

File Count

11

NPM Version

10.9.2

Node Version

22.15.0

Published on

Jul 09, 2025

Total Downloads

Cumulative downloads

Total Downloads

NaN

Last Day

0%

NaN

Compared to previous day

Last Week

0%

NaN

Compared to previous week

Last Month

0%

NaN

Compared to previous month

Last Year

0%

NaN

Compared to previous year

Weekly Downloads

Monthly Downloads

Yearly Downloads

Dependencies

3

@modelcontextprotocol/sdk express @agent-infra/logger

Dev Dependencies

10

get-port @types/express cross-fetch @rslib/core tsx vitest @types/diff @types/minimatch @types/node typescript

MCP HTTP Server

A high performance HTTP+SSE Server with Request Headers for MCP Server.

Features

HTTP/SSE Transport: Support for both HTTP POST and Server-Sent Events
Flexible Routing: Configurable endpoint paths and prefixes
Request Headers: Access to HTTP headers in MCP server context
Multiple Transports: Both stateful and stateless modes
Middleware Support: Custom middleware for authentication, logging, etc.

Install

1npm i mcp-http-server -S

Quick Start

1import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';
2import { createServer } from './server.js';
3
4await startSseAndStreamableHttpMcpServer({
5  port: 3000,
6  createMcpServer: async (params) => {
7    console.log('Request headers:', params.headers);
8    return createServer();
9  },
10});

API Reference

`startSseAndStreamableHttpMcpServer(params)`

Parameters

Parameter	Type	Description
`port`	`number`	Port to listen on (default: 8080)
`host`	`string`	Host to bind to (default: '::')
`stateless`	`boolean`	Enable stateless mode for streamable HTTP (default: true)
`middlewares`	`MiddlewareFunction[]`	Custom Express middlewares
`routes`	`RoutesConfig`	Custom route configuration
`logger`	`Logger`	Custom logger instance
`createMcpServer`	`function`	Factory function to create MCP server instances

Route Configuration

The server supports flexible route configuration through the routes parameter.

Default Routes

By default, the server uses the following routes:

1{
2  prefix: '/',      // Route prefix for all endpoints
3  mcp: '/mcp',      // MCP endpoint path
4  message: '/message', // Message endpoint path for SSE
5  sse: '/sse'       // SSE endpoint path
6}

This creates the following endpoints:

POST /mcp - MCP HTTP transport
GET /mcp - Returns 405 (Method Not Allowed) or SSE stream
GET /sse - SSE connection endpoint
POST /message - SSE message endpoint

Custom Routes

You can customize routes using the routes configuration:

1await startSseAndStreamableHttpMcpServer({
2  port: 3000,
3  routes: {
4    prefix: '/api/v1',
5    mcp: '/custom-mcp',
6    message: '/custom-message',
7    sse: '/custom-sse'
8  },
9  createMcpServer: async () => createServer(),
10});

This creates endpoints at:

POST /api/v1/custom-mcp - MCP HTTP transport
GET /api/v1/custom-mcp - Returns 405 or SSE stream
GET /api/v1/custom-sse - SSE connection endpoint
POST /api/v1/custom-message - SSE message endpoint

Route Configuration Options

`routes.prefix`

Type: string
Default: '/'
Description: Route prefix for all endpoints

`routes.mcp`

Type: string
Default: '/mcp'
Description: MCP endpoint path (relative to prefix)

`routes.message`

Type: string
Default: '/message'
Description: Message endpoint path for SSE (relative to prefix)

`routes.sse`

Type: string
Default: '/sse'
Description: SSE endpoint path (relative to prefix)

Path Handling

The server automatically handles leading/trailing slashes in paths:

1// These configurations are equivalent:
2routes: {
3  prefix: '/api/v2/',
4  mcp: 'mcp-endpoint',
5  sse: '/sse-endpoint/'
6}
7
8routes: {
9  prefix: '/api/v2',
10  mcp: '/mcp-endpoint',
11  sse: 'sse-endpoint'
12}

Both result in:

/api/v2/mcp-endpoint
/api/v2/sse-endpoint/

Usage Examples

Basic HTTP Server

1import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';
2import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
4const server = await startSseAndStreamableHttpMcpServer({
5  port: 3000,
6  createMcpServer: async () => {
7    return new Server(
8      { name: 'my-server', version: '1.0.0' },
9      { capabilities: { tools: {} } }
10    );
11  },
12});
13
14console.log(`Server running at ${server.url}`);

With Custom Routes and Middleware

1import { startSseAndStreamableHttpMcpServer } from 'mcp-http-server';
2
3const authMiddleware = (req, res, next) => {
4  const token = req.headers.authorization;
5  if (!token) {
6    return res.status(401).json({ error: 'Unauthorized' });
7  }
8  next();
9};
10
11await startSseAndStreamableHttpMcpServer({
12  port: 3000,
13  host: 'localhost',
14  routes: {
15    prefix: '/api/v1',
16    mcp: '/mcp',
17    sse: '/events'
18  },
19  middlewares: [authMiddleware],
20  createMcpServer: async (context) => {
21    console.log('User agent:', context.headers['user-agent']);
22    return createServer();
23  },
24});

Command Line Interface

1import { program } from 'commander';
2import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
3
4program
5  .name('mcp-server')
6  .description('MCP server with HTTP and stdio support')
7  .version('1.0.0')
8  .option('--host <host>', 'host to bind server to')
9  .option('--port <port>', 'port to listen on for HTTP transport')
10  .option('--prefix <prefix>', 'route prefix for HTTP endpoints', '/api')
11  .action(async (options) => {
12    try {
13      if (options.port || options.host) {
14        // HTTP/SSE transport
15        await startSseAndStreamableHttpMcpServer({
16          host: options.host,
17          port: options.port ? parseInt(options.port) : undefined,
18          routes: {
19            prefix: options.prefix,
20          },
21          createMcpServer: async (params) => {
22            console.log('HTTP request from:', params.headers['user-agent']);
23            return createServer();
24          },
25        });
26      } else {
27        // Stdio transport
28        const server = createServer();
29        const transport = new StdioServerTransport();
30        await server.connect(transport);
31        console.debug('MCP Server running on stdio');
32      }
33    } catch (error) {
34      console.error('Error:', error);
35      process.exit(1);
36    }
37  });
38
39program.parse();

Transport Modes

Stateful Mode (Default: Stateless)

1await startSseAndStreamableHttpMcpServer({
2  stateless: false, // Enable stateful mode
3  createMcpServer: async () => createServer(),
4});

In stateful mode:

Each client gets a unique session ID
Sessions are maintained across requests
Requires proper session cleanup

Stateless Mode (Recommended)

1await startSseAndStreamableHttpMcpServer({
2  stateless: true, // Default
3  createMcpServer: async () => createServer(),
4});

In stateless mode:

No session state maintained
Each request is independent
Better for scaling and reliability

Return Value

startSseAndStreamableHttpMcpServer returns a McpServerEndpoint object:

1interface McpServerEndpoint {
2  url: string;      // Full URL to MCP endpoint
3  sseUrl: string;   // Full URL to SSE endpoint
4  port: number;     // Server port
5  close: () => void; // Function to close server
6}

Example:

1const endpoint = await startSseAndStreamableHttpMcpServer({
2  port: 3000,
3  routes: { prefix: '/api' },
4  createMcpServer: async () => createServer(),
5});
6
7console.log('MCP endpoint:', endpoint.url);     // http://localhost:3000/api/mcp
8console.log('SSE endpoint:', endpoint.sseUrl);  // http://localhost:3000/api/sse
9
10// Gracefully shutdown
11process.on('SIGTERM', () => {
12  endpoint.close();
13});

License

MIT

Empty State

No vulnerabilities found.

10

Maintained

Determines if the project is "actively maintained".

10

Security-Policy

Determines if the project has published a security policy.

10

Dangerous-Workflow

Determines if the project's GitHub Action workflows avoid dangerous patterns.

10

Binary-Artifacts

Determines if the project has generated executable (binary) artifacts in the source repository.

10

License

Determines if the project has defined a license.

10

Contributors

Determines if the project has a set of contributors from multiple organizations (e.g., companies).

9

SAST

Determines if the project uses static code analysis.

9

CI-Tests

Determines if the project runs tests before pull requests are merged.

3

Pinned-Dependencies

Determines if the project has declared and pinned the dependencies of its build process.

Reason

dependency not pinned by hash detected -- score normalized to 3

Details

Warn: third-party GitHubAction not pinned by hash: .github/workflows/test.yml:50: update your workflow using https://app.stepsecurity.io/secureworkflow/bytedance/UI-TARS-desktop/test.yml/main?enable=pin
Warn: containerImage not pinned by hash: packages/agent-infra/mcp-servers/filesystem/Dockerfile:1
Warn: containerImage not pinned by hash: packages/agent-infra/mcp-servers/filesystem/Dockerfile:13
Warn: npmCommand not pinned by hash: packages/agent-infra/mcp-servers/browser/Dockerfile:33
Warn: npmCommand not pinned by hash: packages/agent-infra/mcp-servers/browser/Dockerfile:42
Warn: npmCommand not pinned by hash: packages/agent-infra/mcp-servers/browser/Dockerfile.http:33
Warn: npmCommand not pinned by hash: packages/agent-infra/mcp-servers/browser/Dockerfile.http:42
Warn: npmCommand not pinned by hash: packages/agent-infra/mcp-servers/filesystem/Dockerfile:8
Warn: npmCommand not pinned by hash: .github/workflows/agent_tars_test.yml:33
Warn: npmCommand not pinned by hash: .github/workflows/benchmark.yml:42
Warn: pipCommand not pinned by hash: .github/workflows/benchmark.yml:50
Warn: pipCommand not pinned by hash: .github/workflows/benchmark.yml:51
Warn: npmCommand not pinned by hash: .github/workflows/e2e-ui-tars.yml:49
Warn: npmCommand not pinned by hash: .github/workflows/e2e-ui-tars.yml:59
Warn: npmCommand not pinned by hash: .github/workflows/release-ui-tars.yml:29
Warn: npmCommand not pinned by hash: .github/workflows/release-ui-tars.yml:37
Warn: npmCommand not pinned by hash: .github/workflows/release-ui-tars.yml:95
Warn: npmCommand not pinned by hash: .github/workflows/release-ui-tars.yml:103
Warn: npmCommand not pinned by hash: .github/workflows/release-ui-tars.yml:164
Warn: npmCommand not pinned by hash: .github/workflows/test.yml:46
Info: 25 out of 25 GitHub-owned GitHubAction dependencies pinned
Info: 4 out of 5 third-party GitHubAction dependencies pinned
Info: 2 out of 4 containerImage dependencies pinned
Info: 2 out of 17 npmCommand dependencies pinned
Info: 0 out of 2 pipCommand dependencies pinned

2

Code-Review

Determines if the project requires human code review before pull requests (aka merge requests) are merged.

0

Token-Permissions

Determines if the project's workflows follow the principle of least privilege.

0

CII-Best-Practices

Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.

0

Dependency-Update-Tool

Determines if the project uses a dependency update tool.

0

Signed-Releases

Determines if the project cryptographically signs release artifacts.

0

Fuzzing

Determines if the project uses fuzzing.

0

Vulnerabilities

Determines if the project has open, known unfixed vulnerabilities.

Score

4.8

/10

Last Scanned on 2025-07-12T18:31:21Z

The Open Source Security Foundation is a cross-industry collaboration to improve the security of open source software (OSS). The Scorecard provides security health metrics for open source projects.