MCP Server Secrets Manager Lambda Caching — AWS Secrets Extension vs SDK cache, batch GetSecretValue

AWS Secrets Manager Lambda Extension

The Secrets Manager Lambda extension is a Lambda layer that runs as a process alongside your function handler within the Lambda execution environment. It starts before your handler is invoked (as part of the Lambda extension init phase), pre-fetches secrets configured via environment variables, and serves them via a local HTTP API on port 2773. Your function code fetches secrets from http://localhost:2773/secretsmanager/get?secretId=... instead of calling the Secrets Manager API directly.

# Terraform: attach the Secrets Manager Lambda extension layer
# Layer ARN varies by region — find current ARN at:
# https://docs.aws.amazon.com/secretsmanager/latest/userguide/retrieving-secrets_lambda.html

resource "aws_lambda_function" "mcp_server" {
  function_name = "mcp-server-tool-handler"
  runtime       = "nodejs20.x"
  handler       = "index.handler"
  role          = aws_iam_role.mcp_lambda.arn
  filename      = "mcp-server.zip"

  layers = [
    # Secrets Manager extension — us-east-1 ARN (check docs for your region)
    "arn:aws:lambda:us-east-1:177933569100:layer:AWS-Parameters-and-Secrets-Lambda-Extension:11"
  ]

  environment {
    variables = {
      # Extension configuration
      PARAMETERS_SECRETS_EXTENSION_CACHE_ENABLED = "true"
      PARAMETERS_SECRETS_EXTENSION_CACHE_SIZE     = "1000"   # max cached items
      SECRETS_MANAGER_TTL                         = "300"    # seconds; 0 = no TTL
      # AWS_SESSION_TOKEN is auto-populated by Lambda — extension uses it
    }
  }
}

# Lambda IAM role must have secretsmanager:GetSecretValue
resource "aws_iam_role_policy" "mcp_lambda_secrets" {
  role   = aws_iam_role.mcp_lambda.id
  policy = jsonencode({
    Version = "2012-10-17"
    Statement = [{
      Effect   = "Allow"
      Action   = ["secretsmanager:GetSecretValue", "secretsmanager:DescribeSecret"]
      Resource = "arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:mcp/*"
    }]
  })
}

// MCP server handler — fetching secrets via the extension HTTP API
// The extension handles caching; your code always fetches from localhost

const EXTENSION_PORT = 2773;
const SESSION_TOKEN = process.env.AWS_SESSION_TOKEN;

async function getSecretViaExtension(secretId) {
  const url = `http://localhost:${EXTENSION_PORT}/secretsmanager/get?secretId=${encodeURIComponent(secretId)}`;

  const resp = await fetch(url, {
    headers: {
      // Required: extension validates the session token to prevent SSRF
      "X-Aws-Parameters-Secrets-Token": SESSION_TOKEN,
    },
  });

  if (!resp.ok) {
    const body = await resp.text();
    throw new Error(`Secrets extension error ${resp.status}: ${body}`);
  }

  const data = await resp.json();
  return JSON.parse(data.SecretString);
}

// Usage in tool handler
export const handler = async (event) => {
  const creds = await getSecretViaExtension(
    "arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:mcp/prod/db-creds-AbCdEf"
  );
  // creds.username, creds.password — served from extension cache if TTL not expired
  return await handleMCPToolCall(event, creds);
};

SDK-level in-memory cache (without extension)

If you can't use Lambda layers or need more control over the cache lifecycle, an SDK-level in-memory cache at module scope is the alternative. Module-scope variables persist across warm Lambda invocations within the same execution environment. The cache must implement TTL expiry and handle post-rotation credential failures with a retry-and-invalidate pattern.

// Module-scope cache — persists across warm Lambda invocations
import { SecretsManagerClient, GetSecretValueCommand } from "@aws-sdk/client-secrets-manager";

const sm = new SecretsManagerClient({ region: process.env.AWS_REGION });

const cache = new Map(); // secretId → { value, expiresAt }
const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes

async function getCachedSecret(secretId) {
  const now = Date.now();
  const cached = cache.get(secretId);
  if (cached && now < cached.expiresAt) {
    return cached.value;
  }

  const resp = await sm.send(new GetSecretValueCommand({
    SecretId: secretId,
    VersionStage: "AWSCURRENT",
  }));
  const value = JSON.parse(resp.SecretString);

  cache.set(secretId, { value, expiresAt: now + CACHE_TTL_MS });
  return value;
}

function invalidateCachedSecret(secretId) {
  cache.delete(secretId);
}

// Retry-on-auth-failure pattern for post-rotation window
async function withSecretRetry(secretId, operation) {
  let creds = await getCachedSecret(secretId);
  try {
    return await operation(creds);
  } catch (err) {
    if (isAuthenticationError(err)) {
      invalidateCachedSecret(secretId);
      creds = await getCachedSecret(secretId); // fresh fetch
      return await operation(creds); // retry once
    }
    throw err;
  }
}

function isAuthenticationError(err) {
  // Postgres auth failure
  if (err.code === "28P01") return true;
  // MySQL auth failure
  if (err.code === "ER_ACCESS_DENIED_ERROR") return true;
  // HTTP 401/403 from backend APIs
  if (err.status === 401 || err.status === 403) return true;
  return false;
}

// Batch load multiple secrets at function cold start
async function preloadSecrets(secretIds) {
  await Promise.all(secretIds.map(id => getCachedSecret(id)));
}

// Module init — preload during cold start (outside handler)
await preloadSecrets([
  "arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:mcp/prod/db-creds-AbCdEf",
  "arn:aws:secretsmanager:us-east-1:ACCOUNT_ID:secret:mcp/prod/slack-token-XyZwQr",
]);

Extension vs SDK cache: comparison

Failure modes reference