MCP Server API Gateway HTTP API — JWT authorizer, payload format v2, throttling, and CORS

Payload format v2.0: field mapping for Lambda handlers

The most common migration mistake when moving from REST API to HTTP API is using REST API field names on the v2.0 event. The shapes are different at the top level. Lambda handlers must be updated to use the new field paths — or explicitly set payloadFormatVersion: "1.0" on the integration to keep the old shape (with a small latency overhead).

// Payload format v2.0 (HTTP API default) — event shape
const v2Event = {
  version: "2.0",
  routeKey: "POST /tools/invoke",
  rawPath: "/tools/invoke",
  rawQueryString: "sessionId=abc&debug=true",
  headers: {
    "content-type": "application/json",
    "authorization": "Bearer eyJ..."
  },
  queryStringParameters: {  // always present (empty object if none)
    sessionId: "abc",
    debug: "true"
  },
  pathParameters: { toolName: "search" },  // null if no path params
  body: '{"input":"query"}',  // always a string (not parsed)
  isBase64Encoded: false,
  requestContext: {
    accountId: "123456789",
    apiId: "abc123",
    domainName: "abc123.execute-api.us-east-1.amazonaws.com",
    http: {
      method: "POST",       // v2: here, not event.httpMethod
      path: "/tools/invoke", // v2: here, not event.path
      protocol: "HTTP/1.1",
      sourceIp: "1.2.3.4",
      userAgent: "..."
    },
    requestId: "...",
    routeKey: "POST /tools/invoke",
    stage: "prod",
    time: "18/Sep/2026:10:00:00 +0000",
    timeEpoch: 1726653600000
  },
  // JWT claims available here if a JWT authorizer is attached
  requestContext: {
    authorizer: {
      jwt: {
        claims: { sub: "user123", email: "user@example.com" },
        scopes: ["openid", "tools:invoke"]
      }
    }
  }
};

// v2.0-compatible Lambda handler
export const handler = async (event) => {
  // v2: use event.requestContext.http.method (NOT event.httpMethod)
  const method = event.requestContext.http.method;
  const path = event.rawPath;
  const body = event.body ? JSON.parse(event.body) : {};

  // JWT claims from native authorizer (no Lambda code to verify token)
  const userId = event.requestContext.authorizer?.jwt?.claims?.sub;

  return {
    statusCode: 200,
    // v2 response: headers is an object (same as v1); body must be a string
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ status: 'ok', userId })
  };
};

Native JWT authorizer: OIDC configuration

The JWT authorizer validates the token's signature, expiry, issuer, and audience without a Lambda. API Gateway fetches the OIDC discovery document from {issuer}/.well-known/openid-configuration and caches the JWKS for 2 hours. The authorizer checks: exp not in the past, iss matches the configured issuer, and aud (or client_id for some providers) contains the configured audience. Token claims are forwarded to the Lambda in event.requestContext.authorizer.jwt.claims.

// AWS CDK — HTTP API with JWT authorizer (Cognito example)
import { HttpApi, HttpMethod, HttpJwtAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2';
import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';

const userPool = new cognito.UserPool(this, 'Users');
const userPoolClient = userPool.addClient('ApiClient');

const jwtAuthorizer = new HttpJwtAuthorizer('JwtAuth', userPool.userPoolProviderUrl, {
  jwtAudience: [userPoolClient.userPoolClientId]
});

const httpApi = new HttpApi(this, 'ToolsApi', {
  corsPreflight: {
    allowHeaders: ['Authorization', 'Content-Type'],
    allowMethods: [CorsHttpMethod.POST, CorsHttpMethod.GET, CorsHttpMethod.OPTIONS],
    allowOrigins: ['https://app.example.com'],
    maxAge: Duration.hours(1)
  }
});

httpApi.addRoutes({
  path: '/tools/invoke',
  methods: [HttpMethod.POST],
  integration: new HttpLambdaIntegration('InvokeTool', invokeToolFn),
  authorizer: jwtAuthorizer
});

// For non-CDK: Terraform / CloudFormation JwtConfiguration on AWS::ApiGatewayV2::Authorizer
// Properties:
//   AuthorizerType: JWT
//   IdentitySource: $request.header.Authorization
//   JwtConfiguration:
//     Audience: [ !Ref UserPoolClientId ]
//     Issuer: !Sub https://cognito-idp.${AWS::Region}.amazonaws.com/${UserPool}

// For Auth0 or other OIDC providers:
//   Issuer: https://your-domain.auth0.com/
//   Audience: ["https://api.example.com"]   # your API identifier in Auth0

HTTP API JWT authorizers do not support aud arrays by itself for providers that put audience in client_id (like some OAuth 2.0 providers). In those cases, use a Lambda authorizer with the simple response format to validate the token and return { isAuthorized: true }. The Lambda authorizer on HTTP API differs from REST API: there is no TOKEN type — only REQUEST type — and the default cache key is the full identitySource expression (typically $request.header.Authorization).

Per-route throttling and default stage settings

HTTP API throttling is configured in two layers: default stage-level throttle (applies to all routes) and per-route overrides via routeSettings. Both specify throttlingBurstLimit (maximum concurrent requests in a burst) and throttlingRateLimit (sustained requests per second). When throttled, API Gateway returns 429 Too Many Requests with a Retry-After header.

// AWS CDK — per-route throttle settings on HTTP API
const httpApi = new HttpApi(this, 'ToolsApi', {
  defaultAuthorizationScopes: ['openid'],
  // Default throttle for all routes
  throttle: {
    burstLimit: 500,
    rateLimit: 100   // sustained req/sec across all routes
  }
});

// Per-route override: stricter limit on expensive tool invocations
const stage = httpApi.defaultStage?.node.defaultChild as CfnStage;
stage.addPropertyOverride('RouteSettings', {
  'POST /tools/invoke': {
    ThrottlingBurstLimit: 50,
    ThrottlingRateLimit: 10   // max 10 req/sec for tool invocations
  },
  'GET /tools/status': {
    ThrottlingBurstLimit: 1000,
    ThrottlingRateLimit: 500  // status checks are cheap — allow more
  }
});

// Response when throttled — Lambda does NOT receive the request:
// HTTP 429 Too Many Requests
// { "message": "Too Many Requests" }
// Retry-After: 1
//
// Clients should implement exponential backoff with jitter starting at 1s.
// MCP client library should surface 429s as a retryable ToolError.

HTTP API vs REST API decision matrix

Failure modes reference