Connect UniFi to ChatGPT: Monitor Devices, SD-WAN, and Site Health

If you need to give an AI agent access to your network infrastructure to run diagnostics, you want to connect UniFi to ChatGPT. Using a Model Context Protocol (MCP) server, your AI agents can read device health, map SD-WAN topologies, audit ISP metrics, and even manage console paths. If your team uses Claude instead, check out our guide on connecting UniFi to Claude, or explore our broader architectural overview on connecting UniFi to AI Agents.

Giving a Large Language Model (LLM) read and write access to physical network infrastructure is a massive engineering challenge. You must navigate varying firmware versions, handle complex authentication across the UniFi Site Manager, map extensive JSON schemas to MCP tool definitions, and deal with strict rate limits. Every time an endpoint changes across UniFi OS upgrades, your server code breaks.

This guide breaks down exactly how to bypass the boilerplate using Truto. We will cover how to generate a secure, managed MCP server for UniFi, connect it natively to ChatGPT, and execute complex network administration workflows using natural language.

The Engineering Reality of the UniFi API

A custom MCP server is a self-hosted integration layer that translates an LLM's tool calls into REST API requests. While the open MCP standard provides a predictable way for ChatGPT to discover network administration tools, the reality of implementing it against the UniFi ecosystem is painful. You are not just building a standard CRUD integration. You are building against a distributed system of hardware controllers.

If you decide to build a custom MCP server for UniFi in-house, you own the entire API lifecycle. Here are the specific integration challenges that make the UniFi API uniquely difficult to work with.

The Cloud Proxy Pattern

UniFi networks are often managed via local consoles (like a Dream Machine or Cloud Key). To manage these remotely without exposing them directly to the internet, Ubiquiti uses the UniFi Site Manager as a cloud proxy. To make a change to a local network, you do not call a standard REST endpoint on a unified cloud server. Instead, you forward raw HTTP requests through a proxy endpoint to the specific application (Network or Protect) running on a specific console hardware ID.

If your custom MCP server does not properly format the encapsulated request body for the create_a_uni_fi_console_path tool, or fails to parse the un-normalized upstream response, the LLM will hallucinate the result.

Firmware-Dependent Schema Drift

When you pull host information from UniFi, the API returns a massive JSON payload. However, the structure of the userData and reportedState objects varies wildly depending on whether the host is running UniFi OS 3.x, UniFi OS 4.x, or an older self-hosted Network Server. If you try to enforce a strict, static JSON schema for your MCP tools, validation will fail across mixed hardware environments. Your MCP server must present a flexible schema to ChatGPT so the LLM can inspect the keys dynamically.

Host vs. Site Abstraction

The UniFi data model separates physical hardware from logical management boundaries. Devices belong to logical 'sites', and sites are managed by 'hosts' (consoles). If ChatGPT wants to find a specific access point, it cannot just query a global device list easily without understanding this hierarchy. Your AI agent will frequently need to chain tool calls - first listing the hosts, then listing the sites for a specific host, and finally querying the devices for that site.

Rate Limits and the 429 Reality

Network APIs are strictly rate-limited to protect the hardware controllers from being overwhelmed by aggressive polling. When you hit these limits, the UniFi API returns an HTTP 429 Too Many Requests error.

Note on Truto's rate limit handling: Truto does not retry, throttle, or apply backoff on rate limit errors. When the upstream UniFi API returns an HTTP 429, Truto passes that error directly to the caller. Truto normalizes the upstream rate limit information into standardized headers (ratelimit-limit, ratelimit-remaining, ratelimit-reset) per the IETF specification. The caller (your AI agent framework or custom script) is entirely responsible for implementing retry and backoff logic. Do not expect the integration layer to magically absorb rate limits.

Creating the UniFi MCP Server

Instead of building this infrastructure from scratch, you can use Truto to generate a dynamic, documentation-driven MCP server. Truto reads the existing resource definitions and documentation for the UniFi API and compiles them into a JSON-RPC 2.0 endpoint.

You can generate this server via the Truto user interface or programmatically via the API.

Method 1: Via the Truto UI

1. Log into Truto and navigate to your Integrated Accounts.
2. Select the connected UniFi account you want to expose to ChatGPT.
3. Click the MCP Servers tab.
4. Click Create MCP Server.
5. Configure the server. You can name it "UniFi Network Ops" and use the method filters to restrict access (e.g., selecting only read methods to prevent the LLM from altering network configs).
6. Click Create and copy the generated MCP server URL. It will look like https://api.truto.one/mcp/a1b2c3d4e5f6....

Method 2: Via the API

If you are provisioning environments programmatically for multiple tenants, you can generate the server via a POST request.

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 SD-WAN Diagnostics",
    "config": {
      "methods": ["read"]
    }
  }'

