Step Functions Callback Pattern for MCP Server Orchestration

Injecting the task token

The token lives in the execution context object at $$.Task.Token. The $$ prefix accesses the Step Functions context (not the execution state $). Inject it into the task input using the Parameters field with the .$ suffix on the key name to indicate a JSON path reference:

{
  "InvokeAsyncTool": {
    "Type": "Task",
    "Resource": "arn:aws:states:::lambda:invoke.waitForTaskToken",
    "Parameters": {
      "FunctionName": "arn:aws:lambda:us-east-1:ACCOUNT:function:AsyncToolHandler",
      "Payload": {
        "taskToken.$": "$$.Task.Token",
        "toolName.$": "$.toolName",
        "toolInput.$": "$.toolInput",
        "sessionId.$": "$.sessionId"
      }
    },
    "HeartbeatSeconds": 300,
    "TimeoutSeconds": 600,
    "Retry": [
      {
        "ErrorEquals": ["Lambda.TooManyRequestsException"],
        "MaxAttempts": 3,
        "IntervalSeconds": 1,
        "BackoffRate": 1.5
      }
    ],
    "Catch": [
      {
        "ErrorEquals": ["States.HeartbeatTimeout", "States.Timeout"],
        "ResultPath": "$.error",
        "Next": "HandleTimeout"
      },
      {
        "ErrorEquals": ["States.ALL"],
        "ResultPath": "$.error",
        "Next": "HandleToolError"
      }
    ],
    "End": true
  }
}

The .waitForTaskToken suffix on the resource ARN activates the callback pattern. Without it, the Lambda integration returns immediately after Lambda responds — there is no pause-and-wait behavior.

Worker — storing the token and resuming execution

The Lambda function receives the task token in the event payload. The correct order is: store the token durably first, then begin processing work. This ensures that a worker crash after processing but before calling SendTaskSuccess is recoverable by a retry mechanism:

import { DynamoDBClient, PutItemCommand } from "@aws-sdk/client-dynamodb";
import { SFNClient, SendTaskSuccessCommand, SendTaskFailureCommand } from "@aws-sdk/client-sfn";

const dynamo = new DynamoDBClient({ region: process.env.AWS_REGION });
const sfn = new SFNClient({ region: process.env.AWS_REGION });

export async function handler(event: {
  taskToken: string;
  toolName: string;
  toolInput: Record<string, unknown>;
  sessionId: string;
}) {
  // Step 1: store token durably BEFORE starting work
  await dynamo.send(new PutItemCommand({
    TableName: process.env.PENDING_TOKENS_TABLE,
    Item: {
      sessionId: { S: event.sessionId },
      taskToken: { S: event.taskToken },
      toolName: { S: event.toolName },
      createdAt: { S: new Date().toISOString() },
      ttl: { N: String(Math.floor(Date.now() / 1000) + 3600) },  // 1h TTL
    },
    ConditionExpression: "attribute_not_exists(sessionId)",  // idempotency guard
  }));

  // Step 2: dispatch async work (SQS, EventBridge, third-party webhook, etc.)
  // The actual result will come back via webhook → call SendTaskSuccess
  await dispatchWork(event.toolName, event.toolInput, event.sessionId);

  // Lambda returns here; Step Functions execution remains paused
  // (do NOT call SendTaskSuccess here — that defeats the async pattern)
}

The separate webhook handler (or SQS consumer) calls SendTaskSuccess when the result is ready:

// Webhook receiver / SQS consumer
async function handleResult(sessionId: string, result: unknown): Promise<void> {
  // Retrieve the stored token
  const record = await getTokenBySessionId(sessionId);
  if (!record) {
    console.warn(`No pending token for session ${sessionId} — may have timed out`);
    return;
  }

  try {
    await sfn.send(new SendTaskSuccessCommand({
      taskToken: record.taskToken,
      output: JSON.stringify({ result }),
    }));
    await deleteToken(sessionId);
  } catch (err: any) {
    if (err.name === "TaskTimedOut" || err.name === "InvalidToken") {
      // Execution already timed out or was aborted — clean up and continue
      await deleteToken(sessionId);
      return;
    }
    throw err;
  }
}

SQS integration — decoupled worker pool

The SQS optimized integration avoids a Lambda intermediary entirely. Step Functions sends a message containing the task token directly to SQS, and a pool of workers picks it up:

{
  "SendToWorkerQueue": {
    "Type": "Task",
    "Resource": "arn:aws:states:::sqs:sendMessage.waitForTaskToken",
    "Parameters": {
      "QueueUrl": "https://sqs.us-east-1.amazonaws.com/ACCOUNT/mcp-tool-workers",
      "MessageBody": {
        "taskToken.$": "$$.Task.Token",
        "toolName.$": "$.toolName",
        "toolInput.$": "$.toolInput",
        "sessionId.$": "$.sessionId"
      },
      "MessageGroupId.$": "$.sessionId"   // FIFO queue: same session = same group
    },
    "HeartbeatSeconds": 120,
    "TimeoutSeconds": 300,
    "End": true
  }
}

The state machine execution role needs sqs:SendMessage on the queue and nothing else. The worker Lambda consuming from SQS calls SendTaskSuccess when done. This is the most operationally simple callback pattern — no Lambda intermediary, no token storage in DynamoDB — because SQS guarantees delivery of the token to exactly one worker.

HeartbeatSeconds — detecting crashed workers

Without HeartbeatSeconds, a worker crash leaves the state machine execution waiting until TimeoutSeconds elapses. With HeartbeatSeconds: 30, the worker must call SendTaskHeartbeat every 30 seconds or the task fails with States.HeartbeatTimeout:

// Worker heartbeat loop — runs while processing
async function processWithHeartbeat(taskToken: string, work: () => Promise<unknown>) {
  let done = false;
  const heartbeatInterval = setInterval(async () => {
    if (done) return;
    try {
      await sfn.send(new SendTaskHeartbeatCommand({ taskToken }));
    } catch (err: any) {
      if (err.name === "TaskTimedOut") {
        clearInterval(heartbeatInterval);
        // Abort in-flight work if possible
      }
    }
  }, 20_000);  // every 20s, well under HeartbeatSeconds: 30

  try {
    const result = await work();
    done = true;
    clearInterval(heartbeatInterval);
    return result;
  } catch (err) {
    done = true;
    clearInterval(heartbeatInterval);
    throw err;
  }
}

Set the heartbeat interval to 60–70% of HeartbeatSeconds to provide a buffer for network latency. A heartbeat interval equal to HeartbeatSeconds may miss the deadline on a slow network call and trigger a false timeout.

Common failures