Skip to content

Claude MCP Server

The Normal Framework MCP server lets Claude interact directly with your building automation sites — exploring points, modeling equipment, writing hooks, diagnosing devices, and controlling equipment.

Normal Framework is published in the Claude connector directory, so for most people setup is two clicks: find it in the directory and sign in with your Normal Online account.

Normal Online Required

Your site must be connected to Normal Online with an active tunnel. The MCP server runs in Normal Online and reaches your site through that tunnel; local-only sites are not supported.

Setup

Claude.ai, Claude Desktop, and mobile

  1. Go to Settings → Connectors (or browse the full directory at claude.ai/directory).
  2. Search for Normal Framework and click Connect.
  3. Sign in with your Normal Online account and approve access.

The same connector list is shared across Claude.ai, Claude Desktop, mobile, and Cowork — connect once and it is available everywhere.

Team and Enterprise plans

On Team and Enterprise plans only administrators can enable connectors. If you see a Request button instead of Connect, click it to send the request to your organization's admins. Admins enable it from Admin Settings → Connectors.

Once connected, turn the connector on for a conversation with the + button in the chat composer, then Connectors.

Claude Code

If you sign in to Claude Code with a Claude.ai account, connectors you have already added there appear automatically — run /mcp to see them.

To add it directly instead:

claude mcp add --transport http normal-framework https://portal.normal-online.net/mcp

Then run /mcp inside Claude Code and follow the browser sign-in.

Use --scope user to make it available in every project, or --scope project to write a .mcp.json your team can commit:

{
  "mcpServers": {
    "normal-framework": {
      "type": "http",
      "url": "https://portal.normal-online.net/mcp"
    }
  }
}

The type field is required

A .mcp.json entry with a url but no type is read as a local stdio server and skipped. It must be "type": "http".

Selecting a Site

Authentication gets Claude into your Normal Online account, not into a specific building. Before any site-level tool works you must pick a tenant and a site. Just ask:

List my sites

Claude walks the connect tool through list_tenants → use_tenant → list_sites → use_site, and reports each site's connection health. Say which one you want and it connects.

Your selection persists across conversations for as long as your sign-in is valid, so you normally only do this once. To move to a different building, ask Claude to switch sites.

Verifying the Connection

Once a site is selected, ask:

What's on this site? Give me an overview.

Claude reports the NF version, the active protocol layers, and a device summary. If that comes back, everything is working.

What Claude Can Do

The connector exposes 22 tools. You never need to name them — describe what you want and Claude picks. Broadly:

  • Explore — search the point database, read current and historical values, discover naming patterns
  • Model — browse the Haystack ontology, create equipment types and instances, classify and tag points, build extraction workflows
  • Automate — write, deploy, run, and debug JavaScript hooks
  • Operate — diagnose device health and errors, scan for new devices, write setpoints, manage schedules and value conversions

The MCP Training Course walks through each of these with example prompts.

Troubleshooting

Connector missing in Claude Code — Connectors are only pulled from Claude.ai when your active login is a Claude.ai subscription. If you authenticate with an API key or a Bedrock/Vertex configuration, add the server explicitly with claude mcp add instead.

"No site connected" — The tenant/site selection was lost or the instance token expired. Ask Claude to list your sites and reselect one.

Connection refused / timeout — The site's tunnel to Normal Online may be down. Check that the site shows as online in the Normal Online dashboard.

Authentication errors — Remove and re-add the connector to re-authenticate. In Claude Code, use Clear authentication in the /mcp menu.

Intermittent failures — Tunnel connections can drop briefly. Claude retries failed tool calls; a single failure does not mean the site is down.