---
title: "Connect UniFi to Claude: Manage Sites, Hosts, and ISP Performance"
slug: connect-unifi-to-claude-manage-sites-hosts-and-isp-performance
date: 2026-07-25
author: Sidharth Verma
categories: ["AI & Agents"]
excerpt: "Learn how to build a managed MCP server to connect UniFi to Claude. Automate network monitoring, SD-WAN status checks, and ISP performance tracking."
tldr: "Connect your UniFi network infrastructure to Claude using a managed Model Context Protocol (MCP) server. Give your AI agents secure, authenticated access to query hosts, check SD-WAN health, and update console paths without building a custom integration."
canonical: https://truto.one/blog/connect-unifi-to-claude-manage-sites-hosts-and-isp-performance/
---

# Connect UniFi to Claude: Manage Sites, Hosts, and ISP Performance


If you need to connect your Ubiquiti UniFi infrastructure to Claude to automate network monitoring, SD-WAN health checks, or site management, you need a [Model Context Protocol (MCP) server](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/). 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 to ChatGPT](https://truto.one/connect-unifi-to-chatgpt-monitor-devices-sd-wan-and-site-health/) or explore our broader architectural overview on [connecting UniFi to AI Agents](https://truto.one/connect-unifi-to-ai-agents-automate-network-and-console-operations/).

Giving a Large Language Model (LLM) read and write access to a sprawling enterprise network ecosystem like UniFi is an engineering challenge. You have to handle fragmented authentication mechanisms, map complex nested JSON schemas to MCP tool definitions, and deal with UniFi's proxy pathways to local hardware consoles. Every time a UniFi OS update changes a data structure, 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](https://truto.one/managed-mcp-for-claude-full-saas-api-access-without-security-headaches/) for UniFi, connect it natively to Claude, and execute complex network operations using natural language.

## The Engineering Reality of the UniFi 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 API surface is painful. You are not just integrating a standard REST API - you are dealing with a hybrid cloud-to-hardware proxy layer.

If you decide to [build a custom MCP server](https://truto.one/the-hands-on-guide-to-building-mcp-servers-for-ai-agents-2026/) for UniFi, you own the entire API lifecycle. Here are the specific challenges you will face:

**Fragmented Firmware and Data Structures**
The response schemas for UniFi endpoints are notoriously fluid. When you query for a UniFi host, the structure of the `userData` and `reportedState` fields varies wildly depending on the specific UniFi OS or Network Server version running on that hardware. If you feed these raw, unpredictable JSON blobs directly to Claude without schema definitions, the model will hallucinate available data fields. Truto solves this by normalizing the documentation-driven schemas, ensuring Claude knows exactly what fields to expect regardless of the underlying OS version.

**Cloud-to-Console Proxying**
UniFi often requires routing requests through the UniFi Site Manager cloud connector down to specific local hardware (like a UDM Pro running the Network or Protect application). Endpoints like console path updates require forwarding raw POST or PUT requests through this tunnel, and they strictly require target consoles to be on firmware 5.0.3 or higher. Handling this reverse-proxy logic inside a custom MCP server is brittle. A managed layer standardizes this routing so the LLM just calls a single tool.

**Mutually Exclusive Query Parameters and Data Retention**
When querying ISP metrics, the UniFi API strictly enforces mutually exclusive parameters. You can pass a `duration` window, or you can pass `begin_timestamp` and `end_timestamp`, but if an LLM tries to pass both, the API rejects the call. Furthermore, metrics have strict retention cliffs: 5-minute intervals disappear after 24 hours, and 1-hour intervals are purged after 30 days. If your AI agent tries to fetch 5-minute granular data from a week ago, the request fails. 

**Rate Limits and 429 Errors**
Like any enterprise API, UniFi enforces rate limits. When your AI agent enters a tight `while` loop attempting to summarize 50 different sites, it will inevitably hit a rate limit. **Truto does not retry, throttle, or apply backoff on rate limit errors.** Instead, when the upstream API returns an HTTP 429, Truto passes that error directly to the caller (Claude) while normalizing the upstream rate limit info into standardized IETF headers (`ratelimit-limit`, `ratelimit-remaining`, `ratelimit-reset`). The caller - or the agent framework wrapping the caller - is responsible for implementing retry and backoff logic using these standardized headers.

## How to Generate a UniFi MCP Server with Truto

Truto dynamically generates MCP tools based on the actual resources and documentation defined for the UniFi integration. You can create an MCP server in two ways: through the Truto UI or programmatically via the API.

### Method 1: Creating via the Truto UI

For most teams, the fastest way to get started is via the dashboard:

1. Navigate to the **Integrated Accounts** page in your Truto dashboard and select your connected UniFi account.
2. Click the **MCP Servers** tab.
3. Click **Create MCP Server**.
4. Select your desired configuration (e.g., restrict to read-only methods, filter by specific tags like `network` or `isp`, and optionally set an expiration date).
5. Copy the generated MCP server URL (it will look like `https://api.truto.one/mcp/abc123def...`).

### Method 2: Creating via the API

If you are provisioning infrastructure dynamically for your own users, you can generate MCP servers programmatically. 

Make a `POST` request to `/integrated-account/:id/mcp` with your configuration preferences. 

```typescript
const response = await fetch('https://api.truto.one/integrated-account/<unifi_account_id>/mcp', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TRUTO_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: "UniFi Network Ops Server",
    config: {
      methods: ["read", "list"], // Restrict to safe operations
      require_api_token_auth: false
    }
  })
});

const mcpServer = await response.json();
console.log(mcpServer.url); // The URL Claude will use to connect
```

This endpoint validates that the UniFi integration has documented tools, generates a secure cryptographically hashed token, stores the configuration in durable state, and returns the ready-to-use URL.

## How to Connect the MCP Server to Claude

Once you have your Truto MCP URL, you can connect it to your Claude environment. 

### Method A: Via the Claude UI (Claude for Work / Desktop)

If you are using Claude Desktop or Claude for Work, you can add the server directly through the interface:

1. Open Claude and navigate to **Settings**.
2. Select **Integrations** (or **Connectors** depending on your tier).
3. Click **Add MCP Server** or **Add custom connector**.
4. Paste the Truto MCP URL you generated.
5. Click **Add**. Claude will immediately perform a handshake, request the `tools/list`, and make the UniFi operations available to the model.

### Method B: Via Manual Config File (Claude Desktop)

For developers managing their local environment configurations, you can update your `claude_desktop_config.json` file. Since Truto hosts the server, you will use the standard SSE transport mechanism provided by the official MCP SDK.

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

Restart Claude Desktop. The model will automatically read this configuration, connect to the Truto URL, and populate the tool list.

## UniFi Hero Tools for Claude

Truto maps UniFi's API surface into discrete, heavily documented tools. Here are the core "hero" operations your AI agents will rely on for network administration. 

### List All UniFi Hosts
**Tool Name:** `list_all_uni_fi_hosts`

This tool retrieves all UniFi hardware hosts associated with the authenticated UI account. It returns critical identifying information like the hardware ID, IP address, ownership status, and the raw `reportedState`. This is the starting point for almost any diagnostic workflow, as it provides the `id` needed for subsequent queries.

> "Claude, list all the UniFi hosts in my account and tell me if any of them are currently reporting an offline or blocked status."

### List All UniFi Devices
**Tool Name:** `list_all_uni_fi_devices`

While hosts represent the controllers (like Cloud Keys or UDM Pros), devices represent the actual networking gear (switches, access points) managed by those hosts. This tool returns the MAC address, model, connectivity status, and firmware status for the underlying hardware. You can optionally filter this down by passing specific `host_ids`.

> "Fetch all UniFi devices managed by host ID 12345. Are any access points currently running outdated firmware?"

### Check SD-WAN Configuration Status
**Tool Name:** `list_all_uni_fi_sd_wan_config_status`

For distributed enterprise networks using UniFi's Site Magic SD-WAN capabilities, monitoring tunnel health is critical. This tool requires an `sd_wan_config_id` and returns the deployment status of the hub-and-spoke topology, including WAN status, active tunnel connections, and any active warnings or errors.

> "Check the health of our regional SD-WAN config (ID 9876). I need a summary of any dropped tunnel connections or spoke errors logged in the last update."

### Query ISP Metric Performance
**Tool Name:** `list_all_uni_fi_isp_metric_queries`

This tool fetches WAN performance data, allowing agents to diagnose internet connectivity issues across multiple sites. It requires a `type` parameter and honors specific time intervals (5-minute or 1-hour granularity). Because Truto normalizes the schema, Claude knows not to request 5-minute data older than 24 hours.

> "Query the 1-hour ISP metrics for the last 7 days across our primary sites. Identify any extended periods where latency spiked above our standard threshold."

### Bulk Update Console Paths
**Tool Name:** `uni_fi_console_paths_bulk_update`

This is a powerful orchestration tool. It forwards a `PUT` request through the UniFi Site Manager cloud connector down to a specific local console's Network or Protect application. This allows Claude to execute configuration changes directly on the hardware without requiring direct local network access, provided the console firmware is >= 5.0.3.

> "Update the configuration on console ID 555 to adjust the stream limit on our primary Protect viewer layout. Here is the JSON payload for the new state."

> To see the complete list of available UniFi tools, detailed JSON schemas, and parameter requirements, check out the full integration reference.
>
> [View the UniFi integration](https://truto.one/integrations/detail/unifi)

## Workflows in Action

Connecting a single tool is useful. Chaining them together into autonomous workflows is where MCP servers fundamentally change IT operations. Here is how Claude handles complex networking requests using the Truto MCP server.

### Scenario 1: Multi-Site SD-WAN Diagnostic Audit

When a remote branch complains about intermittent connectivity, an IT admin needs to check the core SD-WAN health, verify the host controller is online, and audit the specific devices at that location.

> "Claude, our Dallas branch is reporting unstable network performance. Please check our primary SD-WAN config (ID 444) for any tunnel errors. If you find dropped connections specifically pointing to the Dallas host (ID 888), pull the device list for that host and tell me if any core switches are offline."

**How Claude executes this:**

1. **`list_all_uni_fi_sd_wan_config_status`**: Claude calls this tool passing the provided SD-WAN config ID. It parses the JSON response to evaluate the health of the hub and spokes.
2. **Analysis**: Claude identifies a warning in the payload indicating the spoke tunnel to host ID 888 has dropped packets.
3. **`get_single_uni_fi_host_by_id`**: Claude queries the specific Dallas host to verify its `lastConnectionStateChange` and ensure the cloud connector itself is online.
4. **`list_all_uni_fi_devices`**: Claude passes `host_ids: ["888"]` to pull the hardware roster for Dallas, identifying that a 24-port PoE switch is currently reporting an offline status.
5. **Response**: Claude provides the user with a synthesized markdown report linking the SD-WAN packet loss directly to the offline state of the core switch.

```mermaid
sequenceDiagram
    participant Admin as IT Admin
    participant Claude as Claude Desktop
    participant Truto as Truto MCP
    participant UniFi as UniFi API
    Admin->>Claude: "Check Dallas branch SD-WAN and devices..."
    Claude->>Truto: call list_all_uni_fi_sd_wan_config_status<br>{"sd_wan_config_id": "444"}
    Truto->>UniFi: GET /sd-wan/status
    UniFi-->>Truto: Hub and Spoke JSON
    Truto-->>Claude: Normalized Response
    Claude->>Truto: call get_single_uni_fi_host_by_id<br>{"id": "888"}
    Truto->>UniFi: GET /hosts/888
    UniFi-->>Truto: Host Status JSON
    Truto-->>Claude: Normalized Response
    Claude->>Truto: call list_all_uni_fi_devices<br>{"host_ids": ["888"]}
    Truto->>UniFi: GET /devices?host_ids=888
    UniFi-->>Truto: Device Roster JSON
    Truto-->>Claude: Normalized Response
    Claude-->>Admin: Markdown Diagnostic Report
```

### Scenario 2: Automated ISP Performance Reporting

Instead of manually exporting CSVs from the UniFi dashboard to report on ISP vendor performance, you can have Claude automatically compile latency and downtime reports.

> "Claude, generate an ISP performance report for the last week for our New York and London sites. Look at the 1-hour interval data and summarize the average latency and any total downtime events."

**How Claude executes this:**

1. **`list_all_uni_fi_sites`**: Claude queries this endpoint to fetch the `siteId` mappings, identifying the specific IDs for New York and London.
2. **`list_all_uni_fi_isp_metric_queries`**: Claude calls the metrics tool, strictly adhering to the schema rules by passing the 1-hour interval format and avoiding the mutually exclusive `duration` parameter in favor of exact begin/end timestamps for the 7-day window.
3. **Analysis**: Claude processes the time-series arrays returned by the API, calculating average latency figures across the requested periods.
4. **Response**: The model outputs a formatted table comparing the two sites, explicitly highlighting an outage event detected in the London data stream.

## Security and Access Control

Granting an AI agent access to core infrastructure APIs requires strict guardrails. Truto's MCP servers are designed with zero-trust principles, allowing you to narrowly scope exactly what Claude can do.

*   **Method Filtering:** When generating the MCP server URL, you can pass `methods: ["read"]`. This hard-codes the server at the infrastructure level to only expose `GET` and `LIST` operations. Even if Claude attempts to hallucinate a `create` or `update` request, the server will reject it, completely eliminating the risk of accidental configuration changes.
*   **Tag Filtering:** You can restrict the MCP server to specific functional areas using tags. For example, passing `tags: ["isp_metrics"]` ensures the server only exposes analytics tools, hiding device configuration endpoints entirely.
*   **Require API Token Auth:** By default, possessing the Truto MCP URL grants access. For enterprise deployments, you can enable `require_api_token_auth: true`. This forces the client (like a custom multi-agent framework) to pass a valid Truto session token in the HTTP Authorization header alongside the URL.
*   **Ephemeral Servers:** You can pass an `expires_at` ISO datetime when creating the server. Truto's durable state alarms will automatically purge the server token and configuration at that exact moment. This is perfect for giving a contractor or a temporary AI agent limited-time access to audit the network.

## Moving Beyond Point-to-Point Scripts

Writing custom Python scripts to parse UniFi's nested state arrays and manage proxy tunnels is a waste of engineering time. By treating the API integration as a managed infrastructure layer, you shift the complexity of pagination, schema normalization, and authentication away from your application logic.

Truto's MCP servers provide a [standardized JSON-RPC 2.0 interface](https://truto.one/what-is-mcp-and-mcp-servers-and-how-do-they-work/) that Claude natively understands. You get the full power of the UniFi API surface delivered directly into your AI workflows without maintaining a single line of connector code. 

> Ready to give your AI agents secure, managed access to UniFi and 100+ other enterprise APIs? Book a technical deep dive with our engineering team today.
>
> [Talk to us](https://cal.com/truto/partner-with-truto)