AWS API Gateway Advanced Patterns for MCP Servers: Usage Plans, Canary Deployments, Request Validation, and Custom Domains

Pattern 1: Usage Plans — tier-based rate limiting and per-client billing analytics

The default API Gateway account-level throttle of 10,000 req/sec with a 5,000-request burst pool is shared across every API, every stage, and every client in the account. A single misbehaving MCP client — a sync loop gone wrong, a framework retrying too aggressively after a 500 — can exhaust this pool and cause 429 responses for all other clients simultaneously. Usage plans break this shared fate by assigning limits at the key level, enabling true multi-tenant isolation for MCP server products that offer tiered access.

Throttle vs quota: two different mechanisms, two different 429 messages

The most important concept in usage plans is that throttle and quota are completely independent limiting mechanisms, and the 429 errors they generate have different messages that require different client-side handling:

• Throttle (rateLimit + burstLimit): A token-bucket real-time rate limiter. rateLimit is the sustained rate in requests per second; burstLimit is how many tokens can accumulate when the rate is below the limit, which can be consumed in a single burst. Exceeding burst returns 429 {"message": "Too Many Requests"} immediately. The correct client response is exponential backoff with jitter.
• Quota (limit + period): A hard cap on total request count over a fixed calendar period — DAY, WEEK, or MONTH. Once the cap is reached, all subsequent requests return 403 {"message": "Limit Exceeded"} until the period resets at midnight UTC. The correct client response is to stop calling until the reset time, not to retry.

A typical MCP server product tier structure might look like this:

Four-step API key and usage plan workflow

The setup has a specific order: create the usage plan with the stage association, create the API key, link them with a UsagePlanKey resource, and verify. Skipping the linking step (step 3) is the most common mistake — the key exists and is enabled, but requests return 403 Forbidden because no UsagePlanKey resource associates the key with a plan.

# Step 1: Create the usage plan (stage association included at creation)
aws apigateway create-usage-plan \
  --name "mcp-pro-tier" \
  --throttle rateLimit=500,burstLimit=1000 \
  --quota limit=100000,offset=0,period=DAY \
  --api-stages apiId=abc123def,stage=prod

USAGE_PLAN_ID=$(aws apigateway get-usage-plans \
  --query "items[?name=='mcp-pro-tier'].id" --output text)

# Step 2: Create an API key for a specific client
aws apigateway create-api-key \
  --name "client-acme-corp" \
  --enabled \
  --generate-distinct-id

KEY_ID=$(aws apigateway get-api-keys \
  --query "items[?name=='client-acme-corp'].id" --output text)

# Step 3: Link the key to the plan (creates UsagePlanKey — MUST NOT skip this)
aws apigateway create-usage-plan-key \
  --usage-plan-id $USAGE_PLAN_ID \
  --key-id $KEY_ID \
  --key-type API_KEY

# Step 4: Verify the association exists
aws apigateway get-usage-plan-keys --usage-plan-id $USAGE_PLAN_ID

Per-method throttle overrides for protecting expensive endpoints

The usage plan throttle applies to all methods on the associated stage. You can override this at the method level to protect expensive MCP tool execution endpoints without tightening limits on cheap health check endpoints. Method-level throttling uses update-stage patch operations with ~1-encoded path separators:

# Tighter limit on expensive MCP tool execution endpoint
aws apigateway update-stage \
  --rest-api-id abc123def \
  --stage-name prod \
  --patch-operations \
    op=replace,path=/POST~1mcp/throttling/rateLimit,value=50 \
    op=replace,path=/POST~1mcp/throttling/burstLimit,value=100

# More generous limit on cheap health/status endpoint
aws apigateway update-stage \
  --rest-api-id abc123def \
  --stage-name prod \
  --patch-operations \
    op=replace,path=/GET~1status/throttling/rateLimit,value=1000 \
    op=replace,path=/GET~1status/throttling/burstLimit,value=2000

Method throttles are additive on top of usage plan throttles — the most restrictive limit wins. The path encoding uses ~1 for forward slashes: POST /mcp/tools/call becomes /POST~1mcp~1tools~1call/throttling/rateLimit.

Per-client billing analytics with CloudWatch Count by KeyId

API Gateway emits a Count metric in the AWS/ApiGateway namespace with a KeyId dimension for every authenticated request. This is zero-code per-client usage tracking — no custom telemetry, no middleware, no DynamoDB counter tables. The KeyId dimension only appears when metricsEnabled: true is set on the stage.

