AWS AppConfig Lambda Extension for MCP Servers

What the Lambda Extension does

A Lambda Extension runs as a sibling process alongside your function handler within the same Lambda execution environment. The AppConfig extension starts when the execution environment initializes, opens a configuration session with AppConfig, and begins polling on a configurable interval. It stores the latest config document in memory and serves it over an HTTP server bound to localhost:2772.

Your handler code calls GET http://localhost:2772/... — this is a local loopback request that returns in under 1ms on a warm container, because the extension already has the cached document in memory. Compare this with a direct SDK call to AppConfig, which requires a TLS handshake and a round-trip to the AWS AppConfig regional endpoint — typically 25–40ms per call.

The extension also handles token rotation automatically. The AppConfig GetLatestConfiguration API returns a new token on every call, and if you fail to use the latest token the session becomes invalid. Managing this in application code requires care — the extension removes that risk entirely.

Adding the extension ARN

The AppConfig Lambda Extension is published as a public Lambda layer. The ARN is region-specific and versioned. Always pin to a specific version in production rather than using :latest to avoid unexpected updates.

For ARM64 (Graviton2) functions, replace AWS-AppConfig-Extension with AWS-AppConfig-Extension-Arm64 in the ARN — the account IDs and version numbers differ per region, so check the AWS documentation for the current ARM64 ARN for your region.

CDK v2 example using addLayers():

import * as cdk from 'aws-cdk-lib';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import * as iam from 'aws-cdk-lib/aws-iam';

const mcpHandler = new lambda.Function(this, 'McpServerHandler', {
  runtime: lambda.Runtime.NODEJS_20_X,
  code: lambda.Code.fromAsset('dist'),
  handler: 'index.handler',
  timeout: cdk.Duration.seconds(30),
  memorySize: 512,
  environment: {
    AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS: '30',
    AWS_APPCONFIG_EXTENSION_HTTP_PORT: '2772',
    APPCONFIG_APP: 'mcp-server',
    APPCONFIG_ENV: 'production',
    APPCONFIG_PROFILE: 'mcp-server-config',
  },
  layers: [
    lambda.LayerVersion.fromLayerVersionArn(
      this,
      'AppConfigExtension',
      // Pin to an exact version; do not use cdk.Fn.select tricks with "latest"
      'arn:aws:lambda:us-east-1:027255383542:layer:AWS-AppConfig-Extension:128',
    ),
  ],
});

// Grant the execution role permissions to read AppConfig
mcpHandler.addToRolePolicy(new iam.PolicyStatement({
  actions: [
    'appconfig:StartConfigurationSession',
    'appconfig:GetLatestConfiguration',
  ],
  resources: ['*'],
}));

In a SAM template, add the layer under the Layers property of your AWS::Serverless::Function resource. The same ARN applies; SAM does not require special syntax beyond listing it in the array.

Fetching config via the extension

The HTTP endpoint format is: http://localhost:2772/applications/{ApplicationIdentifier}/environments/{EnvironmentIdentifier}/configurations/{ConfigurationProfileIdentifier}. Identifiers can be the resource name (e.g., mcp-server) or the numeric ID returned by AppConfig APIs.

interface McpServerConfig {
  toolEnabled: Record<string, boolean>;
  rateLimits: Record<string, { requestsPerMinute: number; burstSize?: number }>;
  upstreamTimeoutMs: Record<string, number>;
  allowedCallers: string[];
  logLevel: string;
  maintenanceMode: boolean;
}

// Default config used before the extension populates its cache on cold start
const DEFAULT_CONFIG: McpServerConfig = {
  toolEnabled: {},
  rateLimits: {},
  upstreamTimeoutMs: {},
  allowedCallers: [],
  logLevel: 'info',
  maintenanceMode: false,
};

const APPCONFIG_PORT = process.env.AWS_APPCONFIG_EXTENSION_HTTP_PORT ?? '2772';
const APPCONFIG_APP = process.env.APPCONFIG_APP!;
const APPCONFIG_ENV = process.env.APPCONFIG_ENV!;
const APPCONFIG_PROFILE = process.env.APPCONFIG_PROFILE!;
const CONFIG_URL = `http://localhost:${APPCONFIG_PORT}/applications/${APPCONFIG_APP}/environments/${APPCONFIG_ENV}/configurations/${APPCONFIG_PROFILE}`;

let cachedConfig: McpServerConfig = DEFAULT_CONFIG;
let cachePopulated = false;

