Amazon IoT Core for MCP Servers — Protocols, Authentication, and IoT Policy Fundamentals

Protocol decision table

IoT Core supports three connection protocols. The choice depends on what is connecting — an embedded device or a server-side MCP tool.

MCP server recommendation: use the HTTPS Data Plane API. Your MCP server already has an IAM role or access key; there is no reason to manage X.509 certificates just to call IoT Core from a server. The SDK client handles SigV4 signing, retries, and regional endpoint selection automatically.

Two SDK clients — control plane vs data plane

IoT Core splits into two SDK packages with separate endpoints:

// Control plane — registry, rules, certificates, jobs
// Endpoint: iot.{region}.amazonaws.com
import { IoTClient, DescribeEndpointCommand, CreateThingCommand } from '@aws-sdk/client-iot';

// Data plane — publish messages, read/write device shadows, retained messages
// Endpoint: {accountPrefix}-ats.iot.{region}.amazonaws.com
import { IoTDataPlaneClient, PublishCommand, GetThingShadowCommand } from '@aws-sdk/client-iot-data-plane';

const region = process.env.AWS_REGION ?? 'us-east-1';

// Control plane client — standard regional endpoint
const iotControl = new IoTClient({ region });

// Data plane client — requires the account-specific ATS endpoint
// Retrieve it once and cache; it never changes for the account lifetime
const { endpointAddress } = await iotControl.send(
  new DescribeEndpointCommand({ endpointType: 'iot:Data-ATS' })
);
// endpointAddress looks like: a1b2c3d4e5f678-ats.iot.us-east-1.amazonaws.com

const iotData = new IoTDataPlaneClient({
  region,
  endpoint: `https://${endpointAddress}`,
});

ATS endpoint vs legacy VeriSign endpoint: always use iot:Data-ATS as the endpoint type. The legacy VeriSign-signed endpoint (iot:Data) is deprecated and returns a different hostname. Devices registered against the legacy endpoint will not connect to the ATS endpoint without reconfiguring their trust store. For server-side calls, the ATS endpoint is strictly correct and the SDK validates the TLS certificate against Amazon's CA hierarchy automatically.

Caching the endpoint: DescribeEndpointCommand is a control plane call and costs nothing beyond the API request. Store the returned endpointAddress in an environment variable or configuration file. It is stable — it does not rotate, does not change when you add or remove devices, and does not vary by Thing name.

Registering Things in the IoT registry

An IoT Thing is a logical representation of a physical or virtual device in the registry. Things are not required for MQTT communication — a device can connect to IoT Core without being registered — but the registry enables fleet management, shadow documents, and job targeting by Thing Group. For MCP tools that manage a fleet of devices, the registry is essential.

import {
  IoTClient,
  CreateThingCommand,
  DescribeThingCommand,
  UpdateThingCommand,
  CreateThingGroupCommand,
  AddThingToThingGroupCommand,
} from '@aws-sdk/client-iot';

const iot = new IoTClient({ region: 'us-east-1' });

// Create a Thing — idempotent: re-creating with same name updates attributes
const { thingName, thingArn } = await iot.send(new CreateThingCommand({
  thingName: 'sensor-floor-3-rack-7',
  thingTypeName: 'TemperatureSensor',  // optional; must exist first
  attributePayload: {
    attributes: {
      // String values only; max 3 searchable attributes
      location: 'floor-3-rack-7',
      model: 'TMP-3000',
      firmware: '2.1.4',
    },
    merge: true,  // true = merge with existing; false = replace all attributes
  },
}));

console.log('Thing ARN:', thingArn);
// arn:aws:iot:us-east-1:123456789012:thing/sensor-floor-3-rack-7

// Describe — read the current registration
const thing = await iot.send(new DescribeThingCommand({
  thingName: 'sensor-floor-3-rack-7',
}));
console.log(thing.attributes);  // { location: 'floor-3-rack-7', ... }
console.log(thing.version);     // integer incremented on every update

// Update attributes on an existing Thing
await iot.send(new UpdateThingCommand({
  thingName: 'sensor-floor-3-rack-7',
  attributePayload: {
    attributes: { firmware: '2.2.0' },
    merge: true,  // only update firmware; leave other attributes unchanged
  },
  // Optimistic locking — omit to skip version check
  expectedVersion: thing.version,
}));