For quota tracking accessible to clients themselves (to power a "you've used X of Y requests today" dashboard), use the GetUsage API:

# Get remaining quota for a specific client key
aws apigateway get-usage \
  --usage-plan-id $USAGE_PLAN_ID \
  --key-id $KEY_ID \
  --start-date $(date -u +%Y-%m-%d) \
  --end-date $(date -u +%Y-%m-%d)

# Response: {"items": {"abc123keyid": [[850, 150]]}}
# Each pair is [used, remaining] for that day
# remaining: -1 means no quota limit (enterprise tier)

The GetUsage API is itself rate-limited — avoid polling it more than once per minute per key. Cache the result and invalidate on 429 Limit Exceeded responses from the API.

Pattern 2: Canary Deployments — safe version rollouts with AliveMCP monitoring

Standard API Gateway deployments replace the stage's deploymentId atomically — 100% of traffic switches to the new version instantly with no ability to roll back without creating another deployment. For MCP servers where a new tool schema format, a changed response structure, or an updated error-handling contract could break integrations, this all-or-nothing promotion is a high-risk operation. Canary deployments extend the stage model to hold two deployments simultaneously.

The dual-deployment stage model

A stage with an active canary has four relevant fields:

• deploymentId — the baseline snapshot (currently serving most traffic)
• canarySettings.deploymentId — the new canary snapshot (serving canary percentage)
• canarySettings.percentTraffic — fraction from 0.01 to 100 routed to canary
• canarySettings.stageVariableOverrides — stage variable values applied only to canary requests

API Gateway makes the baseline vs canary routing decision before any request reaches Lambda — clients have no input. The routing is random and weighted. Canary requests receive the response header X-Amzn-ApiGateway-Experimental: true; baseline requests do not. Canary deployments are a REST API feature — HTTP API v2 has no canary deployment concept.

Stage variable Lambda alias routing

Hard-coding a Lambda ARN in the integration URI requires a new API Gateway deployment every time you want to point the canary at a different Lambda version. Stage variables decouple the version selection from the API configuration: set the integration URI to arn:aws:lambda:REGION:ACCOUNT:function:mcp-handler:${stageVariables.lambdaAlias} and control which Lambda alias receives traffic through stage variable values instead of API deployments.

# Create Lambda aliases for stable and canary code paths
aws lambda create-alias \
  --function-name mcp-handler \
  --name stable \
  --function-version 1

aws lambda create-alias \
  --function-name mcp-handler \
  --name canary \
  --function-version 2

# Grant API Gateway permission to invoke both aliases
# Lambda resource policies are version/alias-specific — add permission per alias
aws lambda add-permission \
  --function-name mcp-handler:stable \
  --statement-id apigateway-stable \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:abc123def/prod/*/*"

aws lambda add-permission \
  --function-name mcp-handler:canary \
  --statement-id apigateway-canary \
  --action lambda:InvokeFunction \
  --principal apigateway.amazonaws.com \
  --source-arn "arn:aws:execute-api:us-east-1:123456789012:abc123def/prod/*/*"

The 5-phase canary workflow

The workflow has five phases with a critical ordering constraint at phase 4:

# PHASE 1: PREPARE — publish new Lambda version, update canary alias
NEW_VERSION=$(aws lambda publish-version \
  --function-name mcp-handler \
  --description "v2 - new tool schema format" \
  --query Version --output text)

aws lambda update-alias \
  --function-name mcp-handler \
  --name canary \
  --function-version $NEW_VERSION

# PHASE 2: ACTIVATE — create deployment with canary settings at 5%
NEW_DEPLOYMENT_ID=$(aws apigateway create-deployment \
  --rest-api-id abc123def \
  --stage-name prod \
  --canary-settings \
    percentTraffic=5,\
    stageVariableOverrides=\{lambdaAlias=canary\},\
    useStageCache=false \
  --query id --output text)

# PHASE 3: MONITOR — watch Lambda error rates by alias for 10-30 minutes
# If canary error rate rises: roll back immediately
# aws apigateway delete-stage-canary --rest-api-id abc123def --stage-name prod

# PHASE 4: PROMOTE — ramp to 100% FIRST (hard requirement — do not skip)
aws apigateway update-stage \
  --rest-api-id abc123def \
  --stage-name prod \
  --patch-operations \
    op=replace,path=/canarySettings/percentTraffic,value=100

# Wait 60 seconds for in-flight requests to complete

