MCP Server DynamoDB — single-table design and query patterns for MCP tools on AWS

AWS SDK v3 setup and single-table design

The AWS SDK v3 splits DynamoDB into two clients: DynamoDBClient (low-level, returns attribute maps with type descriptors like { S: 'value' }) and DynamoDBDocumentClient (high-level, marshals to/from plain JavaScript objects). Always use the Document client in MCP server code.

import {
  DynamoDBClient,
  DescribeTableCommand
} from '@aws-sdk/client-dynamodb';
import {
  DynamoDBDocumentClient,
  GetCommand,
  PutCommand,
  UpdateCommand,
  DeleteCommand,
  QueryCommand,
  TransactWriteCommand
} from '@aws-sdk/lib-dynamodb';

const TABLE_NAME = process.env.DYNAMODB_TABLE_NAME!;
const AWS_REGION = process.env.AWS_REGION ?? 'us-east-1';

// DynamoDBClient uses the credential chain automatically:
// 1. Environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY)
// 2. ~/.aws/credentials file (local dev)
// 3. IAM role attached to Lambda/ECS/EC2 (production — preferred, no secrets needed)
const baseClient = new DynamoDBClient({
  region: AWS_REGION,
  maxAttempts: 3  // SDK v3 retries throttling with exponential backoff
});

export const ddb = DynamoDBDocumentClient.from(baseClient, {
  marshallOptions: {
    // Omit undefined values from DynamoDB writes (avoids storing 'null' for optional fields)
    removeUndefinedValues: true,
    convertEmptyValues: false
  }
});

// Single-table key design
// PK examples:  CUSTOMER#cust-123     ORDER#ord-456     PRODUCT#prod-789
// SK examples:  METADATA              ORDER#ord-456     PRODUCT#prod-789
//               ORDER#ord-456         ITEM#item-001
//
// This lets you query all orders for a customer:
//   KeyConditionExpression: 'pk = :pk AND begins_with(sk, :sk_prefix)'
//   ExpressionAttributeValues: { ':pk': 'CUSTOMER#cust-123', ':sk_prefix': 'ORDER#' }

export function pk(entityType: string, id: string): string {
  return `${entityType.toUpperCase()}#${id}`;
}
export function sk(entityType: string, id: string): string {
  return `${entityType.toUpperCase()}#${id}`;
}

get_item tool

GetCommand returns undefined when the item doesn't exist — not an error. Handle this explicitly in the tool handler. Use ProjectionExpression to return only the fields the caller needs, reducing read capacity unit (RCU) consumption for large items.

import { z } from 'zod';
import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';

server.tool(
  'get_customer',
  {
    customer_id: z.string().min(1),
    fields: z.array(z.string()).optional()
  },
  async ({ customer_id, fields }) => {
    const projectionParts = fields?.map((f, i) => `#attr${i}`);
    const expressionAttributeNames = fields
      ? Object.fromEntries(fields.map((f, i) => [`#attr${i}`, f]))
      : undefined;

    const { Item } = await ddb.send(new GetCommand({
      TableName: TABLE_NAME,
      Key: {
        pk: pk('CUSTOMER', customer_id),
        sk: 'METADATA'
      },
      ProjectionExpression: projectionParts?.join(', '),
      ExpressionAttributeNames: expressionAttributeNames
    }));

    if (!Item) {
      throw new McpError(
        ErrorCode.InvalidParams,
        `Customer ${customer_id} not found`
      );
    }

    // Strip internal key fields before returning to caller
    const { pk: _pk, sk: _sk, ...customerData } = Item;
    return {
      content: [{ type: 'text', text: JSON.stringify(customerData, null, 2) }]
    };
  }
);

query_items tool

DynamoDB Query is the primary read pattern for most access patterns. It requires the partition key (PK) and optionally a sort key condition. Use FilterExpression for non-key attribute filtering — but note that filters are applied after the query reads items from the partition, so they don't reduce RCU consumption. Design your key patterns so filters are rarely needed for high-volume queries.

