http-mcp-server

A minimal Model Context Protocol (MCP) HTTP server implementing the 2026-07-28 protocol, including the Tasks extension. Zero runtime dependencies.

Usage

Run directly with npx (requires Node.js 24+):

npx http-mcp-server

Or install and run:

npm install -g http-mcp-server
http-mcp-server

The server listens on http://127.0.0.1:8456/mcp.

Related MCP server: nitro-mcp-server

Configuration

Endpoints

• POST /mcp — MCP JSON-RPC over HTTP (2026-07-28)

• POST /mcp-no-tools — same, but tools/list returns no tools (for testing empty-server behavior)

• GET /mcp — SSE stream

Protocol

• Discovery: server/discover advertises supported protocol versions and the io.modelcontextprotocol/tasks extension capability. Legacy initialize is also supported.

• Headers: requests carrying MCP-Protocol-Version, Mcp-Method, and Mcp-Name headers are validated against the body (-32020 on mismatch, -32022 for unsupported versions). Requests without the new-style headers are accepted for backward compatibility.

• Tasks: clients that declare io.modelcontextprotocol/tasks in their per-request _meta.io.modelcontextprotocol/clientCapabilities.extensions receive a task handle (resultType: "task") from thx_slow_echo and poll tasks/get until a terminal state, answering elicitations via tasks/update and cancelling via tasks/cancel.

Tools

thx_slow_echo example

{
  "name": "thx_slow_echo",
  "arguments": { "text": "hello", "delayMs": 1000, "requireApproval": false }
}

The call returns a task handle:

{
  "result": {
    "resultType": "task",
    "taskId": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "status": "working",
    "statusMessage": "echoing 'hello' in 1000ms",
    "createdAt": "2026-08-29T10:30:00Z",
    "lastUpdatedAt": "2026-08-29T10:30:00Z",
    "ttlMs": 3600000,
    "pollIntervalMs": 100
  }
}

Poll tasks/get until the task reaches completed, failed, or cancelled. With requireApproval: true the task enters input_required and surfaces an elicitation/create request under inputRequests; answer it with tasks/update and inputResponses.

Development

npm install
npm test        # run tests
npm run lint    # run eslint
npm run format  # format with prettier

License

MIT