Notifications with StreamableHTTPServerTransport and enableJsonResponse = true

[wr8tt5]

Question: When using the streamable HTTP server transport (StreamableHTTPServerTransport) with its enableJsonResponse option set to true, what is the intended behaviour for handling notifications issued when handling a request (when the notifications are directly related to the request such as progress notifications)?

My expectation: Sending these notifications would be returned together with the request response as a batch of messages in a single response.

My observation: These notifications are absent from the request response. The jsonResponseStreamableHttp.ts example demonstrates this behaviour.

Digging into this, I discovered that the implementation of send() in streamableHttp.ts seemingly drops associated notifications (those with a related request id) on the floor when enableJsonResponse is true.

Included below is an additional test I added temporarily to streamableHttp.test.ts to reproduce the issue and debug it. This test fails on the following expectation.

    expect(Array.isArray(results)).toBe(true);

// Test JSON Response Mode
describe("StreamableHTTPServerTransport with JSON Response Mode", () => { 
...
beforeEach(async () => {
  ...
  mcpServer = result.mcpServer;
  ...
});
...

  /// Additional test ///
  it("should return JSON response for a single request including related notifications", async () => {

    mcpServer.tool(
      "multi-greet",
      "A greeting tool that issues multiple greetings",
      { name: z.string().describe("Name to greet") },
      async ({ name }, { sendNotification, _meta }): Promise<CallToolResult> => {
        const progressToken = _meta?.progressToken || "default-progress-token";

        await sendNotification({
          method: "notifications/progress",
          params: { message: `Starting multi-greet for ${name}`, progress: 1, total: 3, progressToken }
        });

        await sendNotification({
          method: "notifications/progress",
          params: { message: `Sending first greeting to ${name}`, progress: 2, total: 3, progressToken }
        });

        await sendNotification({
          method: "notifications/progress",
          params: { message: `Sending second greeting to ${name}`, progress: 3, total: 3, progressToken }
        });

        return { content: [{ type: "text", text: `Hello, ${name}!` }] };
      }
    );

    const toolsCallMessage: JSONRPCMessage = {
      jsonrpc: "2.0",
      method: "tools/call",
      params: {
        name: "multi-greet",
        arguments: {
          name: "JSON"
        },
        _meta: {
          progressToken: "progress-1",
        }
      },
      id: "json-req-1"
    }

    const response = await sendPostRequest(baseUrl, toolsCallMessage, sessionId);

    expect(response.status).toBe(200);
    expect(response.headers.get("content-type")).toBe("application/json");

    const results = await response.json();
    expect(Array.isArray(results)).toBe(true);
    expect(results).toHaveLength(4);

    // Batch responses can come in any order
    const progressNotifications = results.filter((r: { method?: string, params?: { progressToken?: string } }) => r.method === "notifications/progress" && r.params?.progressToken === "progress-1");
    const callResponse = results.find((r: { id?: string }) => r.id === "json-req-1");

    expect(progressNotifications).toHaveLength(3);

    expect(callResponse).toEqual(expect.objectContaining({
      jsonrpc: "2.0",
      id: "json-req-1",
      result: expect.objectContaining({
        content: expect.arrayContaining([
          expect.objectContaining({ type: "text", text: "Hello, JSON!" })
        ])
      })
    }));
  });

Thanks in advance.

[mozmo15]

My understanding is notifications are only supported in stateful MCP server implementations. And the sdk seems to rely on "text/event-stream" responses to enable statefulness/session resumability. Setting enableJsonResponse to true is explicitly meant for stateless implementations and gives up the ability to send notifications, or make elicitation and sampling requests from the server. From the sdk:

if (this._enableJsonResponse) {
     // All responses ready, send as JSON              
     const headers = {
          'Content-Type': 'application/json',
     };
....
}

[wr8tt5]

In retrospect I made an unfortunate choice when looking at the jsonResponseStreamableHttp.ts example for streaming notifications over HTTP. I didn't realise what the "jsonResponse" part meant in the name until I discovered why notifications are not delivered. Nevertheless, regardless of whether jsonResponse is being used, I believe the result should be the same as enableJsonResponse = false in that enableJsonResponse = true shouldn't silently lose notifications. As it stands, this example confuses people because it seems like the objective is for notifications to be delivered, albeit it not in real time.

[mozmo15]

I agree with you in the sense that it shouldnt silently lose notifications (perhaps some exception or warning should be raised), but if you mean to not lose the notifications at all, I just dont think thats possible. The issue is with application/json schemes is you will have this one-to-one request response pattern where each request-response pair is completely independent. So you only have one JSON-RPC message you can send back in response to your tool call before the whole interaction ends. It would not be possible to send notifications message along with a tool call result message in the same response

[wr8tt5]

Isn't that what the test should return JSON response for batch requests is doing? Sending multiple messages in a single response as an JSON array. What I expected is an array of JSON messages with notification messages preceding their associated response message.

[mozmo15]

Good point. So I was wrong in saying we can only send one json-rpc message per http response. It seems here we are getting a request with multiple json-rpc messages and responding with the same. But we still only send one json-rpc message for each received. So if a tool call message is recieved, a tool call response is sent and nothing more (in JSON response mode).

Also one note regarding batch responses: you can see this comment in the test file: "// Batch responses can come in any order". So even in batch mode you should not expect messages recieved chronologically

Interestingly the only describe block testing JSON response mode is actually using sessionIdGenerator: (() => randomUUID(), so my understanding is this is still a stateful approach but one that doesnt support most features that a stateful mcp server is usually needed for (since it forgoes streaming), such as elicitation, sampling, and notifications mid tool call. Im not sure what the benefit is to generating and attaching then reading the sessionId everytime in JSON response mode when generally the whole request-response pattern disables us from using it in a useful way. I ran the whole test block with sessionIdGenerator as undefined and it behaves the same (all tests still pass)

[felixweinberger]

This is by design. When using enableJsonResponse: true, notifications are intentionally not supported - see PR #299 which introduced this feature: "Returning JSON is more limited in functionality as we are losing streaming tool notification/logging etc."

I've opened #1309 to clarify this in the example. If there's interest in batching notifications into the JSON response, that would be a separate enhancement request.