server.tool(
  'list_customer_orders',
  {
    customer_id: z.string().min(1),
    status: z.enum(['pending', 'processing', 'shipped', 'delivered', 'cancelled']).optional(),
    limit: z.number().int().min(1).max(100).default(25),
    start_key: z.string().optional()  // base64-encoded LastEvaluatedKey for pagination
  },
  async ({ customer_id, status, limit, start_key }) => {
    const params: import('@aws-sdk/lib-dynamodb').QueryCommandInput = {
      TableName: TABLE_NAME,
      KeyConditionExpression: 'pk = :pk AND begins_with(sk, :sk_prefix)',
      ExpressionAttributeValues: {
        ':pk': pk('CUSTOMER', customer_id),
        ':sk_prefix': 'ORDER#'
      },
      Limit: limit,
      ScanIndexForward: false  // descending by SK (most recent orders first)
    };

    // Filter by status (non-key attribute)
    if (status) {
      params.FilterExpression = '#status = :status';
      params.ExpressionAttributeNames = { '#status': 'status' };
      (params.ExpressionAttributeValues as Record<string, unknown>)[':status'] = status;
    }

    // Pagination: decode the continuation key
    if (start_key) {
      params.ExclusiveStartKey = JSON.parse(
        Buffer.from(start_key, 'base64').toString('utf-8')
      );
    }

    const { Items = [], LastEvaluatedKey } = await ddb.send(new QueryCommand(params));

    // Encode pagination key for next call
    const nextKey = LastEvaluatedKey
      ? Buffer.from(JSON.stringify(LastEvaluatedKey)).toString('base64')
      : null;

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          items: Items.map(({ pk: _pk, sk: _sk, ...item }) => item),
          next_start_key: nextKey,
          count: Items.length
        }, null, 2)
      }]
    };
  }
);

put_item and update_item tools

PutCommand overwrites the entire item. UpdateCommand modifies specific attributes, preserving others. Use ConditionExpression for optimistic locking or to prevent overwrites on new items. Always handle ConditionalCheckFailedException as a 4xx business logic error, not a 5xx server error.

import { ConditionalCheckFailedException } from '@aws-sdk/client-dynamodb';

// update_order_status — safe partial update with condition check
server.tool(
  'update_order_status',
  {
    order_id: z.string().min(1),
    new_status: z.enum(['processing', 'shipped', 'delivered', 'cancelled']),
    expected_status: z.enum(['pending', 'processing', 'shipped']).optional(),
    version: z.number().int().optional()  // optimistic locking
  },
  async ({ order_id, new_status, expected_status, version }) => {
    const updateParams: import('@aws-sdk/lib-dynamodb').UpdateCommandInput = {
      TableName: TABLE_NAME,
      Key: {
        pk: pk('ORDER', order_id),
        sk: 'METADATA'
      },
      UpdateExpression: 'SET #status = :new_status, updatedAt = :now, #version = #version + :inc',
      ExpressionAttributeNames: {
        '#status': 'status',    // 'status' is a DynamoDB reserved word
        '#version': 'version'
      },
      ExpressionAttributeValues: {
        ':new_status': new_status,
        ':now': new Date().toISOString(),
        ':inc': 1
      },
      ReturnValues: 'ALL_NEW'
    };

    // Add optimistic locking condition if caller provides expected state
    if (expected_status || version !== undefined) {
      const conditions: string[] = [];
      if (expected_status) {
        conditions.push('#status = :expected_status');
        (updateParams.ExpressionAttributeValues as Record<string, unknown>)[':expected_status'] = expected_status;
      }
      if (version !== undefined) {
        conditions.push('#version = :expected_version');
        (updateParams.ExpressionAttributeValues as Record<string, unknown>)[':expected_version'] = version;
      }
      updateParams.ConditionExpression = conditions.join(' AND ');
    }

    try {
      const { Attributes } = await ddb.send(new UpdateCommand(updateParams));
      return {
        content: [{ type: 'text', text: JSON.stringify(Attributes, null, 2) }]
      };
    } catch (e) {
      if (e instanceof ConditionalCheckFailedException) {
        // This is a 4xx conflict — not a server error
        throw new McpError(
          ErrorCode.InvalidParams,
          `Condition check failed: order may have been updated concurrently or status mismatch`
        );
      }
      throw e;  // Re-throw unexpected errors (throttling, etc.)
    }
  }
);