The API verifies that the UniFi integration has documented tools, generates a secure cryptographic token hashed via HMAC, stores it in distributed KV storage for low-latency lookups, and returns the ready-to-use URL.

{
  "id": "mcp_srv_987654321",
  "name": "UniFi SD-WAN Diagnostics",
  "config": { "methods": ["read"] },
  "expires_at": null,
  "url": "https://api.truto.one/mcp/a1b2c3d4e5f67890"
}

Connecting the MCP Server to ChatGPT

Because the MCP server URL contains a cryptographic token that securely identifies the exact integrated UniFi account, you do not need to configure complex OAuth flows inside ChatGPT. The URL is fully self-contained.

Method 1: Via the ChatGPT UI

For users on Pro, Plus, Team, or Enterprise accounts, you can add the connector directly in the application:

1. Open ChatGPT and navigate to Settings.
2. Go to the Apps section and click Advanced settings.
3. Toggle on Developer mode (MCP support requires this flag).
4. Under the MCP servers / Custom connectors section, click to add a new server.
5. Name: Enter "UniFi Admin" (or similar).
6. Server URL: Paste the Truto MCP URL you generated in the previous step.
7. Save the configuration. ChatGPT will immediately perform the protocol handshake, request tools/list, and load the UniFi capabilities.

Method 2: Via Local Configuration File

If you are running a local testing instance or using a custom desktop client that supports standard MCP config files, you can use the Server-Sent Events (SSE) transport adapter.

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

Hero Tools for UniFi

Truto exposes the entirety of the documented UniFi integration as tools. When ChatGPT asks for the tool list, it receives dynamic schemas outlining exactly what parameters are required and what data will be returned.

Here are the highest-leverage tools available for UniFi administration.

List All UniFi Devices

This tool retrieves the hardware status for all access points, switches, and gateways managed by hosts where the calling account is an owner or super admin. It returns critical health fields including mac, model, status, version, and firmwareStatus.

"Fetch all UniFi devices across my network and list any switches that currently have an offline status or require a firmware update."

List All UniFi ISP Metrics

Network reliability relies on ISP uptime. This tool queries the UniFi Site Manager for historical ISP performance metrics linked to the current sites, returning latency and uptime data in 5-minute or 1-hour intervals.

"Pull the 1-hour interval ISP metrics for all sites over the last 24 hours. Analyze the data to identify periods of high latency or packet loss."

List All UniFi SD-WAN Configs

Managing Site-to-Site VPNs manually is tedious. This tool returns all hub-and-spoke SD-WAN configurations associated with the UniFi account, providing the structure needed to diagnose routing issues.

"List all SD-WAN configurations. Identify the hub and any spoke connections associated with the primary office setup."

List All UniFi SD-WAN Config Status

Once you have an SD-WAN configuration ID, this tool fetches the live deployment status. It returns tunnel connection states, WAN statuses for hubs and spokes, and any active errors or warnings preventing the VPN from establishing.

"Check the deployment status for SD-WAN config '12345'. Inform me if there are any active warnings or if a spoke tunnel is currently down."

Bulk Update UniFi Console Paths

This tool acts as a proxy to forward a PUT request directly to a UniFi console's Network or Protect application via the UniFi Site Manager. You supply the id of the console and the specific path you are updating. The upstream response is passed through directly. Note: The target console firmware must be >= 5.0.3.

"Execute a bulk update to the console path '/proxy/network/api/s/default/rest/user' on console ID 'abcd' to revoke access for the specified MAC address list."

Create a UniFi Console Path

Similar to the update tool, this forwards a POST request to the proxied application. It is incredibly powerful for executing specific controller actions like creating vouchers, triggering reboots, or adjusting radio transmission power. The body schema is flexible to accommodate whatever the upstream API expects.

"Send a POST request to console 'abcd' at path '/proxy/network/api/s/default/cmd/devmgr' with the payload to restart the access point with MAC '00:11:22:33:44:55'."

To view the complete inventory of tools, schemas, and required parameters, visit the UniFi integration page.

Workflows in Action

Exposing individual endpoints to an LLM is useful, but the real power of MCP comes from agentic workflows. When ChatGPT has access to the UniFi toolset, it can chain operations together to solve complex support tickets without human intervention.

Scenario 1: SD-WAN Diagnostic Triage

When a remote branch office reports they cannot access internal servers, the network engineer needs to check the VPN status. Instead of logging into the UniFi portal, navigating to the SD-WAN section, and clicking through site configurations, they can ask ChatGPT.

"The remote branch office is reporting connectivity issues. Check our SD-WAN configurations, find the active deployment, and diagnose any tunnel warnings or errors."

Step-by-step execution:

