SQS Visibility Timeout for MCP Servers — Lambda Relationship, ChangeMessageVisibility, Heartbeat Pattern

How visibility timeout interacts with at-least-once delivery

The SQS message lifecycle has three key events:

1. ReceiveMessage: the message is returned to the consumer and immediately hidden for VisibilityTimeout seconds.
2. DeleteMessage: the consumer calls this after successfully processing. The message is permanently removed.
3. Timeout expiry: if DeleteMessage is never called, the message becomes visible again. Its ApproximateReceiveCount increments.

When ApproximateReceiveCount exceeds the dead-letter queue's maxReceiveCount, the message is sent to the DLQ instead of being re-enqueued. This is the only automatic failsafe against a poison-pill message — one that always causes the consumer to crash — looping forever in the queue.

Visibility timeout and Lambda function timeout

The critical constraint: if the Lambda function timeout fires while a message is still being processed, Lambda does not automatically delete or extend the message — the function execution terminates, and the message becomes visible again.

AWS's documented recommendation is to set the queue visibility timeout to at least 6× the Lambda function timeout. The rationale: if Lambda retries the invocation (rare but possible on internal errors), the second invocation has time to complete without racing the first one's visibility window.

import { Queue, Duration } from 'aws-cdk-lib/aws-sqs';
import { Function, Runtime } from 'aws-cdk-lib/aws-lambda';
import { SqsEventSource } from 'aws-cdk-lib/aws-lambda-event-sources';

const lambdaTimeout = Duration.seconds(30);

const probeQueue = new Queue(this, 'ProbeQueue', {
  visibilityTimeout: Duration.seconds(lambdaTimeout.toSeconds() * 6),  // 180s
  deadLetterQueue: {
    queue: dlq,
    maxReceiveCount: 3,
  },
});

const probeFunction = new Function(this, 'ProbeFunction', {
  timeout: lambdaTimeout,
  // ...
});

probeFunction.addEventSource(new SqsEventSource(probeQueue, {
  batchSize: 1,
  // Lambda ESM manages visibility extension automatically
}));

Lambda ESM automatic visibility extension

When Lambda processes SQS messages via an Event Source Mapping (ESM), it automatically calls ChangeMessageVisibility on each in-flight message at roughly two-thirds of the way through the function timeout. This extends the visibility window, preventing the message from reappearing while the function is still running.

Specifically, if the function timeout is T seconds, Lambda ESM extends visibility at approximately 2T/3 seconds into the invocation. The extension sets a new visibility timeout equal to the queue's configured VisibilityTimeout — not the remaining function time. This can create an unexpectedly long re-hide window if your queue's visibility timeout is large.

What Lambda ESM does not do:

• It does not extend visibility for messages in a batch where individual messages take varying amounts of time — the extension applies to all messages in the batch at once.
• It does not call ChangeMessageVisibility more than once per invocation. If your function runs longer than 2× the function timeout (possible with certain async patterns), the message may reappear.
• It does not extend visibility when the function is in the process of terminating due to a timeout error.

ChangeMessageVisibility: extending manually for non-Lambda consumers

For ECS-based probe workers or Node.js/Go processes that poll SQS directly, you must extend visibility manually. The ChangeMessageVisibility call updates the timeout from the current moment — it does not add to the remaining time, it resets it.

import { SQSClient, ChangeMessageVisibilityCommand, DeleteMessageCommand } from '@aws-sdk/client-sqs';

const sqs = new SQSClient({});
const VISIBILITY_TIMEOUT_SEC = 60;    // queue setting
const HEARTBEAT_INTERVAL_SEC = 20;    // extend every 1/3 of the timeout

async function processWithHeartbeat(
  queueUrl: string,
  receiptHandle: string,
  work: () => Promise
): Promise {
  let heartbeatTimer: NodeJS.Timeout | undefined;

  const heartbeat = async () => {
    try {
      await sqs.send(new ChangeMessageVisibilityCommand({
        QueueUrl: queueUrl,
        ReceiptHandle: receiptHandle,
        VisibilityTimeout: VISIBILITY_TIMEOUT_SEC,  // reset to full timeout
      }));
    } catch (err) {
      // If the message is already deleted, ReceiptHandleIsInvalid — stop heartbeat
      clearInterval(heartbeatTimer!);
    }
  };

  heartbeatTimer = setInterval(heartbeat, HEARTBEAT_INTERVAL_SEC * 1000);

  try {
    await work();
    await sqs.send(new DeleteMessageCommand({ QueueUrl: queueUrl, ReceiptHandle: receiptHandle }));
  } finally {
    clearInterval(heartbeatTimer);
  }
}

The heartbeat interval should be visibilityTimeout / 3: frequent enough to avoid expiry, infrequent enough to avoid unnecessary API calls. SQS charges per API call, so a 5-second heartbeat on a high-volume queue is expensive. For a 60-second visibility timeout, a 20-second heartbeat is appropriate.

Maximum visibility timeout and 12-hour limit

The maximum visibility timeout you can set on a queue is 12 hours. The maximum value for a single ChangeMessageVisibility call is also 12 hours. However, the total visibility duration across all extensions for one receive attempt is capped at 12 hours from the initial receive. After 12 hours, the message reappears regardless of extensions.

For MCP probe pipelines with processing times in the seconds-to-minutes range, the 12-hour cap is never relevant. It matters only for batch-archival or report-generation consumers that may run for hours.

Common failure modes