GSI queries

Global Secondary Indexes (GSIs) enable querying on non-key attributes. Common patterns for MCP server data: query orders by status, find customers by email, list products by category. GSI writes are eventually consistent — a write to the base table propagates to GSIs within milliseconds but not atomically.

// Assume GSI: GSI1PK = 'STATUS#pending', GSI1SK = createdAt (ISO string)
// This lets you query all pending orders efficiently

server.tool(
  'list_orders_by_status',
  {
    status: z.enum(['pending', 'processing', 'shipped', 'delivered', 'cancelled']),
    since: z.string().datetime().optional(),
    limit: z.number().int().min(1).max(100).default(25)
  },
  async ({ status, since, limit }) => {
    const params: import('@aws-sdk/lib-dynamodb').QueryCommandInput = {
      TableName: TABLE_NAME,
      IndexName: 'GSI1',  // GSI index name
      KeyConditionExpression: since
        ? 'GSI1PK = :gsi_pk AND GSI1SK >= :since'
        : 'GSI1PK = :gsi_pk',
      ExpressionAttributeValues: {
        ':gsi_pk': `STATUS#${status}`,
        ...(since ? { ':since': since } : {})
      },
      Limit: limit,
      ScanIndexForward: false  // most recent first
    };

    const { Items = [], LastEvaluatedKey } = await ddb.send(new QueryCommand(params));

    return {
      content: [{
        type: 'text',
        text: JSON.stringify({
          items: Items,
          count: Items.length,
          // Note for caller: GSI data may be seconds behind the base table
          consistency_note: 'GSI reads are eventually consistent — data may be up to a few seconds stale'
        }, null, 2)
      }]
    };
  }
);

Health endpoint: /health/dynamodb

The DynamoDB health endpoint should verify that the table is active and your IAM permissions are intact. DescribeTableCommand is a lightweight control-plane call that returns table status, item count, and provisioning mode.

import express from 'express';
import { DescribeTableCommand } from '@aws-sdk/client-dynamodb';

const app = express();

app.get('/health/dynamodb', async (_req, res) => {
  const start = Date.now();
  try {
    const { Table } = await ddb.send(
      // Note: DescribeTableCommand goes to base DynamoDBClient, not DocumentClient
      // but our ddb DocumentClient wraps it — use the underlying client
      new DescribeTableCommand({ TableName: TABLE_NAME })
    );

    const tableStatus = Table?.TableStatus;
    const isActive = tableStatus === 'ACTIVE';
    const billingMode = Table?.BillingModeSummary?.BillingMode ?? 'PROVISIONED';

    res.status(isActive ? 200 : 503).json({
      status: isActive ? 'ok' : 'degraded',
      table: TABLE_NAME,
      table_status: tableStatus,
      item_count: Table?.ItemCount,
      size_bytes: Table?.TableSizeBytes,
      billing_mode: billingMode,
      gsi_count: Table?.GlobalSecondaryIndexes?.length ?? 0,
      elapsed_ms: Date.now() - start
    });
  } catch (err) {
    res.status(503).json({
      status: 'error',
      error: (err as Error).message,
      elapsed_ms: Date.now() - start
    });
  }
});

Silent failure modes and AliveMCP monitoring

DynamoDB throttling is insidious: the AWS SDK retries automatically, so individual tool calls eventually either succeed (after 3 retries, adding seconds of latency) or fail with the final throttle error. Neither outcome produces an HTTP 503 from your MCP server. Set up AliveMCP monitoring on /health/dynamodb and also track tool call latency — a spike above 2s on normally sub-10ms operations is a reliable indicator of active throttling even when no errors are being returned.

Frequently asked questions

Further reading

• MCP Server AWS — deploying and securing MCP servers on AWS infrastructure
• MCP Server AWS Bedrock — integrating Bedrock models with MCP tool use
• MCP Server Idempotency — safe retries for DynamoDB write tools
• MCP Server Retry Logic — exponential backoff for throttled operations
• MCP Server Error Handling — mapping AWS exceptions to McpError codes