invoke asyn method in mcp tool through StreamableHttpTransport cause early return from tool call

[junjiexv]

Describe the bug
when calling a asyn method in tool callbak, always raise an error "No connection established for request ID".

this error will be catched internal, makes tool call looks like pending.

To Reproduce
Steps to reproduce the behavior:

1. register a echo tool like following:

server.registerTool(
'echo',
{
title: 'Echo Tool',
description: 'Echoes back the provided message',
inputSchema: { message: z.string() }
},
async ({ message }) => {
logger.info(Echo tool called with message: ${message});

      // await aync call will cause the response return immediately
      await new Promise(resolve => {
        setTimeout(resolve, 1)
      })

      // when returning from this, the reported error will be raised
      return {
        content: [{ type: 'text', text: `Tool echo: ${message}` }]
      };
    }
  );

Expected behavior
async call in a tool should be allowed.

Logs

Additional context
error screenshot

[hfzhae]

I have encountered a similar problem as well. Have you resolved your issue?

[junjiexv]

I use this work around: create a promise before the mcp tool execution, when tool called, resolve it manually.

[xiangzhicjm-cyber]

@junjiexv I have encountered similar error too. "Early create a promise and resolve it manually later" seems that extract all the logic before async callback，but how to deal with the input arguments?

[junjiexv]

detail on my workaround(eggjs):
// 1. Create signal Promise (during request handling in EggJS controller)
const signal = {
promise: new Promise(resolve => { signal.resolve = resolve; })
};

// 2. Store signal in request headers (EggJS context)
this.ctx.request.headers['finsignal'] = signal;

// 3. Async handling during tool registration in EggJS service
server.registerTool('asyncTool', schema, async (params, ex) => {
return new Promise(async (resolve) => {
const finish = (result) => {
// Resolve result first
resolve(result);

  // Key: Delay signal by 1ms
  setTimeout(() => signal.resolve(), 1);
};

// Simulate async operation
setTimeout(() => {
  finish({ content: [{ type: 'text', text: 'Async operation completed' }] });
}, 1000);

});
});

// 4. Wait for signal before ending request processing (EggJS middleware)
await transport.handleRequest(req, res, body);
await signal.promise; // Wait for tool async operations to fully complete

Core Principle
Timing Control:

Tool Call → resolve(result) → setTimeout(1ms) → signal.resolve() → Request End
↑ ↑
Immediate Return Delayed Completion Signal

Why 1ms Delay is Needed:
resolve(result) adds result to microtask queue
setTimeout(1) adds signal sending to macrotask queue
Ensures microtasks (like schema validation) complete before macrotasks

[mcp-claude]

Thanks for the detailed report! This was a real bug in the old StreamableHTTPServerTransport (v1.x through ~Aug 2025 / commit 3dd074f), and it's been fixed in the current codebase.

Root cause

In the old implementation, handleRequest() returned its Promise as soon as the HTTP request was parsed and the async tool handler was started — not when it finished. For SSE responses, the ServerResponse was kept alive only by internal state, with a res.on('close', ...) listener that cleaned up the stream mapping when the response was closed.

If a framework (EggJS, or any framework that calls res.end() / socket.destroy() after the handler's Promise resolves) closed the response while the async tool was still awaiting, one of two failures would occur:

1. The 'close' event fires before the tool completes → stream mapping is deleted → send() throws "No connection established for request ID: ..."
2. The 'close' event fires after send() writes → ERR_STREAM_WRITE_AFTER_END unhandled error crash

I reproduced both behaviors with a 50 ms async tool handler on the old code: the normal path (framework doesn't close res) succeeds, while calling res.end() after handleRequest() returns causes a process-crashing ERR_STREAM_WRITE_AFTER_END.

Fix (already landed)

PR #1209 (Dec 2025) rewrote StreamableHTTPServerTransport as a thin wrapper around WebStandardStreamableHTTPServerTransport via @hono/node-server's getRequestListener. The Hono adapter awaits the full response body (the SSE ReadableStream) before resolving, so handleRequest() now only resolves after the tool result has been written and the stream has been closed. Frameworks that call res.end() after handleRequest() returns will find the response already cleanly ended — there's no window for premature closure.

Verification

• Reproduced on old code (commit 3dd074f8): res.end() after handleRequest() returns → crash with ERR_STREAM_WRITE_AFTER_END
• Cannot reproduce on current origin/v1.x (v1.29.0): handleRequest() blocks until the tool result is fully sent
• Cannot reproduce on main (v2): same behaviour

Recommendation

Upgrade to v1.x ≥ v1.18.0 (the first release after PR #1209). No code changes are needed on the server side — the handleRequest() contract now works as intuitively expected. If you were using the workaround of calling transport.close() inside the request handler, you can safely remove it.