MCP Server DynamoDB Transactions — idempotent multi-step tool calls, TransactWriteItems

Basic TransactWriteItems pattern for MCP tool calls

An MCP tool call that creates a resource and logs the operation atomically — both writes succeed or both are rolled back:

import {
  DynamoDBClient,
  TransactWriteItemsCommand,
  TransactWriteItemsCommandInput,
} from "@aws-sdk/client-dynamodb";
import { marshall } from "@aws-sdk/util-dynamodb";

const ddb = new DynamoDBClient({});

export async function createResourceWithAudit(
  toolCallId: string,    // MCP tool call ID — use as idempotency key
  sessionId: string,
  resourceId: string,
  resourceData: Record
): Promise {
  const nowIso = new Date().toISOString();
  const ttlSec = Math.floor(Date.now() / 1000) + 86400; // 24h

  const input: TransactWriteItemsCommandInput = {
    // ClientRequestToken makes this transaction idempotent for 10 minutes.
    // Use the MCP tool call ID — if the caller retries the same tool call,
    // the same token ensures the transaction doesn't double-execute.
    ClientRequestToken: toolCallId,

    TransactItems: [
      // 1. Assert the session is alive (ConditionCheck — read-only assertion)
      {
        ConditionCheck: {
          TableName: "mcp-sessions",
          Key: marshall({ pk: `session#${sessionId}`, sk: "metadata" }),
          ConditionExpression: "attribute_exists(pk) AND #ttl > :now",
          ExpressionAttributeNames: { "#ttl": "ttl" },
          ExpressionAttributeValues: marshall({ ":now": Math.floor(Date.now() / 1000) }),
        },
      },
      // 2. Create the resource item
      {
        Put: {
          TableName: "mcp-resources",
          Item: marshall({
            pk: `resource#${resourceId}`,
            sk: "v1",
            resourceId,
            sessionId,
            data: resourceData,
            status: "active",
            createdAt: nowIso,
            ttl: ttlSec,
          }),
          // Prevent accidental overwrites of existing resources
          ConditionExpression: "attribute_not_exists(pk)",
        },
      },
      // 3. Append an audit log entry
      {
        Put: {
          TableName: "mcp-sessions",
          Item: marshall({
            pk: `session#${sessionId}`,
            sk: `audit#${nowIso}#${toolCallId}`,
            toolCallId,
            action: "create_resource",
            resourceId,
            recordedAt: nowIso,
            ttl: ttlSec,
          }),
        },
      },
    ],
  };

  await ddb.send(new TransactWriteItemsCommand(input));
}

Retry strategy for TransactionConflictException

TransactionConflictException means two transactions tried to modify the same item at the same time. DynamoDB uses optimistic concurrency — the loser is rejected and must retry. This is the only error from transactions that should be retried. All other errors (TransactionCanceledException, ValidationException) indicate either a business logic failure or a programming error and should not be retried.

import { TransactionConflictException } from "@aws-sdk/client-dynamodb";

const MAX_RETRIES = 3;
const BASE_DELAY_MS = 50;

export async function executeToolCallTransaction(
  toolCallId: string,
  buildTransaction: () => TransactWriteItemsCommandInput
): Promise {
  let attempt = 0;

  while (true) {
    try {
      await ddb.send(new TransactWriteItemsCommand(buildTransaction()));
      return; // success
    } catch (err) {
      if (err instanceof TransactionConflictException && attempt < MAX_RETRIES) {
        // Exponential backoff with jitter for concurrent transaction conflicts
        const delay = BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * 25;
        await new Promise((resolve) => setTimeout(resolve, delay));
        attempt++;
        continue;
      }
      // Re-throw all other errors — TransactionCanceledException is a business
      // logic failure (e.g., ConditionCheck failed) and must NOT be retried.
      throw err;
    }
  }
}

// Parse TransactionCanceledException to surface which condition failed
import { TransactionCanceledException } from "@aws-sdk/client-dynamodb";

function handleTransactionCanceled(err: unknown): string {
  if (!(err instanceof TransactionCanceledException)) throw err;
  const reasons = err.CancellationReasons ?? [];
  for (let i = 0; i < reasons.length; i++) {
    const code = reasons[i].Code;
    if (code === "ConditionalCheckFailed") {
      // Map index to the relevant TransactItem for a descriptive error
      return `Precondition failed for item ${i}: ${reasons[i].Message}`;
    }
    if (code === "ItemSizeLimitExceeded") {
      return `Item ${i} exceeds 400 KB DynamoDB item size limit`;
    }
  }
  return "Transaction canceled for unknown reason";
}

25-item limit and capacity cost

DynamoDB transactions have two constraints that affect MCP server design:

Idempotency token lifetime and semantics

The ClientRequestToken makes a TransactWriteItems call idempotent for exactly 10 minutes. If you retry with the same token within that window, DynamoDB returns the original response without re-executing the transaction. After 10 minutes, the token is forgotten and the same token would execute a new transaction.

For MCP tool calls, the tool call ID (which the MCP framework provides) is the ideal idempotency token. If the MCP client or framework retries a timed-out tool call within 10 minutes, the same token prevents double execution. After 10 minutes, a re-submitted tool call with the same ID would create a duplicate — guard against this with a ConditionExpression: "attribute_not_exists(toolCallId)" on the primary item write.

Token requirements: must be 1–36 characters (UUID fits), only alphanumerics and hyphens.

Common failure modes