MCP Server Lambda Response Streaming — SSE transport, chunked JSON, streamifyResponse

BUFFERED vs RESPONSE_STREAM invoke modes

Lambda Function URLs support two invoke modes. The mode is set at the Function URL resource, not per-request.

You cannot switch invoke modes on an existing Function URL without recreating it. In CDK, switching invokeMode triggers a URL replacement (the URL hostname changes), so update any DNS records or MCP client configurations that hardcode the Function URL hostname.

Implementing streamifyResponse for MCP SSE transport

The awslambda global is available in Node.js Lambda runtimes without any package install. The streamifyResponse wrapper transforms your handler signature to receive a writable responseStream argument instead of returning a value.

// mcp-handler-streaming.ts
// Runtime: nodejs22.x — awslambda is a global, no import needed
import { APIGatewayProxyEventV2 } from "aws-lambda";

const handler = awslambda.streamifyResponse(
  async (
    event: APIGatewayProxyEventV2,
    responseStream: AWSLambda.ResponseStream,
    context: AWSLambda.Context
  ) => {
    // Headers must be written before any body data
    const metadata = {
      statusCode: 200,
      headers: {
        "Content-Type": "text/event-stream",
        "Cache-Control": "no-cache",
        "X-Accel-Buffering": "no",  // prevent nginx/Caddy from buffering SSE
      },
    };
    responseStream = awslambda.HttpResponseStream.from(responseStream, metadata);

    // Write SSE events as chunks
    const writeEvent = (event: string, data: unknown) => {
      responseStream.write(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
    };

    try {
      // MCP initialize response
      writeEvent("message", {
        jsonrpc: "2.0",
        id: 1,
        result: {
          protocolVersion: "2024-11-05",
          capabilities: { tools: {} },
          serverInfo: { name: "alivemcp-probe", version: "1.0.0" },
        },
      });

      // Stream tool call result progressively
      const toolResults = await runToolCallInChunks(event);
      for await (const chunk of toolResults) {
        writeEvent("message", {
          jsonrpc: "2.0",
          id: chunk.id,
          result: { content: [{ type: "text", text: chunk.text }] },
        });
      }
    } finally {
      responseStream.end();
    }
  }
);

export { handler };

Critical ordering: responseStream.write() called before awslambda.HttpResponseStream.from() will silently drop data — always attach metadata (headers/status) to the stream before writing body bytes. The finally { responseStream.end() } is mandatory; forgetting it causes the client connection to hang until the Lambda function timeout.

CDK: Function URL with RESPONSE_STREAM invoke mode

import * as lambda from "aws-cdk-lib/aws-lambda";
import * as lambdaNodeJs from "aws-cdk-lib/aws-lambda-nodejs";
import { Duration } from "aws-cdk-lib";

const mcpStreamingFn = new lambdaNodeJs.NodejsFunction(this, "McpStreamingFn", {
  entry: "src/mcp-handler-streaming.ts",
  runtime: lambda.Runtime.NODEJS_22_X,
  timeout: Duration.minutes(15),  // streaming connections can be long-lived
  memorySize: 512,
  bundling: {
    // awslambda global is not in @types/aws-lambda — add type stubs
    externalModules: [],
  },
});

const streamUrl = mcpStreamingFn.addFunctionUrl({
  authType: lambda.FunctionUrlAuthType.NONE,
  invokeMode: lambda.InvokeMode.RESPONSE_STREAM,  // enables streaming
  cors: {
    allowedOrigins: ["*"],
    allowedMethods: [lambda.HttpMethod.POST, lambda.HttpMethod.GET],
    allowedHeaders: ["Content-Type", "Authorization"],
  },
});

The 15-minute timeout is relevant for SSE connections — an MCP client holding an open SSE channel will keep the Lambda instance alive for as long as the handler is running. AliveMCP's probe uses a 30-second timeout on tools/list calls regardless of invoke mode, so a streaming endpoint that stalls without writing any data will trigger an AliveMCP alert after 30 seconds.

Payload size and throughput limits

For MCP tool results that could exceed 20 MB (large file reads, database dumps), split the tool into paginated calls and have the MCP client invoke multiple times with a cursor parameter rather than streaming a single oversized response.

Monitoring streaming endpoints with CloudWatch

# Average bytes streamed per invocation (useful for baseline baselining)
aws cloudwatch get-metric-statistics \
  --namespace AWS/Lambda \
  --metric-name ResponseStreamingDataLength \
  --dimensions Name=FunctionName,Value=McpStreamingFn \
  --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --period 60 --statistics Average

# Throughput in bytes/second — alert if drops below baseline
aws cloudwatch get-metric-statistics \
  --namespace AWS/Lambda \
  --metric-name ResponseStreamingThroughput \
  --dimensions Name=FunctionName,Value=McpStreamingFn \
  --start-time $(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ) \
  --end-time $(date -u +%Y-%m-%dT%H:%M:%SZ) \
  --period 60 --statistics Average

AliveMCP tracks total response time (time-to-first-byte + time-to-stream-complete) and flags streaming endpoints where time-to-first-byte exceeds 5 seconds — this usually means the handler is doing synchronous work before calling responseStream.write() for the first time, negating the value of streaming.

Common failure modes