Connect UniFi On Prem to ChatGPT: Manage Access and Credentials

If you need to connect UniFi On Prem to ChatGPT to automate door access, manage credentials, and audit physical security logs, you need a Model Context Protocol (MCP) server. This infrastructure layer acts as the translation layer between ChatGPT's tool calls and your local UniFi controller's REST APIs. If your team uses Claude, check out our guide on connecting UniFi On Prem to Claude 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 building security is a high-stakes engineering challenge. You must handle secure tunneling to an on-premise network, parse proprietary hardware states, and ensure the model cannot accidentally trigger an unauthorized facility lockdown. You either spend weeks building, hosting, and maintaining a custom MCP server to bridge the cloud-to-local gap, or you use a managed integration platform like Truto to dynamically generate a secure, authenticated MCP server URL.

This guide breaks down exactly how to use Truto to generate a secure, managed MCP server for UniFi On Prem, connect it natively to ChatGPT, 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 UniFi's on-premise APIs is notoriously difficult.

If you decide to build a custom MCP server for UniFi On Prem, you own the entire API lifecycle. Here are the specific integration challenges that break standard CRUD assumptions when working with UniFi hardware:

The Cloud-to-Local Bridge Unlike standard SaaS APIs, UniFi On Prem controllers live on local networks. Exposing port 12445 to the public internet for an LLM to access is a massive security risk. Your custom MCP server must implement secure reverse tunneling or rely on a zero-trust network overlay. If the connection drops or latency spikes, the LLM will timeout and hallucinate a successful physical action, like opening a door that remains locked.

Hardware State Polling Mechanisms Provisioning physical access isn't a single API call. When you enroll an NFC card, you must call a specific endpoint to wake up a physical UA reader (uni_fi_on_prem_credentials_enroll_nfc_card), retrieve a session ID, and then continuously poll the enrollment status endpoint (uni_fi_on_prem_credentials_get_nfc_enrollment_status) until the hardware reads the card. Standard LLM tool execution expects synchronous returns. If your MCP server doesn't manage this polling loop and state translation, ChatGPT will fail the tool call before the user has time to tap their badge.

Strict Hierarchical Access Topologies UniFi enforces a rigid relational structure. You cannot simply "grant user X access to door Y." Doors belong to door groups; access policies bind door groups to time-based schedules; users belong to user groups, which inherit access policies. If an LLM attempts to modify a user's access, it must parse this entire topology. A custom MCP server must inject immense context into the system prompt to prevent the model from assigning conflicting schedules or overriding inherited group policies.

Rate Limits and System Logs When you ask an LLM to "analyze who accessed the server room today," it will attempt to pull the system logs. UniFi enforces strict local rate limits. It is critical to note that Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit info into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF spec. The caller - in this case, your agent framework - is entirely responsible for handling the retry and backoff logic.

How to Generate the UniFi On Prem MCP Server

Instead of writing custom tunneling and polling logic, you can use Truto to generate a secure MCP server. Truto dynamically derives MCP tools directly from the integration's documented API endpoints. A tool only appears in the MCP server if it has a corresponding documentation entry, ensuring the LLM only executes well-formed, deterministic operations.

You can generate the MCP server through the Truto UI or programmatically via the API.

Method 1: Via the Truto UI

For teams who want to manually provision a connector for a specific UniFi controller:

1. Navigate to the Integrated Accounts page in the Truto dashboard.
2. Select your connected UniFi On Prem instance.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Select your configuration. You can restrict the server to specific tags (e.g., doors, users) or methods (e.g., read).
6. Click Generate and copy the resulting URL (e.g., https://api.truto.one/mcp/a1b2c3d4e5f6...).

Method 2: Via the Truto API

For developers embedding AI features into their own applications, you can programmatically generate MCP servers for your users' UniFi instances on the fly.

Make a POST request to /integrated-account/:id/mcp. The API validates that the integration has tools available, generates a secure cryptographic token, and returns a ready-to-use JSON-RPC endpoint.

curl -X POST https://api.truto.one/admin/integrated-accounts/{integrated_account_id}/mcp \
  -H "Authorization: Bearer YOUR_TRUTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "UniFi Physical Security Agent",
    "config": {
      "methods": ["read", "write", "custom"]
    }
  }'

