HERAIOT MCP

Connect an AI assistant to your entities, devices, telemetry, and dashboards. The assistant uses HERAIOT tools to answer questions with platform data and, when permitted, propose and carry out changes.

For example: “List my entities,” “Show temperature for entity COLD001FF during the last hour,” or “Preview a temperature chart before saving it.”

The planned server address is https://mcp.heraiot.com. Choose a connection URL below, or use the endpoint selector on the MCP page in HERAIOT Cloud.

Connect your assistant

You need a HERAIOT account with access to the intended tenant and resources, and an MCP client supporting Streamable HTTP and OAuth Authorization Code with PKCE. If your account requires MFA, complete that step during sign-in.

1. Add a remote MCP connection in your client.
2. For a reporting assistant, enter https://mcp.heraiot.com/mcp/readonly.
3. Complete the HERAIOT browser sign-in when prompted.
4. Confirm that tools are listed, then ask “List my available entities.”

An MCP URL is an API endpoint, not a webpage. Opening it in a browser is not a connection test. Clients that support HERAIOT OAuth handle access-token renewal; you do not need to paste credentials into your prompts.

Claude Desktop or a client using stdio configuration

For a client configured through mcpServers, use the mcp-remote adapter . It requires Node.js and npx on your computer. Merge this entry into the client’s configuration, preserving other servers, restart the client, and complete browser sign-in:

{
  "mcpServers": {
    "digisense": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.heraiot.com/mcp/readonly",
        "--resource",
        "https://mcp.heraiot.com/mcp"
      ]
    }
  }
}

Change the connection URL to select a category. Keep the --resource value unchanged: all HERAIOT endpoints use the same OAuth resource. Use the MCP page in HERAIOT Cloud to copy configuration for your selection.

Scoped endpoints

Prefix these paths with https://mcp.heraiot.com:

Excluded tools are unavailable and direct calls to them are rejected. Changing the URL requires a new MCP session. A session opened on one endpoint cannot be reused on another endpoint or by a different user/client.

Use All categories for tasks that need tools from several categories. For example, MQTT device creation requires list_device_types to resolve the exact type, and a command may require get_entity_info to inspect an entity’s outputs. The devices-only endpoint does not include those tools.

Permissions and tenant access

Every endpoint requires a valid HERAIOT OAuth token. The server checks its signature, issuer, audience, expiry, and mcp:tools scope. Explicit tenant requests must be in the token’s tenantIds; the backend also checks current account and resource access.

• dev and gadmin have platform-wide MCP tenant access.
• Integrators can reach their home, member, and owned tenants, excluding suspended tenants.
• Other users can reach their home and member tenants, excluding suspended tenants.
• Reaching a tenant does not grant every operation: entity read/write and management-role checks still apply. Platform roles bypass per-entity permission rows.

For a shared chatbot, operations run as the HERAIOT account used by its connection. An MQTT request’s tenantId selects a workspace; it does not authenticate the person sending the message. A shared platform-admin login therefore gives the chatbot that account’s broad access.

Device API tokens and MQTT broker credentials are not MCP OAuth tokens. See Tokens and access for their separate purposes.

Supported tools

Use the client’s tool schemas for the complete arguments. Discovery supports pagination, with at most 200 results per page. Some tools default to the token’s current tenant; entity discovery can search across the user’s authorized tenants when no tenant is specified. Include the intended tenant when it matters.

Write tools require confirmed: true after explicit user confirmation. The client should show the proposed action and obtain that confirmation; a boolean argument alone is not proof that a person approved it.

For dashboards, get the current dashboard and catalog, preview the operations, then save the confirmed changes with the latest expectedRevision. Preview does not save data but can still require edit permission. Replace mode can remove existing widgets.

There are currently no dedicated MCP tools for incidents, organizations, device groups, or statistical aggregation. The assistant must not claim to have run an unsupported operation.

Application and API integrations

A server-side MCP client sends its OAuth access token in the HTTP header:

Authorization: Bearer <DIGISENSE_OAUTH_ACCESS_TOKEN>

Use the selected endpoint as the Streamable HTTP transport URL. Obtain tokens through HERAIOT OAuth and renew them through the refresh-token flow; do not substitute a device token or the internal backend API key.

The audience remains /mcp even for a /readonly transport URL. Metadata is also available at the corresponding scoped path, such as /.well-known/oauth-protected-resource/mcp/_/devices/readonly.

For the Anthropic Messages API, follow the current MCP connector documentation . Configure HERAIOT as a remote URL server and supply its OAuth access token as the connector’s authorization_token. Your application is responsible for obtaining and refreshing that token. Keep provider-specific model names and API versions aligned with that provider’s documentation.

Example prompts

Use /mcp/readonly for:

• “List the entities I can read in tenant 2.”
• “Show temperature for entity COLD001FF between these two timestamps.”
• “Show the current dashboard for entity COLD001FF.”

Use /mcp, with the necessary permissions, for:

• “Find the exact device type named Cold Room, then propose an MQTT device using it.”
• “Preview a temperature chart for COLD001FF and ask before saving.”
• “Inspect the available outputs and ask me to confirm before changing relay1.”

Replace example names and serials with resources from your workspace.

Troubleshooting

To change scope, update the connection URL and reconnect. To stop using the integration, disable or remove it in your client; removing a connection does not by itself revoke a previously issued token.

For support, include the endpoint, tool name, error, and client version. Remove bearer tokens, refresh tokens, passwords, and private data from logs. See Getting help.