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. 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 or explore our broader architectural overview on connecting UniFi to AI Agents.

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 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 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.

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.

{
  "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."

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.

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 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.