// Organize Things into groups (for targeting jobs and rules)
await iot.send(new CreateThingGroupCommand({
  thingGroupName: 'floor-3-sensors',
  thingGroupProperties: {
    thingGroupDescription: 'All temperature sensors on floor 3',
    attributePayload: { attributes: { building: 'HQ', floor: '3' } },
  },
}));

await iot.send(new AddThingToThingGroupCommand({
  thingName: 'sensor-floor-3-rack-7',
  thingGroupName: 'floor-3-sensors',
}));

Thing Types: a Thing Type is a template that defines a set of searchable attributes for Things of that type. Create a Thing Type with CreateThingTypeCommand before referencing it in CreateThingCommand. Thing Types are immutable after creation except for their description. Deprecating a Thing Type with DeprecateThingTypeCommand prevents new Things from being assigned to it but does not affect existing Things.

searchable attributes: IoT Core Fleet Indexing (enabled separately via UpdateIndexingConfigurationCommand) indexes Thing attributes and allows queries like attributes.firmware:2.1.* AND attributes.location:floor-3-*. Without Fleet Indexing, you can still look up individual Things by name but cannot do attribute-based searches across the fleet.

Authentication methods

IoT Core supports four authentication methods. The right choice depends on whether the caller is a physical device or a server-side application.

MCP server rule: always use IAM + SigV4 for server-side MCP tools. Certificate management and rotation is non-trivial operational overhead that is not necessary when the caller is a server process with an IAM role. The IoT Data Plane API accepts standard SigV4 requests and the SDK handles signing transparently.

IoT Policy documents vs IAM policies

This is the most common source of confusion in IoT Core integrations. There are two separate policy systems:

• IAM policies — control what AWS API callers (Lambda, EC2, ECS, SDK callers) can do. When your MCP server calls PublishCommand or GetThingShadowCommand over HTTPS, IoT Core checks the IAM policy attached to the calling principal. Standard iot:Publish, iot:GetThingShadow, etc. actions in an IAM policy.
• IoT policies — control what devices connecting via MQTT can do. IoT policies are attached to X.509 certificates or Cognito identities. They use the same JSON structure as IAM policies but have IoT-specific actions (iot:Connect, iot:Publish, iot:Subscribe, iot:Receive) and IoT resource ARN formats.

Your MCP server never needs an IoT policy. IoT policies are for the devices. Your MCP server needs an IAM policy.

