AWS Lambda Powertools Idempotency for MCP Servers

DynamoDB table setup and persistence layer

Powertools Idempotency uses DynamoDB as the persistence store. The table needs a string partition key (default: id) and a TTL attribute (default: expiration). No sort key is needed.

# CloudFormation / SAM
Resources:
  IdempotencyTable:
    Type: AWS::DynamoDB::Table
    Properties:
      TableName: mcp-idempotency
      BillingMode: PAY_PER_REQUEST
      AttributeDefinitions:
        - AttributeName: id
          AttributeType: S
      KeySchema:
        - AttributeName: id
          KeyType: HASH
      TimeToLiveSpecification:
        AttributeName: expiration
        Enabled: true

from aws_lambda_powertools.utilities.idempotency import (
    DynamoDBPersistenceLayer,
    IdempotencyConfig,
    idempotent,
)
from aws_lambda_powertools.utilities.typing import LambdaContext

persistence_store = DynamoDBPersistenceLayer(table_name="mcp-idempotency")

config = IdempotencyConfig(
    event_key_jmespath="body.callId",          # extract stable key from payload
    expires_after_seconds=3600,                 # cache successful responses for 1 hour
    in_progress_expiration_seconds=30,          # release INPROGRESS lock after 30s
    raise_on_no_idempotency_key=True,           # fail if key extraction returns None
    payload_validation_jmespath="body.userId",  # validate same user on retry
)

@idempotent(config=config, persistence_store=persistence_store)
def handler(event: dict, context: LambdaContext) -> dict:
    tool_name = event["body"]["toolName"]
    tool_input = event["body"]["input"]
    result = execute_mcp_tool(tool_name, tool_input)
    return {"statusCode": 200, "body": json.dumps(result)}

Idempotency key selection

The idempotency key is a hash of the value extracted by event_key_jmespath. The key must be stable across retries of the same logical request — it must not change between the original call and any retry. Common patterns:

With raise_on_no_idempotency_key=True, if the JMESPath expression returns null (e.g., the client didn't include a callId), Powertools raises IdempotencyKeyError and the handler does not execute. This is the safe default: it forces clients to send a stable key rather than accidentally processing every request as unique.

Status transitions and concurrent requests

Powertools Idempotency uses DynamoDB conditional writes to manage concurrent requests with the same key safely. The status field transitions:

The transition from no-record → INPROGRESS uses a ConditionalCheckFailedException guard: the write only succeeds if no record with that key exists, or the existing record is EXPIRED. This prevents two concurrent Lambda invocations with the same key from both proceeding. The second invocation receives IdempotencyAlreadyInProgressError and should retry after a short delay.

In-progress expiry — handling Lambda kills

in_progress_expiration_seconds is the most important safety parameter. Without it, any Lambda invocation that is killed before completion (timeout, OOM, infrastructure failure, forced stop) leaves a record in INPROGRESS state. Subsequent retries see the INPROGRESS record and raise IdempotencyAlreadyInProgressError — the request is permanently blocked until the TTL expires hours later.

config = IdempotencyConfig(
    event_key_jmespath="body.callId",
    expires_after_seconds=3600,
    # If Lambda is killed after 30s without completing, the INPROGRESS
    # record is considered stale and the next retry re-executes the handler
    in_progress_expiration_seconds=30,
)

Set in_progress_expiration_seconds to your Lambda timeout + a 5-second buffer. For a 25-second timeout function, use 30 seconds. This ensures that if the Lambda was killed after its maximum possible runtime, the next retry can always proceed.

idempotent_function — for internal operations

The @idempotent decorator protects the entire Lambda handler. For finer-grained control — making only specific internal operations idempotent while allowing the handler to run — use @idempotent_function:

from aws_lambda_powertools.utilities.idempotency import idempotent_function

@idempotent_function(
    data_keyword_argument="tool_call",
    config=config,
    persistence_store=persistence_store,
)
def execute_mcp_tool(tool_call: dict) -> dict:
    # This function is idempotent — only the tool execution is deduplicated
    # The handler can run multiple tools; each is independently idempotent
    tool_name = tool_call["name"]
    return tool_implementations[tool_name](tool_call["input"])

def handler(event: dict, context: LambdaContext) -> dict:
    results = []
    for tool_call in event["toolCalls"]:
        result = execute_mcp_tool(tool_call=tool_call)
        results.append(result)
    return {"results": results}

The data_keyword_argument specifies which function argument to hash for the idempotency key. The function must be called with that argument as a keyword argument.

Common failures