MCP client does not work with streamable http server

[ajshedivy]

Template Version: 1.7.0
Node.js Version: v22.6.0

Summary

The HTTP transport layer in the MCP TypeScript template has critical bugs that prevent it from working with built-in MCP clients and external MCP clients. The server crashes immediately upon receiving HTTP requests due to multiple Hono framework-related errors.

here is the Error trace:

🚀 MCP Server running at: http://127.0.0.1:3010/mcp

2025-07-17 13:13:07 debug: Running MCP Authentication Middleware (Bearer Token Validation)...
  Meta: {
  "requestId": "e5b3832c-cff7-422e-8703-7db7aa4254a4",
  "operation": "mcpAuthMiddleware",
  "method": "POST",
  "path": "/mcp"
}
2025-07-17 13:13:07 warn: Bypassing JWT authentication: MCP_AUTH_SECRET_KEY is not set (DEVELOPMENT ONLY).
  Meta: {
  "requestId": "e5b3832c-cff7-422e-8703-7db7aa4254a4",
  "operation": "mcpAuthMiddleware",
  "method": "POST",
  "path": "/mcp"
}
2025-07-17 13:13:07 debug: Dev mode auth object created.
  Meta: {
  "requestId": "e5b3832c-cff7-422e-8703-7db7aa4254a4",
  "operation": "mcpAuthMiddleware",
  "method": "POST",
  "path": "/mcp",
  "authDetails": {
    "token": "dev-mode-placeholder-token",
    "clientId": "dev-client-id",
    "scopes": [
      "dev-scope"
    ]
  }
}
2025-07-17 13:13:07 info: Initializing MCP server instance
  Meta: {
  "requestId": "aa6e115d-7cb5-4758-a1d7-09c9ef6f660e",
  "operation": "createMcpServerInstance"
}
2025-07-17 13:13:07 debug: RequestContextService configuration updated
  Meta: {
  "requestId": "19b2ad17-ddb6-4f62-9b84-23cdf9c606e4",
  "operation": "RequestContextService.configure",
  "newConfigState": {
    "appName": "mcp-ts-template",
    "appVersion": "1.7.0",
    "environment": "development"
  }
}
2025-07-17 13:13:07 debug: Registering resources and tools...
  Meta: {
  "requestId": "aa6e115d-7cb5-4758-a1d7-09c9ef6f660e",
  "operation": "createMcpServerInstance"
}
2025-07-17 13:13:07 info: Registering resource: 'echo-resource'
  Meta: {
  "requestId": "bdef93d9-35e5-42e0-958e-0743ac2a99eb",
  "operation": "RegisterResource",
  "resourceName": "echo-resource"
}
2025-07-17 13:13:07 info: Resource 'echo-resource' registered successfully.
  Meta: {
  "requestId": "bdef93d9-35e5-42e0-958e-0743ac2a99eb",
  "operation": "RegisterResource",
  "resourceName": "echo-resource"
}
2025-07-17 13:13:07 info: Registering tool: 'echo_message'
  Meta: {
  "requestId": "0ef735e2-8c2f-4fcd-b6d5-8c4caa0bbc3a",
  "operation": "RegisterTool",
  "toolName": "echo_message"
}
2025-07-17 13:13:07 info: Tool 'echo_message' registered successfully.
  Meta: {
  "requestId": "0ef735e2-8c2f-4fcd-b6d5-8c4caa0bbc3a",
  "operation": "RegisterTool",
  "toolName": "echo_message"
}
2025-07-17 13:13:07 info: Registering tool: 'get_random_cat_fact'
  Meta: {
  "requestId": "61266cf4-bf7a-4df2-9979-364d978c7a83",
  "operation": "RegisterTool",
  "toolName": "get_random_cat_fact"
}
2025-07-17 13:13:07 info: Tool 'get_random_cat_fact' registered successfully.
  Meta: {
  "requestId": "61266cf4-bf7a-4df2-9979-364d978c7a83",
  "operation": "RegisterTool",
  "toolName": "get_random_cat_fact"
}
2025-07-17 13:13:07 info: Tool 'fetch_image_test' registered.
  Meta: {
  "requestId": "fc5b8ce5-0304-44d7-8d63-79027c5acde1",
  "operation": "registerFetchImageTestTool"
}
2025-07-17 13:13:07 info: Resources and tools registered successfully
  Meta: {
  "requestId": "aa6e115d-7cb5-4758-a1d7-09c9ef6f660e",
  "operation": "createMcpServerInstance"
}
2025-07-17 13:13:07 info: HTTP Session created: 417a3802-eb56-4267-b9f8-a7a977544613
  Meta: {
  "requestId": "97dce72f-9429-459d-bee5-5b6e2fdf1d80",
  "operation": "handlePost",
  "transport": "http",
  "component": "HttpTransportSetup",
  "newSessionId": "417a3802-eb56-4267-b9f8-a7a977544613"
}
2025-07-17 13:13:07 error: Error in httpTransport: Error in httpTransport: init["status"] must be in the range of 200 to 599, inclusive.
  Meta: {
  "requestId": "cf395253-78cb-409d-9097-cd3c31209356",
  "operation": "httpErrorHandler",
  "critical": false,
  "errorCode": "VALIDATION_ERROR",
  "originalErrorType": "RangeError",
  "finalErrorType": "McpError",
  "path": "/mcp",
  "method": "POST",
  "errorDetails": {
    "requestId": "cf395253-78cb-409d-9097-cd3c31209356",
    "timestamp": "2025-07-17T18:13:07.452Z",
    "operation": "httpErrorHandler",
    "path": "/mcp",
    "method": "POST",
    "originalErrorName": "RangeError",
    "originalMessage": "init[\"status\"] must be in the range of 200 to 599, inclusive.",
    "originalStack": "RangeError: init[\"status\"] must be in the range of 200 to 599, inclusive.\n    at initializeResponse (node:internal/deps/undici/undici:9030:15)\n    at new Response (node:internal/deps/undici/undici:8822:9)\n    at [getResponseCache] (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:196:36)\n    at get headers (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:227:34)\n    at set res (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/context.js:74:16)\n    at dispatch (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/compose.js:38:21)\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)\n    at async file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/dist/mcp-server/transports/httpTransport.js:134:9\n    at async dispatch (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/compose.js:22:17)\n    at async file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/dist/mcp-server/transports/httpTransport.js:121:9"
  },
  "stack": "McpError: Error in httpTransport: init[\"status\"] must be in the range of 200 to 599, inclusive.\n    at ErrorHandler.handleError (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/dist/utils/internal/errorHandler.js:209:19)\n    at httpErrorHandler (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/dist/mcp-server/transports/httpErrorHandler.js:25:39)\n    at dispatch (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/compose.js:26:25)\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)\n    at async file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/dist/mcp-server/transports/httpTransport.js:121:9\n    at async dispatch (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/compose.js:22:17)\n    at async cors2 (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/middleware/cors/index.js:84:5)\n    at async dispatch (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/compose.js:22:17)\n    at async file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/hono/dist/hono-base.js:201:25\n    at async responseViaResponseObject (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:400:13)"
}
Error [ERR_HTTP_HEADERS_SENT]: Cannot write headers after they are sent to the client
    at ServerResponse.writeHead (node:_http_server:342:11)
    at responseViaResponseObject (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:423:16)
    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)
    at async Server.<anonymous> (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:511:14) {
  code: 'ERR_HTTP_HEADERS_SENT'
}
2025-07-17 13:13:07 error: FATAL: Uncaught exception detected. This indicates a bug or unexpected state. Initiating shutdown...
  Meta: {
  "requestId": "6e69a798-4660-4871-84bb-7fcc230b1b93",
  "operation": "ServerStartupSequence_http",
  "applicationName": "mcp-ts-template",
  "applicationVersion": "1.7.0",
  "nodeEnvironment": "development",
  "triggerEvent": "uncaughtException",
  "errorMessage": "write after end",
  "errorStack": "Error [ERR_STREAM_WRITE_AFTER_END]: write after end\n    at ServerResponse.end (node:_http_outgoing:1093:15)\n    at handleResponseError (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:352:14)\n    at Server.<anonymous> (file:///Users/adamshedivy/Documents/IBM/sandbox/oss/ai/db2i-ai/mcp/ibmi-mcp-server/node_modules/@hono/node-server/dist/index.mjs:513:14)\n    at process.processTicksAndRejections (node:internal/process/task_queues:95:5)"
}
2025-07-17 13:13:07 info: Received uncaughtException. Initiating graceful shutdown...
  Meta: {
  "requestId": "2a27a4d9-0c28-48d6-8cc0-af084929ca3d",
  "operation": "ServerShutdown",
  "triggerEvent": "uncaughtException"
}
2025-07-17 13:13:07 info: Closing HTTP server...
  Meta: {
  "requestId": "2a27a4d9-0c28-48d6-8cc0-af084929ca3d",
  "operation": "ServerShutdown",
  "triggerEvent": "uncaughtException"
}
2025-07-17 13:13:07 info: HTTP server closed successfully.
  Meta: {
  "requestId": "2a27a4d9-0c28-48d6-8cc0-af084929ca3d",
  "operation": "ServerShutdown",
  "triggerEvent": "uncaughtException"
}
2025-07-17 13:13:07 info: Graceful shutdown completed successfully. Exiting.
  Meta: {
  "requestId": "2a27a4d9-0c28-48d6-8cc0-af084929ca3d",
  "operation": "ServerShutdown",
  "triggerEvent": "uncaughtException"
}

