Connect UniFi On Prem to Claude: Automate Doors and System Logs

If you need to connect your on-premises UniFi access controllers to Claude to automate physical security, employee onboarding, or system audits, you need a Model Context Protocol (MCP) server. This server acts as the translation layer between Claude's tool calls and UniFi's REST APIs. You can either build and maintain this infrastructure yourself, or use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL. If your team uses ChatGPT, check out our guide on connecting UniFi On Prem to ChatGPT or explore our broader architectural overview on connecting UniFi On Prem to AI Agents.

Giving a Large Language Model (LLM) read and write access to physical hardware like doors, intercoms, and NFC readers introduces severe security and engineering challenges. You have to handle network tunneling to your on-prem controller, map complex relational access schemas to MCP tool definitions, and deal with physical hardware polling states. Every time you want to expose a new UniFi capability to your AI agent, you have to update your server code, redeploy, and test the integration. This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for UniFi On Prem, connect it natively to Claude, and execute complex physical security workflows using natural language.

The Engineering Reality of the UniFi On Prem API

A custom MCP server is a self-hosted integration layer. While the open MCP standard provides a predictable way for models to discover tools, the reality of implementing it against a physical hardware controller's API is painful.

If you decide to build a custom MCP server for UniFi On Prem, you own the entire API lifecycle. Here are the specific challenges you will face:

Asynchronous Hardware Polling Unlike purely digital SaaS APIs, UniFi controls physical hardware. When you instruct the API to enroll an NFC card, the system does not immediately return the card data. Instead, it wakes up a physical UA reader and opens an enrollment session. Your server must then constantly poll the get_nfc_enrollment_status endpoint to check if a human has physically tapped a card against the reader. Exposing this asynchronous polling loop directly to an LLM is a disaster - the model will rapidly burn through its token context waiting for a response, or hallucinate a success state before the physical action occurs. You have to build custom middleware to abstract this state machine away from the AI.

Deeply Nested Access Schemas UniFi's physical access control is highly relational. To grant a user access to a specific room, you cannot just update a single user record. You must navigate a complex hierarchy of Users, User Groups, Access Policies, Door Groups, Schedules, and Holiday Schedules. If you give an LLM raw access to these endpoints without standardized JSON schemas and clear relationship definitions, the model will struggle to construct the correct sequence of API calls. Truto dynamically derives these schemas directly from the integration definition, ensuring Claude understands exactly which ID maps to which entity type.

Handling Rate Limits and Hardware Constraints UniFi controllers (like the UDM Pro or Cloud Key) are physical appliances with limited compute. If a script or an over-eager AI agent spams the system logs endpoint or attempts to bulk-update hundreds of users without pagination, the controller will return HTTP 429 Too Many Requests. Truto normalizes these upstream rate limits into standard IETF headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset). Truto does not retry, throttle, or absorb these errors - it passes them transparently to the caller so your AI agent framework can implement proper retry and exponential backoff logic.

Instead of building this infrastructure from scratch, you can use Truto to generate a managed MCP server that handles the authentication, schema translation, and protocol bridging automatically.

How to Generate a UniFi On Prem MCP Server with Truto

Truto dynamically generates MCP tools based on the UniFi On Prem endpoints and documentation. You can generate a secure MCP server URL either through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

This is the fastest method for internal testing or setting up a personal Claude Desktop agent.

1. Navigate to the Integrated Accounts page in your Truto dashboard and select your connected UniFi On Prem instance.
2. Click the MCP Servers tab.
3. Click Create MCP Server.
4. Select your desired configuration. You can filter by methods (e.g., only read operations) or tags (e.g., only users and doors), and optionally set an expiration date for temporary access.
5. Click Create and copy the generated MCP server URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For enterprise deployments where you are spinning up individual AI agents for different IT administrators, you can generate MCP servers programmatically.

Make a POST request to the /integrated-account/:id/mcp endpoint:

curl -X POST https://api.truto.one/integrated-account/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UniFi SecOps MCP",
    "config": {
      "methods": ["read", "write"],
      "tags": ["doors", "system_logs", "users"]
    }
  }'