1. Tool Call: list_all_uni_fi_sd_wan_configs (Returns the list of VPN configurations, allowing the LLM to identify the correct ID based on the name).
2. Tool Call: list_all_uni_fi_sd_wan_config_status (Passes the identified sd_wan_config_id to get the real-time tunnel state).
3. Result: ChatGPT parses the JSON response, identifies that the spoke WAN is down or the tunnel failed to establish, and outputs a human-readable summary of the exact failure point.

sequenceDiagram
    participant Admin as Network Admin
    participant ChatGPT as ChatGPT
    participant Truto as Truto MCP Server
    participant UniFi as UniFi API
    Admin->>ChatGPT: "Diagnose SD-WAN issues"
    ChatGPT->>Truto: Call list_all_uni_fi_sd_wan_configs
    Truto->>UniFi: GET /sdwan/configs
    UniFi-->>Truto: Config array JSON
    Truto-->>ChatGPT: Returns config ID '54321'
    ChatGPT->>Truto: Call list_all_uni_fi_sd_wan_config_status (id: 54321)
    Truto->>UniFi: GET /sdwan/configs/54321/status
    UniFi-->>Truto: Status JSON (Spoke tunnel down)
    Truto-->>ChatGPT: Returns tunnel errors
    ChatGPT-->>Admin: "Tunnel to branch office is down. Spoke WAN is offline."

Scenario 2: Multi-Site Firmware Inventory

Keeping hardware up to date across multiple clients or office locations is a major compliance requirement. An IT administrator can use ChatGPT to instantly audit the network fleet.

"Run an inventory across all UniFi hosts. List any devices that have an outdated firmware status or are currently disconnected. Format the result as a markdown table with the MAC address, model, and site ID."

Step-by-step execution:

1. Tool Call: list_all_uni_fi_hosts (Retrieves the list of active consoles managed by the account).
2. Tool Call: list_all_uni_fi_devices (Iterates through the devices, potentially filtering by host_ids if the user specifies a subset of the network).
3. Result: The LLM processes the massive array of devices, filters out the healthy ones, maps the schema properties (mac, model, firmwareStatus), and formats a clean table for the administrator to review.

Scenario 3: Automated ISP Performance Audit

When end-users complain about "slow internet," pinpointing the cause requires historical data. ChatGPT can gather and analyze ISP telemetry autonomously.

"Users at the main office are reporting slow internet today. Pull the ISP metrics for the site over the last 24 hours in 1-hour intervals and tell me if there was a spike in latency or an outage."

Step-by-step execution:

1. Tool Call: list_all_uni_fi_sites (Locates the siteId for the 'main office').
2. Tool Call: list_all_uni_fi_isp_metric_queries (Submits a query for the specific siteId using the requested time range and interval).
3. Result: ChatGPT receives the time-series array of latency and uptime metrics. It mathematically evaluates the array to spot anomalies and explains exactly when the performance degraded.

graph TD
    A["User Prompt:<br>Check internet performance"] --> B["Tool:<br>list_all_uni_fi_sites"]
    B --> C{"LLM finds<br>correct siteId?"}
    C -->|"Yes"| D["Tool:<br>list_all_uni_fi_isp_metric_queries"]
    C -->|"No"| E["Ask user to clarify<br>site name"]
    D --> F["Analyze time-series<br>JSON array"]
    F --> G["Output:<br>Outage detected at 14:00"]

Security and Access Control

Exposing your network infrastructure to an AI model requires strict governance. Truto's MCP servers provide several layers of security to ensure the LLM operates within bounded constraints.

• Method Filtering: When creating the server via UI or API, you can restrict the methods array to ["read"]. This ensures only get and list operations are compiled into tools. The LLM physically cannot execute a PUT, POST, or DELETE command, eliminating the risk of an accidental network configuration change.
• Tag Filtering: You can restrict the server to specific resource tags. If you only want the AI to analyze SD-WAN setups, you can filter tools by an "sd-wan" tag, hiding the broader device and host endpoints.
• Require API Token Auth: By setting require_api_token_auth: true, possession of the MCP URL is no longer sufficient. The connecting client must also supply a valid Truto API token in the Authorization header. This adds a secondary layer of authentication for highly privileged network operations.
• Time-Limited Access: You can define an expires_at ISO datetime when generating the server. Once the timestamp is reached, Truto's background alarm system purges the cryptographic token from distributed KV storage and the database instantly, ensuring the AI agent's access is strictly temporary.

Accelerating Network Operations with AI

Building a custom integration between UniFi and an LLM framework is an exercise in managing technical debt. From parsing undocumented proxy payloads to handling aggressive rate limits and dynamic JSON schemas, maintaining the integration layer quickly overshadows the value of the AI agent itself.

By leveraging a dynamic, documentation-driven MCP server, you eliminate the integration boilerplate. Your engineering team can focus on writing better prompts, designing safer agentic workflows, and automating complex SD-WAN diagnostics, while the underlying infrastructure handles the API translation securely.