NOTE: MCP_AUTH_SECRET_KEY is disabled

Bug Description

The HTTP transport crashes with multiple fatal errors when attempting to handle MCP client connections:

1. Primary Error: init["status"] must be in the range of 200 to 599, inclusive
2. Secondary Error: Cannot write headers after they are sent to the client
3. Fatal Error: write after end causing uncaught exception and server shutdown

Reproduction Steps

Method 1: Direct HTTP Client Connection

1. Configure MCP server for HTTP transport (MCP_TRANSPORT_TYPE=http)
2. Start server with npm run start:http
3. Server starts successfully and shows: 🚀 MCP Server running at: http://127.0.0.1:3010/mcp
4. Attempt to connect with any MCP client to http://localhost:3010/mcp
5. Server immediately crashes with Hono framework errors

Method 2: Supergateway Bridge (External Tool)

1. Configure MCP server for HTTP transport
2. Start server with npm run start:http
3. Use supergateway to bridge HTTP to stdio:

   npx -y supergateway@latest --streamableHttp http://localhost:3010/mcp

4. Server crashes on first connection attempt

Method 3: Built-in MCP Client (mcp-config.json)

{
  "mcpServers": {
    "local-mcp-server-http": {
      "command": "http://localhost:3010",
      "args": [],
      "transportType": "http",
      "disabled": false,
      "autoApprove": true
    }
  }
}