# PHASE 5: FINALIZE — copy canary deploymentId to main, remove canary settings
aws apigateway update-stage \
  --rest-api-id abc123def \
  --stage-name prod \
  --patch-operations \
    op=copy,path=/deploymentId,from=/canarySettings/deploymentId

aws apigateway delete-stage-canary \
  --rest-api-id abc123def \
  --stage-name prod

aws lambda update-alias \
  --function-name mcp-handler \
  --name stable \
  --function-version $NEW_VERSION

The critical constraint: in Phase 4, percentTraffic must reach 100 before copying the deployment pointer. Promoting directly from a partial canary leaves the stage in an inconsistent state where the main deploymentId was updated but canary settings still exist. This is a hard requirement documented by AWS, not a recommendation.

AliveMCP canary vs baseline health timelines

Standard uptime monitoring treats all responses from an endpoint equally — a 200 from the baseline and a 200 from the canary look identical. AliveMCP probes can use the X-Amzn-ApiGateway-Experimental: true response header to split monitoring into two separate health timelines within a single endpoint monitor:

• Baseline health timeline: Probes that did not receive the experimental header — the stable code path's availability and round-trip latency over the rollout window.
• Canary health timeline: Probes that received the experimental header — the new code path's availability and latency being evaluated before full promotion.

If canary P99 climbs while baseline P99 holds steady, you have a clear visual signal to call delete-stage-canary before the canary percentage climbs further. This is more reliable than CloudWatch Lambda duration metrics alone because AliveMCP probes the full round-trip including API Gateway overhead, not just Lambda execution time.

Pattern 3: Request Validation — edge-based schema enforcement before Lambda is invoked

A public MCP endpoint without request validation receives a constant stream of structurally invalid requests from internet scanners, bots, and misconfigured clients. These requests hit Lambda, fail immediately, and produce invocation charges, CloudWatch error increments, X-Ray trace spans, and application log noise — all before any business logic runs. A single RequestValidator with a JSON Schema model for the MCP protocol envelope silently blocks all of this at the API Gateway layer for free.

The cost math

Lambda pricing is $0.0000002 per invocation. At 10 million requests per day, that is $2.00/day in invocation cost alone before duration. If 20% are structurally malformed (conservative for a public endpoint), request validation saves $0.40/day in pure Lambda waste — $146/year. The more significant saving is operational: Lambda invocations that return errors appear in your error metrics and can make real error signals hard to detect. API Gateway validation removes these pre-invocation, keeping error rates meaningful and alarm thresholds tight.

JSON Schema model for the MCP protocol envelope

API Gateway supports JSON Schema draft-04 only. Draft-07 keywords like if/then/else, const, and contains are silently ignored — they do not cause an error, but the validation logic they define does not run. Every valid MCP request has a method string and an id (string or integer) — any request missing these fields is structurally invalid and can be safely rejected at the edge:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "title": "MCPToolCallRequest",
  "type": "object",
  "required": ["method", "id"],
  "properties": {
    "method": {
      "type": "string",
      "pattern": "^(tools/call|tools/list|resources/read|prompts/get)$"
    },
    "id": {
      "type": ["string", "integer"]
    },
    "params": {
      "type": "object"
    }
  },
  "additionalProperties": false
}

Four-step validation setup

Both the RequestValidator resource and the Model resource must be attached to the method — either one alone does nothing. The most common mistake is creating the validator and the model but forgetting to attach both to the method, or attaching them and forgetting to redeploy.

# Step 1: Create the model
aws apigateway create-model \
  --rest-api-id abc123def \
  --name MCPToolCallRequest \
  --content-type "application/json" \
  --schema file:///tmp/mcp-request-model.json

# Step 2: Create the RequestValidator
VALIDATOR_ID=$(aws apigateway create-request-validator \
  --rest-api-id abc123def \
  --name "mcp-body-and-params-validator" \
  --validate-request-body \
  --validate-request-parameters \
  --query id --output text)

# Step 3: Attach BOTH validator AND model to the method
# omitting either one means validation does not run
aws apigateway update-method \
  --rest-api-id abc123def \
  --resource-id $RESOURCE_ID \
  --http-method POST \
  --patch-operations \
    op=replace,path=/requestValidatorId,value=$VALIDATOR_ID \
    op=replace,path=/requestModels/application~1json,value=MCPToolCallRequest

# Step 4: Redeploy — method changes require a deployment to take effect
aws apigateway create-deployment \
  --rest-api-id abc123def \
  --stage-name prod \
  --description "Enable request validation"