The API provisions the server and returns a fully authenticated URL:

{
  "id": "mcp_abc123",
  "name": "UniFi SecOps MCP",
  "config": {
    "methods": ["read", "write"],
    "tags": ["doors", "system_logs", "users"]
  },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

This URL is fully self-contained. It encodes the integrated account and configuration cryptographically. Do not expose this URL publicly.

How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you need to connect it to Claude. You can do this via the Claude Desktop UI (or web interface if using ChatGPT) or by directly editing the local configuration file.

Method A: Via the Claude UI

If you are using Claude Desktop or an enterprise workspace with UI-based connector management:

1. Open Claude and navigate to Settings -> Integrations -> Add MCP Server (or Settings -> Connectors depending on your tier).
2. Name your connector (e.g., "UniFi On Prem").
3. Paste the Truto MCP URL into the connection field.
4. Click Add. Claude will instantly connect to the URL, execute the MCP handshake, and ingest all available UniFi tools.

(Note: If you are configuring this for ChatGPT, go to Settings -> Apps -> Advanced settings, enable Developer mode, and add the URL under Custom connectors.)

Method B: Via Manual Config File (Claude Desktop)

For local development with Claude Desktop, you connect to the remote Truto MCP server using the Server-Sent Events (SSE) transport adapter provided by the official MCP SDK.

Open your claude_desktop_config.json file (typically located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows) and add the following configuration:

{
  "mcpServers": {
    "unifi_on_prem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-sse",
        "https://api.truto.one/mcp/a1b2c3d4e5f6..."
      ]
    }
  }
}

Save the file and restart Claude Desktop. The application will execute the npx command, connect to the Truto SSE bridge, and expose the UniFi tools to the model.

Hero Tools for UniFi On Prem

Truto automatically translates the complex UniFi API into clean, callable LLM tools. Here are the highest-leverage tools for automating physical security and IT operations.

Remote Door Unlock

uni_fi_on_prem_doors_remote_unlock allows Claude to trigger a physical door unlock remotely. This is critical for automated helpdesk workflows where verified employees request emergency access to a locked server room or office suite.

"I am locked out of the West Wing server room. Please verify my identity in the IT directory and trigger a remote unlock for door ID dr_88291."

Manage Emergency Lockdown Status

uni_fi_on_prem_doors_set_emergency_status allows security operations agents to instantly trigger or resolve physical lockdowns or evacuations across specific doors or entire building groups based on threat intelligence or manual override.

"We have an active security incident in Building B. Set the emergency status to 'lockdown' for all exterior doors immediately."

NFC Card Enrollment

uni_fi_on_prem_credentials_enroll_nfc_card wakes up a physical UA reader to await a card tap. This allows an AI agent to guide a new hire through the physical badge-in process, monitoring the session and assigning the resulting token to the user record.

"Start an NFC card enrollment session on the front desk reader (dev_1102). Let me know when the reader is active so I can tell the new employee to tap their physical badge."

User Directory Management

create_a_uni_fi_on_prem_user creates a new identity record in the UniFi system. This is the first step in physical onboarding, allowing the AI to sync HR platform data directly into the physical security controller.

"A new contractor, Sarah Connor, is starting today. Create a user record for her in UniFi with her email sarah@example.com."

Access Policy Assignment

uni_fi_on_prem_users_assign_access_policy links a specific user to one or more physical access policies (which contain door groups and schedules). This is how Claude grants or revokes physical access to specific areas.

"Assign the 'Standard Employee Access' policy (ID pol_9921) to Sarah Connor's user record so she can enter the main lobby during business hours."

System Log Analysis

list_all_uni_fi_on_prem_system_logs pulls event data from the controller, including authentications, door access events, and hardware status changes. This turns Claude into a physical security analyst capable of detecting anomalies.

"Pull the system logs for the past 24 hours focusing on the 'Server Room A' door. Are there any rejected access attempts during off-hours?"

To view the complete inventory of available UniFi On Prem tools, parameters, and JSON schemas, visit the UniFi On Prem integration page.

