SNS Subscription Filter Policies for MCP Servers — Attribute Routing, String Match, Numeric Operators

Filter policy scope: message attributes vs message body

SNS supports two filter policy scopes, set per subscription via the FilterPolicyScope attribute:

For MCP monitoring, prefer message attributes: they are set explicitly at publish time, avoid coupling the filter policy to your JSON schema, and do not require SNS to parse the message body on every delivery attempt. Reserve MessageBody scope for legacy publishers you cannot modify to add attributes.

String operators

String operators apply to String-typed message attributes or string-valued JSON body fields.

// Publish with message attributes for filter policy evaluation
await snsClient.send(new PublishCommand({
  TopicArn: process.env.STATUS_TOPIC_ARN,
  Message: JSON.stringify({ endpointId, status, latencyMs, region }),
  MessageAttributes: {
    status:   { DataType: "String", StringValue: status },         // "healthy"|"degraded"|"unhealthy"
    region:   { DataType: "String", StringValue: region },         // "us-east-1", "eu-west-1", ...
    severity: { DataType: "String", StringValue: getSeverity(status, latencyMs) }, // "low"|"medium"|"high"|"critical"
    latencyMs: { DataType: "Number", StringValue: String(latencyMs) },
  },
}));

Numeric operators

Numeric operators apply to Number-typed message attributes. The attribute DataType must be "Number"; string attributes with numeric content are not evaluated as numbers.

Numeric operators are useful for latency-tier routing: send latencyMs > 5000 events to a SLO-breach queue, latencyMs between 1000 and 5000 to a degraded-performance queue, and latencyMs < 1000 to a healthy archive queue — all from a single publish call.

AND and OR semantics

Understanding AND vs OR is critical to writing correct filter policies:

• OR: Multiple values within one key's array are evaluated as OR. "status": ["degraded", "unhealthy"] matches messages where status is either degraded or unhealthy.
• AND: Multiple top-level keys in the filter policy object are evaluated as AND. A message must satisfy all key conditions to match.

// Filter policy: (status is "degraded" OR "unhealthy") AND (region starts with "eu-")
// This subscription only receives alerts from European endpoints with non-healthy status
{
  "status": ["degraded", "unhealthy"],
  "region": [{ "prefix": "eu-" }]
}

// Filter policy: latencyMs > 3000 AND severity is "high" OR "critical"
// Routes high-latency critical alerts to an ops pager queue
{
  "latencyMs": [{ "numeric": [">", 3000] }],
  "severity": ["high", "critical"]
}

Combining numeric and string conditions: You can mix string and numeric operators within a single filter policy. The AND rule applies across all key types. A message with latencyMs = 4500 (matches > 3000) but severity = "low" (does not match ["high", "critical"]) will not be delivered to this subscription.

CDK: subscriptions with filter policies

import * as sns from "aws-cdk-lib/aws-sns";
import * as sqs from "aws-cdk-lib/aws-sqs";
import * as subscriptions from "aws-cdk-lib/aws-sns-subscriptions";

declare const statusTopic: sns.Topic;

// Queue 1: critical alerts only (status unhealthy OR degraded AND severity critical)
const criticalAlertQueue = new sqs.Queue(this, "CriticalAlertQueue");
statusTopic.addSubscription(
  new subscriptions.SqsSubscription(criticalAlertQueue, {
    rawMessageDelivery: true,
    filterPolicy: {
      status: sns.SubscriptionFilter.stringFilter({
        allowlist: ["degraded", "unhealthy"],
      }),
      severity: sns.SubscriptionFilter.stringFilter({
        allowlist: ["high", "critical"],
      }),
    },
  })
);

// Queue 2: SLO latency breach (latencyMs > 5000, any status)
const sloBreachQueue = new sqs.Queue(this, "SloBreachQueue");
statusTopic.addSubscription(
  new subscriptions.SqsSubscription(sloBreachQueue, {
    rawMessageDelivery: true,
    filterPolicy: {
      latencyMs: sns.SubscriptionFilter.numericFilter({
        greaterThan: 5000,
      }),
    },
  })
);

// Queue 3: EU region all events (for regional dashboards)
const euRegionQueue = new sqs.Queue(this, "EuRegionQueue");
statusTopic.addSubscription(
  new subscriptions.SqsSubscription(euRegionQueue, {
    rawMessageDelivery: true,
    filterPolicyWithMessageBody: {
      region: sns.FilterOrPolicy.filter(
        sns.SubscriptionFilter.stringFilter({ matchPrefixes: ["eu-"] })
      ),
    },
  })
);

Filter policy size limit and evaluation performance

Billing note: SNS charges per message published to the topic, not per delivery. If you publish 10,000 healthy-probe events per day to a topic with a filter policy that excludes healthy events, those 10,000 messages are still billed as published. Only use SNS filtering to reduce downstream processing cost — not to reduce SNS publishing cost.

Common failure modes