Customizing 400 errors with GatewayResponse

The default validation failure response body is {"message": "Invalid request body"} — it tells the client something is wrong but not what. For MCP server clients that are themselves developer tools, this is frustrating. Use GatewayResponse to include $context.error.validationErrorString, which contains the specific JSON Schema failure message:

aws apigateway put-gateway-response \
  --rest-api-id abc123def \
  --response-type REQUEST_VALIDATION_ERROR \
  --status-code 400 \
  --response-templates '{"application/json": "{\"message\": \"$context.error.message\", \"detail\": \"$context.error.validationErrorString\", \"schema\": \"MCPToolCallRequest\"}"}' \
  --response-parameters '{"gatewayresponse.header.Access-Control-Allow-Origin": "'"'"'*'"'"'"}'

With this customization, a missing method field returns:

{
  "message": "Invalid request body",
  "detail": "object has missing required properties ([\"method\"])",
  "schema": "MCPToolCallRequest"
}

The CORS header in the GatewayResponse is not optional for browser-based MCP clients. Without it, a 400 validation rejection from API Gateway does not include Access-Control-Allow-Origin, and browsers display a misleading "CORS error" instead of the actual 400 message — the client sees no information about what was wrong with the request.

Parameter presence validation

RequestValidator can also check that required headers and query strings are present on every request. This is presence-only — it checks that the parameter exists, not what value it contains. To require a session-id header:

# Enable parameter validation on the validator
aws apigateway update-request-validator \
  --rest-api-id abc123def \
  --request-validator-id $VALIDATOR_ID \
  --patch-operations \
    op=replace,path=/validateRequestParameters,value=true

# Declare required parameters on the method
# value=true = required (missing returns 400), value=false = documented but optional
aws apigateway update-method \
  --rest-api-id abc123def \
  --resource-id $RESOURCE_ID \
  --http-method POST \
  --patch-operations \
    "op=add,path=/requestParameters/method.request.header.x-session-id,value=true"

Use lowercase consistently for header parameter declarations (method.request.header.x-session-id not method.request.header.X-Session-Id). API Gateway normalizes incoming headers to lowercase before matching, but if your declaration uses mixed case, matching behavior can be inconsistent across deployment environments.

Pattern 4: Custom Domains — stable URLs, version routing, and enterprise mTLS

The default execute-api.amazonaws.com hostname changes whenever the API is recreated. This means client integrations hard-coded to the default URL break silently on API replacement — a common operation during major version upgrades or incident recovery. Custom domains replace the volatile hostname with a stable, branded URL that you control, and base path mappings enable routing different path prefixes to different API stages without any client reconfiguration.

Regional vs edge-optimized: always choose regional

API Gateway offers two endpoint types for custom domains. The comparison determines your certificate region requirements and downstream flexibility:

AWS's own documentation now recommends regional endpoints for new deployments. Edge-optimized is a legacy default that predates regional support. For MCP servers, regional is the right choice in every scenario: it supports mTLS, keeps certificate management in one region, and lets you add CloudFront manually with custom cache behaviors if you need global edge presence later.

Four-phase creation workflow

# PHASE 1: Request and validate ACM certificate with DNS validation
CERT_ARN=$(aws acm request-certificate \
  --domain-name api.yourmcp.com \
  --validation-method DNS \
  --query CertificateArn --output text)

# Add the DNS validation CNAME to Route53, then wait
aws acm wait certificate-validated --certificate-arn $CERT_ARN

# PHASE 2: Create the regional custom domain name
DOMAIN_OUTPUT=$(aws apigateway create-domain-name \
  --domain-name api.yourmcp.com \
  --endpoint-configuration types=REGIONAL \
  --regional-certificate-arn $CERT_ARN \
  --security-policy TLS_1_2)

# IMPORTANT: save the regionalDomainName — this is what Route53 points at
# NOT the execute-api URL — they are completely different endpoints
REGIONAL_DOMAIN=$(echo $DOMAIN_OUTPUT | jq -r '.regionalDomainName')
REGIONAL_HZ=$(echo $DOMAIN_OUTPUT | jq -r '.regionalHostedZoneId')
# regionalDomainName looks like: d-abc123def.execute-api.us-east-1.amazonaws.com
# Note the d- prefix — it is NOT the same as abc123def.execute-api...