The response returns the URL you will feed to your AI client:

{
  "id": "mcp-7a8b9c0d",
  "name": "UniFi Physical Security Agent",
  "config": { "methods": ["read", "write", "custom"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f6..."
}

Connecting the MCP Server to ChatGPT

Once you have the Truto MCP URL, you must register it with your LLM client. Truto MCP servers are fully self-contained - the URL embeds the routing and authentication required to reach the specific UniFi On Prem controller.

Option A: Via the ChatGPT UI

If you are using the ChatGPT desktop application or web interface, you can add the server directly to your workspace:

1. In ChatGPT, navigate to Settings → Apps → Advanced settings.
2. Toggle Developer mode to ON (MCP support requires this flag, available on Pro, Plus, Business, Enterprise, and Education tiers).
3. Under MCP servers / Custom connectors, click Add new server.
4. Name: "UniFi Controller"
5. Server URL: Paste the Truto MCP URL.
6. Click Save. ChatGPT will execute an initialize handshake and automatically list the available UniFi tools.

Option B: Via Manual Config File (CLI / Desktop)

If you are building custom AI agents or running local frameworks (like Claude Desktop or custom LangChain setups), you map the Server-Sent Events (SSE) transport layer using the @modelcontextprotocol/server-sse package.

Add the following to your MCP configuration file (e.g., mcp_config.json):

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

UniFi On Prem Hero Tools

Truto exposes the full surface area of the UniFi API, but a few specific operations are critical for physical security automation. Here are the core tools your AI agent will use.

1. Remote Door Unlock

Tool Name: uni_fi_on_prem_doors_remote_unlock

This tool allows the LLM to trigger the relay on a physical door reader, granting immediate access. It requires the specific door_id and is highly sensitive.

"I'm standing outside the server room but my badge isn't working. Can you unlock the server room door for me? My employee ID is 492."

2. Set Emergency Status

Tool Name: uni_fi_on_prem_doors_set_emergency_status

Overrides normal access schedules to force a door into a lockdown (locked to everyone) or evacuation (unlocked for everyone) state.

"We have a reported security incident in the lobby. Immediately set the front entrance doors to lockdown status."

3. Assign PIN Codes

Tool Name: uni_fi_on_prem_users_assign_pin_code

Provisions a numerical access credential to a user. This skips the need for physical NFC cards and allows the LLM to handle temporary access provisioning.

"Assign a temporary PIN code of 837492 to the new IT contractor so they can access the network closet today."

4. Fetch User Details

Tool Name: get_single_uni_fi_on_prem_user_by_id

Retrieves the complete physical identity profile of a user, including their assigned access policies, NFC card tokens, registered license plates, and onboarding timestamp.

"Pull the profile for user ID 1093. Tell me which access policies they are assigned to and if they have an active NFC card."

5. Fetch System Logs

Tool Name: list_all_uni_fi_on_prem_system_logs

Queries the UniFi audit logs. Essential for investigating security incidents or tracing who opened a specific door. Remember, aggressive log polling may trigger 429 rate limits, which your agent must handle.

"Check the system logs for the last hour. Did anyone swipe their badge at the South Exit?"

6. Poll NFC Enrollment Status

Tool Name: uni_fi_on_prem_credentials_get_nfc_enrollment_status

Used in tandem with the enrollment session initiation. It checks the local UA reader to see if a physical card has been tapped and returns the resulting card ID and cryptographic token.

"Check the enrollment session ID 9934 to see if the user has tapped their new badge on the HR desk reader yet."

For the comprehensive schema definitions and the complete list of available operations, view the UniFi On Prem integration page.

Workflows in Action

AI agents shine when they chain multiple UniFi operations together to solve complex physical security tasks. Here is how ChatGPT executes real-world workflows using the Truto MCP server.

Scenario 1: Emergency Lockdown & Access Audit

A security admin uses ChatGPT to respond to an unauthorized entry report.

"Lock down the Main Entrance door immediately, then pull the system logs for the last 15 minutes to see who accessed it."

Execution Steps:

1. uni_fi_on_prem_doors_set_emergency_status: The agent calls this tool, passing the ID of the Main Entrance door and setting the status to lockdown.
2. list_all_uni_fi_on_prem_system_logs: The agent queries the audit logs, filtering by the door ID and the recent time window.

The Result: The physical doors lock instantly. ChatGPT then outputs a tabulated list of every user who swiped their badge at the door leading up to the lockdown, allowing the admin to identify the breach.

sequenceDiagram
    participant Admin
    participant ChatGPT
    participant MCP as Truto MCP Server
    participant UniFi as UniFi On Prem

    Admin->>ChatGPT: "Lock down Main Entrance and check logs."
    ChatGPT->>MCP: Call uni_fi_on_prem_doors_set_emergency_status
    MCP->>UniFi: POST /api/v1/developer/doors/{id}/emergency
    UniFi-->>MCP: 200 OK (Lockdown active)
    MCP-->>ChatGPT: Tool execution success
    ChatGPT->>MCP: Call list_all_uni_fi_on_prem_system_logs
    MCP->>UniFi: GET /api/v1/developer/system/logs?topic=door
    UniFi-->>MCP: Log payload
    MCP-->>ChatGPT: Parsed JSON array
    ChatGPT-->>Admin: "Door is locked. Here is the access list..."

Scenario 2: Remote Contractor Provisioning

An IT manager needs to grant temporary network room access to a contractor without physically handing them a badge.

"Fetch the user profile for contractor ID 9382, then assign them a temporary PIN code 123456 so they can access the server room."

Execution Steps:

1. get_single_uni_fi_on_prem_user_by_id: The agent retrieves the contractor's profile to verify they exist and are active in the system.
2. uni_fi_on_prem_users_assign_pin_code: The agent attaches the requested PIN code to the contractor's identity record.
3. uni_fi_on_prem_users_assign_access_policy: The agent ensures the user has the policy required to unlock the server room door.

The Result: The contractor can immediately walk up to the server room keypad, type in the PIN, and gain entry. ChatGPT confirms the assignment and policy update to the IT manager.

Security and Access Control

Exposing physical building infrastructure to an LLM requires strict boundary controls. Truto MCP servers support multiple security layers to ensure agents cannot act maliciously.

• Method Filtering: Limit the server to specific HTTP verbs. Pass methods: ["read"] during creation to allow the LLM to query system logs and user profiles, but completely block write actions like unlocking doors or deleting users.
• Tag Filtering: Restrict access by domain. Use tags: ["logs", "users"] to hide door control operations from the LLM entirely, reducing the risk of hallucinated physical actions.
• API Token Authentication: By setting require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The caller must also pass a valid Truto API token in the header, adding a strict Layer 7 authentication requirement.
• Expiration (TTL): Set an expires_at timestamp when creating the server. This is perfect for giving contractors or temporary automation scripts limited-time access to the physical security API. Truto automatically destroys the token when the time expires.

Shipping Physical Security Automation

Connecting ChatGPT to UniFi On Prem unlocks powerful automation for IT ops, physical security teams, and facility managers. Instead of forcing engineers to manually traverse complex relational door hierarchies, parse hardware polling states, and maintain secure local tunnels, Truto handles the infrastructure boilerplate.

By generating a secure, scoped MCP server, you give your AI agents the exact tools they need to audit access logs, provision credentials, and control physical environments—without compromising the integrity of your local network.