// IAM policy for an MCP server that reads device shadows and publishes commands
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "IoTControlPlaneRead",
      "Effect": "Allow",
      "Action": [
        "iot:DescribeThing",
        "iot:ListThings",
        "iot:DescribeEndpoint",
        "iot:SearchIndex"
      ],
      "Resource": "*"
    },
    {
      "Sid": "IoTDataPlane",
      "Effect": "Allow",
      "Action": [
        "iot:Publish",
        "iot:GetThingShadow",
        "iot:UpdateThingShadow",
        "iot:DeleteThingShadow",
        "iot:ListNamedShadowsForThing"
      ],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/*",
        "arn:aws:iot:us-east-1:123456789012:thing/*"
      ]
    }
  ]
}

An IoT policy attached to a device certificate looks similar in structure but uses IoT-specific actions and variable substitution:

// IoT policy attached to a device X.509 certificate — NOT for MCP servers
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "iot:Connect",
      // Policy variable ${iot:Connection.Thing.ThingName} prevents one certificate
      // from impersonating another Thing's clientId
      "Resource": "arn:aws:iot:us-east-1:123456789012:client/${iot:Connection.Thing.ThingName}"
    },
    {
      "Effect": "Allow",
      "Action": ["iot:Publish", "iot:Receive"],
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topic/devices/${iot:Connection.Thing.ThingName}/*",
        "arn:aws:iot:us-east-1:123456789012:topic/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
      ]
    },
    {
      "Effect": "Allow",
      "Action": "iot:Subscribe",
      "Resource": [
        "arn:aws:iot:us-east-1:123456789012:topicfilter/devices/${iot:Connection.Thing.ThingName}/*",
        "arn:aws:iot:us-east-1:123456789012:topicfilter/$aws/things/${iot:Connection.Thing.ThingName}/shadow/*"
      ]
    }
  ]
}

Policy variable ${iot:Connection.Thing.ThingName}: this substitution binds a certificate to only the Thing it is registered against. Without it, any device with the certificate could connect as any clientId and publish to any Thing's shadow — a security hole in multi-tenant fleets. This variable is only available in IoT policies, not IAM policies.

Connect action vs Publish/Subscribe: iot:Connect governs whether a device can establish an MQTT connection. iot:Publish governs whether it can send messages to a topic. iot:Subscribe governs whether it can register a subscription filter. iot:Receive governs whether messages that match a subscription are delivered. All four must be allowed for a device to function; restricting any one breaks the flow.

Publishing messages from an MCP server tool

An MCP server can publish MQTT messages to IoT Core topics via the HTTP Data Plane API. This is the standard way to send commands to devices — publish to a topic the device subscribes to, and the device receives it over its persistent MQTT connection.

import { IoTDataPlaneClient, PublishCommand } from '@aws-sdk/client-iot-data-plane';

const iotData = new IoTDataPlaneClient({
  region: 'us-east-1',
  endpoint: `https://${process.env.IOT_ENDPOINT}`,
});

// Send a command to a specific device via its command topic
async function sendDeviceCommand(
  thingName: string,
  command: Record
): Promise {
  const topic = `devices/${thingName}/commands`;
  const payload = JSON.stringify({
    ...command,
    timestamp: Date.now(),
    requestId: crypto.randomUUID(),
  });

  await iotData.send(new PublishCommand({
    topic,
    payload: Buffer.from(payload),
    // QoS 0 = fire-and-forget (default); QoS 1 = at-least-once delivery acknowledgment
    // HTTP publish only supports QoS 0 and 1; QoS 2 (exactly-once) is not available
    qos: 1,
    // retain: true — IoT Core stores the last message on this topic and delivers
    // it to new subscribers immediately; use for "last known command" patterns
    retain: false,
  }));
}

// Broadcast to all devices in a topic namespace
async function broadcastFirmwareUpdateNotification(
  firmwareVersion: string,
  downloadUrl: string
): Promise {
  await iotData.send(new PublishCommand({
    topic: 'devices/broadcast/firmware',
    payload: Buffer.from(JSON.stringify({ firmwareVersion, downloadUrl })),
    qos: 0,
  }));
}

QoS semantics: QoS 0 (at-most-once) delivers the message once with no acknowledgment — the device may or may not receive it depending on connection state. QoS 1 (at-least-once) stores the message and retries delivery until the broker receives an acknowledgment from the device. If the device is offline, QoS 1 messages queue until the device reconnects (if the device connected with cleanSession: false). For critical commands (turn off a valve, trigger an alert), use QoS 1. For high-frequency telemetry republishing, QoS 0 is acceptable.

Retained messages: setting retain: true causes IoT Core to store the most recent message on that topic. Any new subscriber receives the retained message immediately on subscription, before any new publishes arrive. Use this for status topics where a new device (or a reconnecting MCP server) should see the last-known state without waiting for the next publish. Only one retained message per topic is stored — each retained publish replaces the previous one.

Listing Things and querying device status

MCP tools frequently need to enumerate devices or look up which devices match certain criteria. Without Fleet Indexing, the only lookup is by exact Thing name or pagination through all Things.

import { ListThingsCommand, SearchIndexCommand } from '@aws-sdk/client-iot';

// Paginate all registered Things — no Fleet Indexing required
async function* listAllThings() {
  let nextToken: string | undefined;
  do {
    const { things, nextToken: next } = await iot.send(new ListThingsCommand({
      maxResults: 250,
      nextToken,
      // Optional filters (can combine both):
      thingTypeName: 'TemperatureSensor',
      attributeName: 'location',
      attributeValue: 'floor-3',  // exact match only without Fleet Indexing
    }));
    for (const thing of things ?? []) yield thing;
    nextToken = next;
  } while (nextToken);
}

// Fleet Indexing — wildcard and range queries across all Things
// Requires: UpdateIndexingConfigurationCommand to enable Thing indexing first
async function findThingsByFirmware(firmwarePrefix: string) {
  const { things } = await iot.send(new SearchIndexCommand({
    indexName: 'AWS_Things',  // the default index; always named AWS_Things
    queryString: `attributes.firmware:${firmwarePrefix}* AND thingTypeName:TemperatureSensor`,
    maxResults: 100,
  }));
  return things ?? [];
}

Fleet Indexing overhead: enabling Fleet Indexing adds a per-Thing cost (approximately $0.25 per million thing-hours indexed) and a per-search cost. For small fleets (under 1,000 Things), the cost is negligible. For large fleets, it is essential — paginating ListThingsCommand across 100,000 Things to find the ones with a specific firmware version would be impractically slow and expensive.

Common errors and their causes