export async function refreshConfig(): Promise<McpServerConfig> {
  const controller = new AbortController();
  // 408 timeout means the extension hasn't completed its first poll yet —
  // this is normal on the very first invocation after a cold start.
  const timeoutId = setTimeout(() => controller.abort(), 500);

  try {
    const response = await fetch(CONFIG_URL, { signal: controller.signal });
    clearTimeout(timeoutId);

    if (!response.ok) {
      // 404 = profile not found; surface this immediately so the error is obvious
      throw new Error(`AppConfig extension returned HTTP ${response.status}`);
    }

    const text = await response.text();
    if (text.length > 0) {
      cachedConfig = JSON.parse(text) as McpServerConfig;
      cachePopulated = true;
    }
    return cachedConfig;
  } catch (err: unknown) {
    clearTimeout(timeoutId);
    if (err instanceof Error && err.name === 'AbortError') {
      // Extension hasn't populated yet; return the default on the first call,
      // or the last good config on subsequent calls
      console.warn('AppConfig extension not ready; using cached/default config');
      return cachedConfig;
    }
    throw err;
  }
}

// Call once at module load to prime the cache asynchronously.
// On warm invocations this returns immediately from the extension's memory.
const primePromise = refreshConfig();

export async function getMcpServerConfig(): Promise<McpServerConfig> {
  await primePromise;
  return cachedConfig;
}

The AWS_APPCONFIG_EXTENSION_POLL_INTERVAL_SECONDS environment variable controls how frequently the extension polls AppConfig. Minimum is 15 seconds. Values lower than 15 are clamped. For kill-switch use cases (disabling a broken tool fast), 15–30 seconds is appropriate. For lower-urgency configs like log level, 60–120 seconds reduces AppConfig API call volume and cost.

Optimizing for warm vs. cold starts

The extension polls AppConfig asynchronously during a cold start. This means your handler's first invocation after a cold start may read a stale or default config — the extension initializes in parallel with your handler code and may not have completed its first poll before your handler calls localhost:2772. This is intentional: it keeps cold start latency low.

If your MCP server absolutely must read the latest config before handling any request (for example, if the config contains allowed-caller lists that are a security boundary), set AWS_APPCONFIG_EXTENSION_POLL_WAIT_COMPLETE=true. This forces the extension to complete its first poll synchronously during initialization, before the handler invocation is allowed to start. The tradeoff is an additional ~30–80ms added to cold start time.

For warm containers, the extension is already running and has a recent config cached. The HTTP GET to localhost:2772 completes in under 1ms — this is faster than any in-process cache lookup that involves JSON parsing, because the extension returns the raw bytes and your code only parses them when the document has actually changed. Use an ETag or content-hash comparison in your refreshConfig logic to avoid re-parsing an unchanged document on every invocation.

IAM permissions

The extension uses the Lambda function's execution role to authenticate with AppConfig. You need exactly two IAM actions. These cannot be scoped to a specific AppConfig Application ARN in all configurations — if you use resource names (rather than numeric IDs) in the URL, the IAM resource must be * unless you construct the exact ARN.

import * as iam from 'aws-cdk-lib/aws-iam';

// Minimum policy for the Lambda execution role
const appConfigPolicy = new iam.PolicyStatement({
  sid: 'AppConfigReadConfig',
  effect: iam.Effect.ALLOW,
  actions: [
    'appconfig:StartConfigurationSession',
    'appconfig:GetLatestConfiguration',
  ],
  // Scope to a specific application/environment/profile if you know the ARNs:
  // resources: [
  //   `arn:aws:appconfig:us-east-1:${this.account}:application/${appId}`,
  //   `arn:aws:appconfig:us-east-1:${this.account}:application/${appId}/environment/${envId}`,
  //   `arn:aws:appconfig:us-east-1:${this.account}:application/${appId}/environment/${envId}/configuration/${profileId}`,
  // ],
  resources: ['*'],
});

mcpHandler.addToRolePolicy(appConfigPolicy);

Note: appconfig:GetConfiguration (the old API) and appconfig:GetLatestConfiguration are different IAM actions. The extension uses the newer AppConfigData API which requires StartConfigurationSession + GetLatestConfiguration. If you grant only appconfig:GetConfiguration you will get AccessDeniedException errors in the extension logs.

To verify the IAM setup before deploying, run the AWS CLI IAM policy simulator or check the extension's CloudWatch log group (/aws/lambda/{functionName}/AppConfig) for AccessDeniedException messages on the first invocation.

AliveMCP uptime monitoring + AppConfig Lambda Extension: complementary layers

The AppConfig Lambda Extension manages config delivery within your Lambda execution environment — it ensures your function has fresh configuration without the overhead of direct AppConfig SDK calls. AliveMCP works at the opposite end of the stack: it probes your MCP server from outside AWS every 60 seconds by sending a real JSON-RPC tools/list handshake and validating the response structure.

These two systems catch different failure modes. When a bad config deployment reaches your Lambda functions and causes them to crash on startup or reject requests, the extension cannot detect that — it only delivers configuration, it does not validate whether your application successfully consumed it. AliveMCP's external probe will detect within 60 seconds that tools/list is no longer returning a valid response. You can then immediately trigger a manual AppConfig rollback by calling StopDeployment or via the console — long before AppConfig's built-in bake timer would expire. The extension's asynchronous poll model means some Lambda containers may still be running the old (working) config while new ones pick up the bad config; AliveMCP sees the aggregate failure rate from a single probe point and alerts you without needing to instrument individual containers.

Failure modes