Summary: This MCP server lets an AI assistant inspect and manage a Ubiquiti UniFi network — reading devices, clients, sites and networks, and performing actions such as restarting devices or blocking clients.
Read devices: list all network devices (APs, switches, gateways) and get per-device activity, including connected clients and their traffic.
Read clients: list connected clients, optionally including offline/historical ones.
Read topology/config: list sites, current-site health, and all network (VLAN) configurations.
Act on devices: restart a device by MAC address.
Act on clients: block, unblock, or force-disconnect a client by MAC address.
Beyond this schema: the README advertises 94 tools covering device adoption/provisioning/upgrades and port power-cycling, guest authorization, network/VLAN CRUD, firewall rules, zone policies and groups, traffic rules and policy-based routes, QoS, NAT, port forwarding, static routes, WLANs, network objects, and port/RADIUS/WAN-SLA/WLAN-rate profiles.
Access: runs locally over stdio (default) or as a LAN HTTP service on port 8765 with bearer tokens minted in an admin UI on 8766; mutating tools apply immediately and a token grants the server's full capabilities.
Enables interaction with Ubiquiti UniFi network infrastructure for monitoring and management, including listing and restarting network devices (APs, switches, gateways), managing connected clients (blocking, unblocking, disconnecting), retrieving site health status, network configurations, and device activity data.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@UniFi MCP Server show me all connected clients on the network"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP (Model Context Protocol) server for Ubiquiti UniFi network devices. It lets an AI assistant such as Claude inspect and manage a UniFi network: devices, clients, sites, networks and VLANs, firewall rules and zone policies, traffic and QoS rules, routing, NAT, port forwarding, WLANs, and the various profile types. 94 tools in total; see Available tools.
It runs in one of two modes:
Mode | How it runs | Use it for |
stdio (default) | The MCP client starts | Claude Desktop or Claude Code on your own machine. |
HTTP ( | A persistent Streamable HTTP service on port 8765, protected by bearer tokens that are minted in a companion web UI on port 8766. | A Docker host or NAS on the LAN, shared by several people or machines. |
Further reading:
docs/usage-guide.md: Claude Code and Claude Desktop setup in depth, plus troubleshooting.
docs/qnap-deployment.md: step-by-step QNAP Container Station deployment, including a TLS reverse proxy.
docs/unifi-api.md: the UniFi Controller HTTP API this project wraps.
A reachable UniFi Controller: either a self-hosted software controller or a UniFi OS console (UDM, UDM Pro, UCG Max), and an account with administrator access to it.
For a local install: Python 3.13+ and uv.
For a container: Docker with Compose.
Related MCP server: UniFi MCP Server
git clone https://github.com/nntkio/unifiMCP.git
cd unifiMCP
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"This installs two console scripts into .venv/bin/:
unifi-mcp: the MCP server (stdio by default, HTTP with
MCP_TRANSPORT=http).
unifi-mcp-admin: the token-admin web UI. Only needed in HTTP mode.
Build the image from source:
git clone https://github.com/nntkio/unifiMCP.git
cd unifiMCP
docker compose build # produces unifi-mcp:latestOr pull the prebuilt multi-arch image (linux/amd64 and linux/arm64) from GitHub Container Registry, which is what the QNAP deployment files use:
docker pull ghcr.io/nntkio/unifi-mcp:latestCredentials are only ever supplied at container run time, never as
build arguments, so the image contains no secrets and is safe to push to a
registry. The Dockerfile installs the exact versions recorded in uv.lock
(mcp is pinned below 2.0, whose server API is incompatible with this
code).
Everything is configured through environment variables. .env.example
lists every one with comments; copy it to .env when using Docker Compose.
Nothing loads .env automatically outside Docker Compose. For a local run,
export the variables yourself, or launch through scripts/run-mcp.sh, which
reads .env, forces stdio, and then starts unifi-mcp from the venv.
Variable | Description | Default | Required |
| Controller URL (e.g. | - | Yes |
| Controller username | - | Yes |
| Controller password | - | Yes |
| Site name |
| No |
| Verify SSL certificates ( |
| No |
|
|
| No |
# Self-hosted software controller (port 8443)
UNIFI_HOST=https://192.168.1.1:8443
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false
UNIFI_IS_UNIFI_OS=false
# UniFi OS console (UDM / UDM Pro / UCG Max, port 443)
UNIFI_HOST=https://192.168.1.1
UNIFI_USERNAME=admin
UNIFI_PASSWORD=your-password
UNIFI_SITE=default
UNIFI_VERIFY_SSL=false
UNIFI_IS_UNIFI_OS=trueMCP_TRANSPORT selects how the server talks to its MCP client:
Value | What happens | When to use it |
| MCP over stdin/stdout. The | The MCP client launches |
| A persistent Streamable HTTP service on | A long-running container or NAS on the LAN that several clients connect to. This is what |
When the variable is unset the server defaults to stdio. .env.example
sets http because Docker Compose is its main consumer; a container
started in stdio mode has no stdin to talk to, so nothing can reach it and
its health check on port 8765 never passes. scripts/run-mcp.sh reads the
same .env but always forces stdio, so a client-launched server keeps
working with that file in place.
Variable | Description | Default |
|
|
|
| Bind host (HTTP mode only) |
|
| Bind port (HTTP mode only) |
|
| SQLite database shared with the token-admin service (HTTP mode only) |
|
Variable | Description | Default |
| Root login username |
|
| Root login password. Required. | - |
| Signs session cookies. Required. Generate with | - |
| Bind host |
|
| Bind port |
|
| Must point at the same file the MCP server uses |
|
You do not normally start the server yourself: the client launches it as a subprocess whenever it needs it. To smoke-test the binary on its own:
export UNIFI_HOST=https://192.168.1.1 UNIFI_USERNAME=admin UNIFI_PASSWORD=your-password
export UNIFI_VERIFY_SSL=false UNIFI_IS_UNIFI_OS=true
unifi-mcp # waits for MCP messages on stdin; Ctrl-C to stopclaude mcp add unifi \
-e UNIFI_HOST=https://192.168.1.1 \
-e UNIFI_USERNAME=admin \
-e UNIFI_PASSWORD=your-password \
-e UNIFI_VERIFY_SSL=false \
-e UNIFI_IS_UNIFI_OS=true \
-- /absolute/path/to/unifiMCP/.venv/bin/unifi-mcpRestart the Claude Code session afterwards; servers added mid-session are
not picked up until then. To keep the password out of the client config,
put the values in .env and point the command at
/absolute/path/to/unifiMCP/scripts/run-mcp.sh instead, with no -e
flags.
Add to the Claude Desktop config file
(~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
~/.config/claude/claude_desktop_config.json on Linux), then restart
Claude Desktop.
Local install:
{
"mcpServers": {
"unifi": {
"command": "/absolute/path/to/unifiMCP/.venv/bin/unifi-mcp",
"env": {
"UNIFI_HOST": "https://192.168.1.1",
"UNIFI_USERNAME": "admin",
"UNIFI_PASSWORD": "your-password",
"UNIFI_VERIFY_SSL": "false",
"UNIFI_IS_UNIFI_OS": "true"
}
}
}
}Docker (the -i flag is what keeps stdin open for the stdio transport):
{
"mcpServers": {
"unifi": {
"command": "docker",
"args": ["run", "-i", "--rm",
"-e", "UNIFI_HOST=https://192.168.1.1",
"-e", "UNIFI_USERNAME=admin",
"-e", "UNIFI_PASSWORD=your-password",
"-e", "UNIFI_VERIFY_SSL=false",
"-e", "UNIFI_IS_UNIFI_OS=true",
"unifi-mcp:latest"
]
}
}
}In HTTP mode two containers run from the same image, separated only by
their command::
Service | Port | Purpose |
| 8765 |
|
| 8766 | Web UI for creating accounts and minting or revoking bearer tokens. |
They share a Docker named volume (unifi-mcp-data) holding tokens.db:
accounts, token hashes, and the usage log. The admin service writes tokens
that the MCP server validates, with no network call between them.
Create .env from the example and fill it in:
cp .env.example .env
python3 -c "import secrets; print(secrets.token_urlsafe(32))" # paste into ADMIN_SESSION_SECRETIn .env, set the UniFi controller variables, and then:
Keep MCP_TRANSPORT=http, which the example file already sets. If it
is changed to stdio, the unifi-mcp container starts a server that
nothing can talk to, and its health check on port 8765 never passes.
ROOT_ADMIN_PASSWORD and ADMIN_SESSION_SECRET. Both are required;
leave either one out and the unifi-mcp-admin container exits at
startup.
Start the stack:
docker compose up -d
docker compose logs -f # watch both services come upVerify the services directly, before putting anything in front of them:
curl -i http://localhost:8765/healthz # 200, body "ok"
curl -s -o /dev/null -w '%{http_code}\n' -X POST http://localhost:8765/mcp # 401
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8766/login # 200Anything other than 401 on the second line means bearer auth is not
running. Stop and investigate: a valid token can restart devices and
rewrite firewall rules.
Mint a token in the admin UI. See Token admin service below.
Prove a real MCP call works:
TOKEN='<the token you just copied>'
curl -sS -X POST http://localhost:8765/mcp \
-H "Authorization: Bearer $TOKEN" \
-H 'Accept: application/json, text/event-stream' \
-H 'Content-Type: application/json' \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1"}}}'Expect an SSE frame containing "serverInfo":{"name":"unifi-mcp".
Point an MCP client at it. With Claude Code:
claude mcp add --transport http unifi http://<host>:8765/mcp \
--header "Authorization: Bearer <token>"Claude Desktop's config file only launches local commands, so it needs a small bridge to reach a remote URL with a bearer header; see the usage guide. Other clients that support remote Streamable HTTP servers need the same two pieces of information, typically in this shape (check your client's documentation for its exact format):
{
"mcpServers": {
"unifi": {
"url": "http://<host>:8765/mcp",
"headers": {
"Authorization": "Bearer <token>"
}
}
}
}The Accept header must list both application/json and
text/event-stream. Omit either and the MCP SDK answers 406 Not Acceptable, which is easy to misread as an auth failure.
/mcp and /mcp/ both work. The bare path is rewritten internally
rather than redirected, because many clients refuse to follow a redirect
on POST.
A reverse proxy must not buffer. MCP responses are Server-Sent
Events, and nginx buffers proxied responses by default, so the client
connects and then hangs with no error anywhere. Set proxy_buffering off,
proxy_cache off, and long read/send timeouts on the MCP host, and always
give clients the https:// URL once TLS is on. Full settings are in
docs/qnap-deployment.md.
Both services speak plain HTTP. TLS is expected to come from a reverse proxy in front. Until you have one, admin passwords and freshly minted tokens cross the LAN in cleartext. Never port-forward 8765 or 8766 from the internet.
A token grants everything the server can do, including mutating operations. There is no per-token scoping, so prefer short expiries.
TOKEN_DB_PATH must match between the two services, and the token
database lives only in the unifi-mcp-data volume. Deleting the volume
invalidates every issued token and account.
The Compose health check probes port 8765 inside the container. If
you change MCP_HTTP_PORT, update the healthcheck in the compose file
to match.
Upgrading: docker compose pull && docker compose up -d for the
registry image, or docker compose up -d --build for a source build.
Accounts and tokens survive, since they live in the volume rather than
the image.
unifi-mcp-admin is a small web UI, self-contained (fonts, stylesheet, and
script are served by the service itself, so it works on a LAN with no
internet access).
Root is the identity in ROOT_ADMIN_USERNAME / ROOT_ADMIN_PASSWORD.
It exists only as environment variables, with no database row, which is
what makes it structurally unable to own a bearer token. Signing in as root
opens two screens:
Accounts (/admin): create accounts, and see every account with the
tokens created under it (label, created, expires, status) plus totals for
all, active, and revoked tokens. For any account root can:
Reset password: a dialog asks for the new temporary password. The old password stops working immediately; the account's existing tokens keep working. The dialog also works without JavaScript.
Delete user: removes the account and all of its tokens.
Revoke any single token.
Usage (/admin/usage): a log of every call made to the MCP endpoint:
time (UTC), user, token, client IP, X-Forwarded-For, JSON-RPC method,
tool name, HTTP status, and duration. Each column has its own filter
(combined with AND) and the list pages 50 rows at a time. The MCP service
writes this log itself, one row per JSON-RPC message that passes bearer
auth, into the same SQLite database, so it needs no extra configuration.
Behind a reverse proxy the IP column shows the first X-Forwarded-For
hop and the direct peer is stored as well.
Everyone else logs in at http://<host>:8766/login with the temporary
password root gave them and lands on My tokens (/tokens) to create,
view, and revoke their own tokens. Each token has a label and an optional
expiry. A newly created token is shown exactly once: only its SHA-256
hash is stored, so copy it immediately. Account passwords are stored as
argon2 hashes.
The typical first run:
http://<host>:8766/login log in as root, create an account for yourself
http://<host>:8766/login log out, log back in as that account
http://<host>:8766/tokens create a token, copy it
http://<host>:8766/admin/usage later, as root: who called what, from whereThe full walkthrough, including verification steps and the nginx settings for a TLS reverse proxy, is in docs/qnap-deployment.md. The pieces involved:
scripts/publish-image.sh builds the multi-arch image on a
workstation and pushes it to ghcr.io/nntkio/unifi-mcp, tagged latest,
the version from pyproject.toml, and sha-<git sha>. Pass one extra
tag (scripts/publish-image.sh rc1) to add it alongside those, or
--local to build for this machine only and load it into the local
Docker daemon as :local without pushing. It needs Docker with buildx and
the gh CLI logged in with the write:packages scope
(gh auth refresh -s write:packages), or GHCR_TOKEN and GHCR_USER
for a dedicated PAT. IMAGE and PLATFORMS override the destination and
targets. If the default buildx builder cannot do both platforms the
script creates one named unifi-mcp-multiarch for the build.
deploy/docker-compose.qnap.yml pulls that image instead of
building, and reads its settings from a sibling qnap.env (copy
deploy/qnap.env.example). Use it when you can reach the NAS over SSH:
docker compose -f docker-compose.qnap.yml --env-file qnap.env pull
docker compose -f docker-compose.qnap.yml --env-file qnap.env up -ddeploy/docker-compose.container-station.yml is the paste-ready
variant for Container Station's "Create Application" box, which cannot
see a sibling env file, so the settings are inlined under environment:.
Replace every <...> placeholder. Note that Container Station stores
these values in its application config, readable by anyone with NAS admin
access.
deploy/qnap.env and any deploy/*.local.yml are ignored by git, so real
values kept next to the templates never get committed.
All tools operate on the site named by UNIFI_SITE; there is no per-call
site override. Mutating tools take effect on the controller immediately.
Domain | Tools |
Devices |
|
Clients |
|
Sites |
|
Networks (VLANs) |
|
Firewall rules and zone policies |
|
Firewall groups |
|
Traffic rules |
|
Traffic routes (policy-based routing) |
|
QoS rules |
|
NAT rules |
|
Port forwarding |
|
Static routes |
|
WLANs (Wi-Fi networks) |
|
Port profiles |
|
RADIUS profiles |
|
WAN SLA profiles |
|
WLAN rate profiles |
|
Network objects (address/port groups) |
|
Object-oriented network configs |
|
Predefined zone-based firewall policies are read-only: the enable, disable, batch-update, and batch-delete policy tools reject them. Each tool's parameters are described in its MCP schema, which any client shows when it lists the server's tools.
pytest # run tests
pytest --cov=src # with coverage
ruff check . # lint
ruff format . # formatThe package layout (one unifi_client/_<domain>.py mixin plus one
server/_<domain>.py tool module per UniFi API domain, with matching test
files) and the steps for adding a new domain are described in
CLAUDE.md.
MIT
Block a client from accessing the network
| Name | Required | Description | Default |
|---|---|---|---|
| mac | Yes | MAC address of the client to block |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. While it indicates a destructive action ('Block'), it doesn't specify whether this is permanent or temporary, what permissions are required, whether it affects other network services, or what the expected outcome looks like. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with no wasted words. It's appropriately sized and front-loaded, making it easy to understand immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'blocking' entails operationally, what happens to the client, whether the action is reversible, or what confirmation/response to expect. More context is needed given the tool's complexity and lack of structured metadata.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'mac' clearly documented. The description doesn't add any additional parameter context beyond what the schema provides, so it meets the baseline for high schema coverage without compensating value.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Block') and target ('client from accessing the network'), providing a specific verb+resource combination. However, it doesn't explicitly distinguish this from its sibling 'disconnect_client' or 'unblock_client', which would be needed for a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided about when to use this tool versus alternatives like 'disconnect_client' or 'unblock_client'. The description states what it does but offers no context about appropriate use cases, prerequisites, or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Force disconnect a client from the network
| Name | Required | Description | Default |
|---|---|---|---|
| mac | Yes | MAC address of the client to disconnect |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Force disconnect', implying a destructive action, but doesn't clarify permanence (temporary vs. permanent), permissions required, side effects (e.g., if the client can reconnect automatically), or error handling. This leaves significant gaps for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence with zero waste—'Force disconnect a client from the network'—front-loading the core action and target. It's appropriately sized for a simple tool with one parameter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (a destructive action with no output schema and no annotations), the description is incomplete. It doesn't address behavioral aspects like what 'Force' entails, potential impacts, or response format, leaving the agent with insufficient context to use it safely and effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the 'mac' parameter fully documented in the schema as 'MAC address of the client to disconnect'. The description adds no additional parameter semantics beyond what the schema provides, so the baseline score of 3 is appropriate given the schema handles the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Force disconnect') and target ('a client from the network'), providing a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'block_client' or 'unblock_client', which likely have related but distinct functions in client management.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'block_client' or 'unblock_client'. It lacks context about prerequisites (e.g., needing client connectivity status), exclusions, or typical scenarios for force disconnection versus other actions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all currently connected clients on the UniFi network
| Name | Required | Description | Default |
|---|---|---|---|
| include_offline | No | Include offline/historical clients |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get all'), implying a read-only operation, but doesn't clarify aspects like authentication needs, rate limits, or what 'currently connected' entails (e.g., real-time vs. cached data). This leaves significant gaps for a tool that interacts with network clients.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, direct sentence that efficiently conveys the core purpose without unnecessary words. It's front-loaded with the essential information, making it easy for an agent to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is insufficiently complete. It doesn't explain what the return data looks like (e.g., list format, fields included), nor does it address behavioral aspects like error handling or data freshness, which are critical for network monitoring tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the parameter 'include_offline' clearly documented in the schema itself. The description doesn't add any parameter-specific details beyond what the schema provides, so it meets the baseline score without compensating or detracting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get all') and resource ('currently connected clients on the UniFi network'), making the tool's purpose immediately understandable. However, it doesn't explicitly differentiate from sibling tools like 'get_devices' or 'get_device_activity', which might also retrieve client-related information, so it doesn't reach the highest score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools like 'get_devices' or 'get_device_activity', nor does it specify prerequisites or exclusions, leaving the agent to infer usage from context alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get activity for a specific device including connected clients and their traffic
| Name | Required | Description | Default |
|---|---|---|---|
| mac | Yes | MAC address of the device (AP or switch) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions what data is returned ('activity... including connected clients and their traffic') but doesn't disclose behavioral traits like whether this is a real-time or historical query, rate limits, authentication needs, error conditions, or response format. For a tool with no annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose. Every word earns its place by specifying the action, target, and included data without redundancy or fluff. It's appropriately sized for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a query tool with no output schema and no annotations), the description is incomplete. It hints at return data but doesn't detail the structure (e.g., what 'activity' entails, traffic metrics format, or client details). Without annotations or output schema, more context on behavior and results is needed for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds no parameter semantics beyond what the schema provides. The schema has 100% coverage with a clear description for the 'mac' parameter, so the baseline is 3. The description doesn't elaborate on MAC address format, examples, or how it relates to device types (AP or switch mentioned in schema), so it doesn't add value here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'activity for a specific device', specifying it includes 'connected clients and their traffic'. It distinguishes from siblings like 'get_clients' (general client list) and 'get_devices' (device list) by focusing on activity for a single device. However, it doesn't explicitly contrast with all siblings, so it's not a perfect 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a device MAC from 'get_devices' first), exclusions, or comparisons to siblings like 'get_clients' (which might list clients without device-specific activity). Usage is implied by the purpose but not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all UniFi network devices (access points, switches, gateways)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states the tool retrieves devices but doesn't disclose behavioral traits such as whether it requires authentication, rate limits, pagination, error handling, or what the return format looks like (e.g., list of objects with fields). For a read operation with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves beyond its basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the key information ('Get all UniFi network devices') and adds clarifying examples without redundancy. Every word earns its place, making it easy to parse quickly. There's no wasted verbiage or structural issues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is complete enough for basic understanding. It specifies the resource type and examples, which suffices for a simple read operation. However, without annotations or output schema, it lacks details on behavioral aspects like response format or operational constraints, leaving some contextual gaps for an agent to use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, as there are none to explain. This meets the baseline for tools with no parameters, where the description focuses on purpose rather than inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('all UniFi network devices') with specific examples (access points, switches, gateways). It distinguishes the tool's scope from siblings like get_clients (which gets clients) or get_networks (which gets networks), but doesn't explicitly contrast them. The purpose is unambiguous but lacks explicit sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'all UniFi network devices', suggesting it's for retrieving device inventory rather than client or network data. However, it doesn't provide explicit guidance on when to use this versus alternatives like get_device_activity (for activity logs) or restart_device (for device management), nor does it mention prerequisites or exclusions. Usage is contextually implied but not clearly articulated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all network configurations for the current site
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get'), implying a read-only operation, but doesn't specify details like pagination, rate limits, authentication needs, or what 'all network configurations' entails (e.g., format, scope). This leaves significant gaps in understanding how the tool behaves beyond its basic purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the tool's purpose without unnecessary words. It is front-loaded with the core action and resource, making it easy to parse. Every part of the sentence earns its place by specifying scope ('all', 'for the current site'), ensuring no waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It covers the basic purpose and scope but lacks details on behavioral traits (e.g., response format, limitations) that would be helpful for an agent. Without annotations or output schema, more context on what 'network configurations' includes could improve completeness, but it meets the minimum for this low-complexity case.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so no parameter documentation is needed. The description doesn't add param info, which is appropriate here. A baseline of 4 is applied as it adequately handles the lack of parameters without redundancy or omission.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get') and resource ('all network configurations for the current site'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_sites' or 'get_devices', but the scope ('network configurations') is specific enough to imply distinction. No tautology or misleading elements are present.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_sites' or 'get_devices', nor does it mention prerequisites or exclusions. It implies usage for retrieving network data in the current site context, but this is minimal and lacks explicit comparison to sibling tools, leaving the agent to infer appropriate contexts.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get health status for the current site
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states it 'gets' health status, implying a read operation, but doesn't specify what 'health status' includes (e.g., metrics, uptime, errors), whether it requires authentication, or how it handles errors. For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence with zero waste—it directly states the tool's purpose without fluff. It's appropriately sized for a simple tool and front-loaded with the essential information. Every word earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters, no annotations, and no output schema, the description is minimally adequate but lacks depth. It explains what the tool does but doesn't cover behavioral aspects like return format or error handling. For a simple read tool, it's complete enough to understand the basic purpose but misses contextual details that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there's no need for parameter details in the description. The description appropriately doesn't mention parameters, avoiding redundancy. A baseline of 4 is justified as it doesn't add unnecessary information beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('health status for the current site'), making the purpose immediately understandable. It doesn't distinguish from siblings like 'get_sites' or 'get_devices', but it's specific enough to understand what it does. The description avoids tautology by not just restating the name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_sites' or 'get_devices'. It implies usage for checking site health but doesn't specify context, prerequisites, or exclusions. Without any when-to-use information, it leaves the agent to guess based on sibling tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get all UniFi sites configured on the controller
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool retrieves data ('Get all UniFi sites'), implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, response format, or potential errors. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without unnecessary words. It directly answers 'what does this tool do?' with zero waste, making it easy for an agent to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is adequate but has clear gaps. It explains the basic purpose but lacks behavioral details (e.g., response structure, error handling) that would help an agent use it correctly. For a read-only tool with no parameters, it's minimally viable but could be more informative.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100% (as there are no parameters to describe). The description doesn't need to add parameter semantics beyond the schema, so it meets the baseline for tools with no parameters. No additional value is required or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('all UniFi sites configured on the controller'), making the purpose immediately understandable. It doesn't explicitly differentiate from sibling tools like 'get_site_health', but the specificity of 'sites' versus 'site health' provides implicit distinction. The description avoids tautology by not merely restating the tool name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, context for usage, or comparisons to siblings like 'get_site_health' or 'get_networks'. The agent must infer usage based on the tool name and description alone, which is insufficient for optimal selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Restart a UniFi network device by its MAC address
| Name | Required | Description | Default |
|---|---|---|---|
| mac | Yes | MAC address of the device to restart (e.g., '00:11:22:33:44:55') |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Restart' implies a disruptive action, it doesn't specify whether this requires admin permissions, if the device becomes temporarily unavailable, potential side effects, or what happens on failure. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core purpose without any wasted words. It's appropriately sized and front-loaded with the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't address behavioral aspects like permissions needed, disruption level, error conditions, or return values. Given the complexity of restarting network devices, more contextual information is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already fully documents the single 'mac' parameter with format examples. The description adds no additional parameter semantics beyond what's in the schema, maintaining the baseline score for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Restart') and target resource ('a UniFi network device by its MAC address'), distinguishing it from sibling tools like block_client or get_devices. It uses precise language that leaves no ambiguity about the tool's function.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like disconnect_client or unblock_client, nor does it mention prerequisites or constraints. It simply states what the tool does without contextual usage information.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Unblock a previously blocked client
| Name | Required | Description | Default |
|---|---|---|---|
| mac | Yes | MAC address of the client to unblock |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'unblock' implies a state change operation, the description doesn't specify whether this requires admin permissions, whether it's reversible, what happens to the client's network access, or if there are rate limits. It provides minimal behavioral context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that states exactly what the tool does with zero wasted words. It's appropriately sized for a simple operation and gets straight to the point without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a state-changing tool with no annotations and no output schema, the description is insufficient. It doesn't explain what 'unblocking' entails operationally, what permissions are required, what the expected outcome is, or how to verify success. Given the complexity of network management operations, more context is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 100% description coverage, with the single parameter 'mac' clearly documented as 'MAC address of the client to unblock.' The description doesn't add parameter details beyond what the schema provides, but with only one well-documented parameter and high schema coverage, the baseline is appropriately high.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('unblock') and target ('a previously blocked client'), making the purpose immediately understandable. However, it doesn't differentiate this tool from its sibling 'block_client' beyond the opposite action, missing an opportunity to clarify the relationship between blocking and unblocking operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., the client must already be blocked), when unblocking is appropriate, or how this differs from other client management tools like 'disconnect_client' or 'restart_device'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
block_clientdisconnect_clientget_clientsget_device_activityget_devicesget_networksget_site_healthget_sitesrestart_deviceunblock_clientScored across 10 tools
Each tool has a clearly distinct purpose with no ambiguity. For example, block_client and disconnect_client serve different functions (blocking vs. disconnecting), while get_clients, get_devices, get_networks, and get_sites each target specific resource types. The actions and resources are well-defined and non-overlapping.
All tool names follow a consistent verb_noun pattern using snake_case, such as block_client, get_clients, and restart_device. This uniformity makes the tool set predictable and easy to understand, with no deviations in naming conventions.
With 10 tools, the server is well-scoped for managing a UniFi network. Each tool serves a clear purpose in client, device, network, and site management, with no redundant or trivial tools. The count aligns well with the domain's typical operations.
The tool set covers core CRUD and lifecycle operations for UniFi management, including monitoring (get_*), control (block/disconnect/restart), and site handling. A minor gap exists in update operations for configurations (e.g., updating network settings), but agents can work around this with the provided tools for most workflows.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
Inspect and control your Northflank projects, services, jobs, and builds from your AI assistant.
Unified MCP Server is a remote MCP connector for AI agents and vertical AI products that provides access to 22,000+ authorized SaaS tools across 400+ integrations and 24 categories directly inside LLMs (Claude, GPT, Gemini, Cohere). Tools operate only on explicitly authorized customer connections, enabling agents to safely read and write against live third-party systems.