MCP Server DynamoDB Session Store — versioning, optimistic locking, conditional writes

Session table schema design

A single-table design stores session metadata and tool call history on the same partition key, separated by sort key prefix:

Benefits: a single Query pk=session#abc123 returns both the metadata and the full tool call history in sort-key order. The metadata item is the only mutable item — tool call records are written once and never updated. TTL on both item types causes automatic cleanup at session expiry.

Optimistic locking with version attribute

Optimistic locking prevents two concurrent writes from silently overwriting each other. The session metadata item carries a version number; every update asserts the expected version in a ConditionExpression and increments it:

import {
  DynamoDBDocumentClient,
  GetCommand,
  UpdateCommand,
} from "@aws-sdk/lib-dynamodb";
import {
  ConditionalCheckFailedException,
  DynamoDBClient,
} from "@aws-sdk/client-dynamodb";

const ddb = DynamoDBDocumentClient.from(new DynamoDBClient({}));

interface SessionMetadata {
  pk: string;
  sk: string;
  version: number;
  status: string;
  context: unknown[];
  updatedAt: string;
  ttl: number;
}

// Update session status with optimistic locking
export async function updateSessionStatus(
  sessionId: string,
  newStatus: string,
  maxRetries = 3
): Promise {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    // Read current state
    const result = await ddb.send(
      new GetCommand({
        TableName: "mcp-sessions",
        Key: { pk: `session#${sessionId}`, sk: "metadata" },
        ConsistentRead: true, // always strongly consistent for read-modify-write
      })
    );

    if (!result.Item) throw new Error(`Session ${sessionId} not found`);

    const session = result.Item as SessionMetadata;
    const expectedVersion = session.version;

    try {
      await ddb.send(
        new UpdateCommand({
          TableName: "mcp-sessions",
          Key: { pk: `session#${sessionId}`, sk: "metadata" },
          UpdateExpression: "SET #status = :status, updatedAt = :now, #v = #v + :inc",
          ConditionExpression: "#v = :expected",
          ExpressionAttributeNames: {
            "#status": "status",
            "#v": "version",
          },
          ExpressionAttributeValues: {
            ":status": newStatus,
            ":now": new Date().toISOString(),
            ":inc": 1,
            ":expected": expectedVersion,
          },
        })
      );
      return; // success
    } catch (err) {
      if (err instanceof ConditionalCheckFailedException && attempt < maxRetries) {
        // Another writer incremented the version concurrently — retry with fresh read
        const delay = 50 * Math.pow(2, attempt) + Math.random() * 20;
        await new Promise((r) => setTimeout(r, delay));
        continue;
      }
      throw err;
    }
  }
  throw new Error(`Could not update session ${sessionId} after ${maxRetries} retries`);
}

Atomic context accumulation with list_append

MCP servers accumulate conversation context (messages) as sessions progress. Instead of reading the context list, appending a message locally, and writing the full list back (a read-modify-write that races with concurrent writes), use DynamoDB's list_append function to atomically append to the list without a prior read:

// Append new messages to the context list atomically
export async function appendContextMessages(
  sessionId: string,
  newMessages: unknown[],
  expectedVersion: number
): Promise {
  await ddb.send(
    new UpdateCommand({
      TableName: "mcp-sessions",
      Key: { pk: `session#${sessionId}`, sk: "metadata" },
      UpdateExpression:
        "SET context = list_append(if_not_exists(context, :empty), :msgs), " +
        "updatedAt = :now, " +
        "#v = #v + :inc",
      ConditionExpression: "#v = :expected",
      ExpressionAttributeNames: { "#v": "version" },
      ExpressionAttributeValues: {
        ":msgs": newMessages,
        ":empty": [],          // handles the case where context doesn't exist yet
        ":now": new Date().toISOString(),
        ":inc": 1,
        ":expected": expectedVersion,
      },
    })
  );
}

// Record an immutable tool call result (no version check needed — new item)
export async function recordToolCall(
  sessionId: string,
  toolCallId: string,
  toolName: string,
  input: unknown,
  output: unknown,
  durationMs: number
): Promise {
  const nowIso = new Date().toISOString();
  const ttlSec = Math.floor(Date.now() / 1000) + 86400;

  await ddb.send(
    new PutCommand({
      TableName: "mcp-sessions",
      Item: {
        pk: `session#${sessionId}`,
        sk: `tool#${nowIso}#${toolCallId}`,
        toolCallId,
        toolName,
        input,
        output,
        durationMs,
        recordedAt: nowIso,
        ttl: ttlSec,
      },
      // Idempotent: if this toolCallId was already recorded, skip silently
      ConditionExpression: "attribute_not_exists(pk)",
    })
  );
}

Session state machine transitions

MCP sessions have a lifecycle: initializing → active → closing → closed. Guard state transitions with condition expressions to prevent invalid transitions (e.g., re-opening a closed session):

// Transition session from active to closing (idempotent)
export async function beginSessionClose(sessionId: string): Promise {
  try {
    await ddb.send(
      new UpdateCommand({
        TableName: "mcp-sessions",
        Key: { pk: `session#${sessionId}`, sk: "metadata" },
        UpdateExpression:
          "SET #status = :closing, updatedAt = :now, #v = #v + :inc",
        // Only transition if currently active (not already closing or closed)
        ConditionExpression: "#status = :active AND attribute_exists(pk)",
        ExpressionAttributeNames: {
          "#status": "status",
          "#v": "version",
        },
        ExpressionAttributeValues: {
          ":closing": "closing",
          ":active": "active",
          ":now": new Date().toISOString(),
          ":inc": 1,
        },
      })
    );
  } catch (err) {
    if (err instanceof ConditionalCheckFailedException) {
      // Session is already closing or closed — this is idempotent, not an error
      return;
    }
    throw err;
  }
}

Common failure modes