unifi-console-mcp

Overview Schema Source Related Servers Discussions Admin

unifi_console_switch_port

DestructiveIdempotent

Preview, then apply, a setting change to one port on one UniFi switch, with safety checks, approval, and automatic rollback if connections break.

Instructions

Preview, then apply, a change to ONE port of ONE switch. Tier C: a wrong setting on an uplink, AP or console port can strand it.

Two steps, always: confirm=false returns a read-only preview (only that port's before/after, how the port is classified: uplink, infrastructure, client or unused, what is connected, warnings, errors, a fingerprint); then call again with the same fields plus confirm=true, that fingerprint and an approval_note. The console needs the whole port list on every save, so the tool sends every other port back exactly as read and checks afterwards that none of them changed. Risky fields (PoE, VLANs, isolation, BPDU guard, flow control, storm control) on uplink and infrastructure ports are refused unless acknowledge_infrastructure=true; a name change is always allowed. After a change every device that was connected must still be connected, otherwise the previous settings are put back automatically, once. Disabling a port, STP edge mode, port profiles and the other switch settings are not offered. Applying also needs UNIFI_CONSOLE_ENABLE_WRITES=true and 'switch_port' in UNIFI_CONSOLE_WRITE_ENTITIES. Every write is journalled.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`params`	Yes

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Oct 18, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Adds substantial context beyond annotations: the preview/apply flow, fingerprint binding, refusal of risky fields on uplink/infrastructure ports unless acknowledge_infrastructure=true, automatic single rollback if connected devices are lost, journalling, and the whole-port-list save requirement. This is fully consistent with destructiveHint=true and does not contradict idempotentHint=true.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the core purpose and the two-step requirement, then layers risk and exclusions in dense, purposeful sentences. Despite the length, every sentence adds operational guidance for a high-risk mutation tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the output schema exists, the description need not explain return values. Annotations already declare the safety profile, and the description supplies workflow, guardrails, prerequisites, rollback behavior, and exclusions. Complete for an agent to invoke the tool correctly at a high level.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the top-level params object, so the description must compensate. It gives meaning to confirm, fingerprint, approval_note, acknowledge_infrastructure, and groups risky fields, but does not explain many nested parameters such as poe_mode, lldpmed, reset, or keepalive. Partial compensation only.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb, resource and scope: preview then apply a change to ONE port of ONE switch, and flags Tier C risk. An agent can distinguish it from unifi_console_switch_port_detail, which reads a port rather than changing it.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly describes the two-step workflow (confirm=false preview, then confirm=true with fingerprint and approval_note) and lists prerequisites (UNIFI_CONSOLE_ENABLE_WRITES, 'switch_port' in UNIFI_CONSOLE_WRITE_ENTITIES). It also states what is not offered: disabling a port, STP edge mode, port profiles, and other switch settings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.