Workflows in Action

Providing an LLM with these tools allows you to orchestrate multi-step physical security and IT workflows entirely through natural language. Here is how Claude handles complex scenarios when connected to UniFi On Prem via Truto.

Scenario 1: Zero-Touch Employee Onboarding

An IT administrator wants to onboard a new employee, grant them physical access, and prepare a physical badge.

"We have a new engineer, David Kim, starting tomorrow. Create his user profile in UniFi, assign him the 'Engineering Suite' access policy, and trigger an NFC enrollment session on my desk reader so I can prep his badge."

How Claude executes this:

1. Calls create_a_uni_fi_on_prem_user passing "David" and "Kim" as required arguments, returning the new user ID (usr_445).
2. Calls uni_fi_on_prem_users_assign_access_policy using usr_445 and the known ID for the Engineering Suite policy.
3. Calls uni_fi_on_prem_credentials_enroll_nfc_card targeting the specific device ID of the admin's desk reader.
4. Claude informs the admin that the reader is active and awaiting a card tap to bind the physical credential to David's profile.

Scenario 2: Security Audit and Anomaly Detection

A SecOps manager wants to investigate a potential physical security breach after hours.

"Check the system logs from last night between 1 AM and 4 AM. Did anyone successfully unlock the Executive Suite door? If so, who was it, and what access policy permitted it?"

How Claude executes this:

sequenceDiagram
    participant User as SecOps Manager
    participant Claude as Claude
    participant MCP as Truto MCP Server
    participant UniFi as UniFi Controller

    User->>Claude: "Check logs for Exec Suite (1AM-4AM)..."
    Claude->>MCP: Call list_all_uni_fi_on_prem_system_logs<br>with time range and topic filters
    MCP->>UniFi: GET /api/v1/system/logs?since=...&until=...
    UniFi-->>MCP: Returns array of log events
    MCP-->>Claude: JSON array of door events
    Claude->>Claude: Analyzes logs for 'Executive Suite'<br>identifies successful unlocks
    Claude->>MCP: Call get_single_uni_fi_on_prem_user_by_id<br>for the actor ID in the log
    MCP->>UniFi: GET /api/v1/users/{id}
    UniFi-->>MCP: Returns user profile & policies
    MCP-->>Claude: JSON user object
    Claude-->>User: "Yes, John Doe accessed the suite at 2:14 AM.<br>He used the '24/7 Exec Access' policy."

The Outcome: Claude fetches the raw log data, parses the JSON to identify specific authentication events targeting that door, extracts the actor ID of the successful entry, fetches that user's profile to see their assigned policies, and summarizes the findings in a concise report.

Security and Access Control

Exposing an on-premises physical security system to an AI agent requires strict governance. Truto's MCP architecture provides several layers of security to ensure agents only access what they need.

• Method Filtering: Limit an MCP server to strictly read operations. If an agent is only used for log analysis, it physically cannot execute a uni_fi_on_prem_doors_remote_unlock command, preventing accidental physical breaches.
• Tag Filtering: Restrict tools to specific API resources. You can configure a server to only expose system_logs and users, completely hiding the doors and devices endpoints from the LLM.
• Ephemeral Servers: Use the expires_at parameter when generating an MCP token. This creates a time-bound URL - perfect for granting a contractor temporary AI automation access that automatically self-destructs at the end of the week.
• Enforced API Auth: By setting require_api_token_auth: true, the MCP URL alone is useless. The client connecting to the MCP server must also pass a valid Truto API token in the authorization header, ensuring only verified internal systems can access the physical infrastructure.

Moving Past Manual IT Operations

Connecting UniFi On Prem to Claude changes how you interact with physical security. You no longer have to navigate complex web UIs or write brittle python scripts to handle hardware polling loops. By using Truto to generate a managed MCP server, you offload the authentication, schema normalization, and protocol translation.

Your AI agents get instant, safe, and heavily curated access to UniFi's APIs, allowing you to automate everything from badge provisioning to emergency lockdowns using natural language.