# PHASE 3: Create base path mappings
# base path must NOT have a leading slash — "v1" not "/v1"
aws apigateway create-base-path-mapping \
  --domain-name api.yourmcp.com \
  --rest-api-id abc123def \
  --stage prod \
  --base-path v1

# PHASE 4: Create Route53 A alias record
# AliasTarget.DNSName = regionalDomainName (not execute-api URL)
# AliasTarget.HostedZoneId = regionalHostedZoneId from create-domain-name output
aws route53 change-resource-record-sets \
  --hosted-zone-id $HOSTED_ZONE_ID \
  --change-batch "{
    \"Changes\": [{
      \"Action\": \"CREATE\",
      \"ResourceRecordSet\": {
        \"Name\": \"api.yourmcp.com\",
        \"Type\": \"A\",
        \"AliasTarget\": {
          \"HostedZoneId\": \"$REGIONAL_HZ\",
          \"DNSName\": \"$REGIONAL_DOMAIN\",
          \"EvaluateTargetHealth\": false
        }
      }
    }]
  }"

Base path mapping versioning and path stripping

Base path mappings enable API versioning without any client reconfiguration: api.yourmcp.com/v1 routes to the v1 API stage and api.yourmcp.com/v2 routes to the v2 API stage. When a request arrives at api.yourmcp.com/v1/mcp/tools/call, API Gateway strips the base path (v1) before forwarding — your Lambda handler receives /mcp/tools/call, not /v1/mcp/tools/call. Design your API routes assuming the base path prefix will never reach Lambda.

To sunset an old API version without client disruption, update the base path mapping to point to the new stage, or return a 410 Gone response from a Lambda that logs all remaining v1 callers:

# Update v1 mapping to point to a new stage after a major version upgrade
aws apigateway update-base-path-mapping \
  --domain-name api.yourmcp.com \
  --base-path v1 \
  --patch-operations \
    op=replace,path=/stage,value=prod-v2

# List all mappings for a domain
aws apigateway get-base-path-mappings \
  --domain-name api.yourmcp.com

Mutual TLS for enterprise clients

Enterprise MCP clients in regulated industries often require mutual TLS: the client must present a certificate signed by a trusted CA that you specify, in addition to the server's TLS certificate. API Gateway supports mTLS on regional custom domains via a PEM-encoded truststore bundle stored in S3.

The critical operational detail: API Gateway does not poll the S3 object for updates. After uploading a new CA to the truststore bundle, you must explicitly call update-domain-name with the new S3 object version ID to trigger re-ingestion. Skipping this step means newly added CAs are not trusted and newly issued client certificates will be rejected.

# S3 bucket must have versioning enabled — required by mTLS truststore
aws s3api put-bucket-versioning \
  --bucket yourmcp-mtls-truststore \
  --versioning-configuration Status=Enabled

aws s3 cp truststore.pem s3://yourmcp-mtls-truststore/truststore.pem

TRUSTSTORE_VERSION=$(aws s3api head-object \
  --bucket yourmcp-mtls-truststore \
  --key truststore.pem \
  --query VersionId --output text)

# Create domain with mTLS enabled
aws apigateway create-domain-name \
  --domain-name enterprise.yourmcp.com \
  --endpoint-configuration types=REGIONAL \
  --regional-certificate-arn $CERT_ARN \
  --security-policy TLS_1_2 \
  --mutual-tls-authentication \
    truststoreUri=s3://yourmcp-mtls-truststore/truststore.pem,\
    truststoreVersion=$TRUSTSTORE_VERSION

# After updating the truststore (adding a new CA cert):
# 1. Upload the new bundle to S3
# 2. Get the new version ID
# 3. Trigger API Gateway re-ingestion — API Gateway never polls S3 automatically
NEW_VERSION=$(aws s3api head-object \
  --bucket yourmcp-mtls-truststore \
  --key truststore.pem --query VersionId --output text)

aws apigateway update-domain-name \
  --domain-name enterprise.yourmcp.com \
  --patch-operations \
    op=replace,path=/mutualTlsAuthentication/truststoreVersion,value=$NEW_VERSION

mTLS and usage plan API keys can be layered on the same domain: the client must pass both the mTLS certificate check (enforced at the domain level, network identity) and provide a valid API key (enforced at the stage level, billing tier). When a client certificate fails mTLS, API Gateway returns a 403 without CORS headers — add a GatewayResponse for UNAUTHORIZED type to include Access-Control-Allow-Origin so browser-based MCP clients see the real error instead of a misleading CORS failure.

Production checklist

Failure modes across all four patterns