Response:

$ npm run start:agent "what tools do you have access to?"

> mcp-ts-template@1.7.0 start:agent
> MCP_LOG_LEVEL=debug node dist/agent/cli/boot.js what tools do you have access to?

Logger not initialized; message dropped.

--- User Prompt ---
what tools do you have access to?

--- LLM Response ---
{
  "command": "terminate_loop",
  "arguments": {
    "reason": "I do not have access to any tools at the moment. The list of available tools is empty."
  }
}
--------------------

Working response with Stdio:

{
  "mcpServers": {
    "test-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/dist/index.js"
      ]
      "transportType": "stdio",
      "disabled": false,
      "autoApprove": false
    },
  }
}

Response:

$ npm run start:agent "what tools do you have access to?"

> mcp-ts-template@1.7.0 start:agent
> MCP_LOG_LEVEL=debug node dist/agent/cli/boot.js what tools do you have access to?

Logger not initialized; message dropped.

--- User Prompt ---
what tools do you have access to?

--- LLM Response ---
{
  "command": "display_message_to_user",
  "arguments": {
    "message": "I have access to the following tools: 'echo_message', 'get_random_cat_fact', and 'fetch_image_test'."
  }
}
[AGENT]: I have access to the following tools: 'echo_message', 'get_random_cat_fact', and 'fetch_image_test'.
{
  "command": "terminate_loop",
  "arguments": {
    "reason": "I have successfully listed the available tools to the user. My task is complete."
  }
}
--------------------

Have you seen any errors like this during your testing? I might be missing some sort of configuration. The immediate fix for me was to remove hono from the transport path and use a "raw" Node.js HTTP server.

[brenoepics]

@ajshedivy This happens because this template is using Zod to validate all fields at once, if any of them is wrong, it will reset all fields, you can fix that by adding valid fields to everything (like supabase etc.) or changing the code to add per env var validation.