Skip to main content
Glama
Horizon MCP Server

Horizon MCP Server

Horizon MCP Server

MCP (Model Context Protocol) server for Omnissa Horizon VDI management. Exposes the Horizon REST API as MCP tools covering inventory, monitoring, configuration, entitlements, Active Directory, and help desk functions. Verified against the Horizon Server REST API spec for versions 2512 through 2606 — call get_api_coverage for the full list of supported tools and known gaps.

Quickstart

The fastest path to a working setup, using Claude Code with stdio transport:

  1. Clone and install:

    git clone https://github.com/matt-coppinger/horizon-mcp.git
    cd horizon-mcp
    uv sync
  2. Register the server with Claude Code (see Configuration below for what each variable means):

    claude mcp add horizon \
      -e HORIZON_BASE_URL=https://horizon.corp.example.com \
      -- uv run --project /absolute/path/to/horizon-mcp horizon-mcp

    Use the absolute path to where you cloned the repo. Omit HORIZON_ACCESS_TOKEN for now — you'll get one in the next step.

  3. Restart Claude Code, then get a token by asking it to call horizon_login (see Getting an Access Token) with your AD credentials.

  4. Verify it works — ask Claude Code to call list_desktop_pools or get_infrastructure_health. If you get real data back, you're set. The server keeps the tokens itself and renews the access token automatically when it expires, so you only log in again after the server restarts (or the refresh token expires). To persist the session across restarts, see Getting an Access Token.

Running the server standalone over HTTP instead (for remote/multi-user access, or in Docker)? See HTTP (remote) and Docker.

Related MCP server: vSphere-MCP-Pro

Requirements

  • Python 3.11+

  • uv (recommended) or pip

  • Horizon Connection Server 2512 or later

Installation

git clone https://github.com/matt-coppinger/horizon-mcp.git
cd horizon-mcp
uv sync

Configuration

The server reads configuration from environment variables:

Variable

Required

Description

HORIZON_BASE_URL

Yes

Connection Server URL, e.g. https://horizon.corp.example.com

HORIZON_ACCESS_TOKEN

Yes*

Bearer token — obtain via horizon_login tool

HORIZON_REFRESH_TOKEN

No

Refresh token the server uses to renew an expired access token automatically. Set it to persist a session across restarts (with it, HORIZON_ACCESS_TOKEN can be omitted)

HORIZON_EXPOSE_TOKENS

No

Set to true to make horizon_login / horizon_refresh_token return the full tokens (default: 8-character hints only), for copying into config

HORIZON_AUDIT_LOG

No

File to append the JSON-lines audit log to (default: stderr). See Audit log

HORIZON_VERIFY_SSL

No

Set to false to skip TLS cert verification (lab use only)

HORIZON_CONFIRMATION

No

elicit (default): destructive tools ask the user to confirm in the MCP client, and are refused if the client can't show the prompt. flag: fall back to a confirm=True argument for clients without elicitation. See Confirming destructive operations

HORIZON_MAX_BULK_DESTRUCTIVE

No

Most machines machine_action will rebuild, reset or archive in one call (default 20)

HORIZON_MAX_MACHINE_COUNT

No

Largest machine / RDS server count create_desktop_pool / create_rdsh_farm will accept (default 500)

MCP_TRANSPORT

No

stdio (default), streamable-http, or sse

MCP_HOST

No

Bind host for HTTP transport (default 127.0.0.1; the Docker image sets 0.0.0.0)

MCP_PORT

No

Port for HTTP transport (default 8000)

MCP_API_KEY

HTTP only

Required for HTTP transport — clients must send Authorization: Bearer <value>. The server refuses to start without it

MCP_ALLOW_UNAUTHENTICATED

No

Set to true to run HTTP transport without MCP_API_KEY (not recommended)

MCP_ALLOWED_HOSTS

No

Comma-separated host names the HTTP server answers to (Host header check). Defaults to loopback names when bound to loopback; unchecked otherwise

MCP_ALLOWED_ORIGINS

No

Comma-separated browser origins allowed to call the HTTP server, e.g. https://app.example.com. Loopback origins are allowed when bound to loopback

*HORIZON_ACCESS_TOKEN can also be obtained at runtime by calling the horizon_login tool, or from HORIZON_REFRESH_TOKEN.

Usage

stdio (Claude Desktop / Claude Code)

Add to your MCP client configuration:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "horizon": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/HorizonMCP", "horizon-mcp"],
      "env": {
        "HORIZON_BASE_URL": "https://horizon.corp.example.com",
        "HORIZON_ACCESS_TOKEN": "your-access-token-here"
      }
    }
  }
}

Claude Code — register it with claude mcp add (add --scope project to write a shareable .mcp.json instead):

claude mcp add horizon \
  -e HORIZON_BASE_URL=https://horizon.corp.example.com \
  -e HORIZON_ACCESS_TOKEN=your-access-token-here \
  -- uv run --project /path/to/HorizonMCP horizon-mcp

HTTP (remote)

HTTP transport requires MCP_API_KEY — clients authenticate with Authorization: Bearer <MCP_API_KEY>, and the server refuses to start without it (set MCP_ALLOW_UNAUTHENTICATED=true to override, not recommended). It binds to 127.0.0.1 by default; set MCP_HOST=0.0.0.0 to accept connections from other machines.

MCP_TRANSPORT=streamable-http \
MCP_PORT=8000 \
MCP_API_KEY=your-secret-key \
HORIZON_BASE_URL=https://horizon.corp.example.com \
HORIZON_ACCESS_TOKEN=your-token \
horizon-mcp

The server exposes a single endpoint at http://host:8000/mcp.

Clients pass the key as a header. For Claude Code:

claude mcp add --transport http horizon http://your-server:8000/mcp \
  --header "Authorization: Bearer your-secret-key"

stdio transport always skips authentication regardless of MCP_API_KEY.

The HTTP server also checks Host and Origin headers to block DNS-rebinding attacks from web pages. When bound to loopback it only answers to localhost/127.0.0.1/::1; behind a reverse proxy or on a named host, list your host names in MCP_ALLOWED_HOSTS. Browser-based clients from other origins must be listed in MCP_ALLOWED_ORIGINS; non-browser MCP clients send no Origin and are unaffected.

HTTP transport security: For any non-localhost deployment, place the server behind a reverse proxy (nginx, Caddy, Traefik) that enforces TLS. Each user should run a separate server instance with their own HORIZON_ACCESS_TOKEN and MCP_API_KEY to maintain session isolation.

Docker

The provided Dockerfile runs the server with streamable-http transport (Docker containers don't have an interactive stdio channel for an MCP client to attach to, so HTTP is the practical option here).

docker build -t horizon-mcp .
docker run -d -p 8000:8000 \
  -e HORIZON_BASE_URL=https://horizon.corp.example.com \
  -e HORIZON_ACCESS_TOKEN=your-token \
  -e MCP_API_KEY=your-secret-key \
  horizon-mcp

Or with docker-compose.yml (reads HORIZON_BASE_URL, HORIZON_ACCESS_TOKEN, HORIZON_REFRESH_TOKEN, HORIZON_VERIFY_SSL, and MCP_API_KEY from your shell environment or a .env file):

HORIZON_BASE_URL=https://horizon.corp.example.com MCP_API_KEY=your-secret-key docker compose up -d

MCP_API_KEY is required — both docker-compose.yml and the server itself refuse to start without it, because a containerized deployment is reachable over the network by definition, so leaving the endpoint unauthenticated is not a safe default (see Security Notes). Point your MCP client at http://host:8000/mcp with the matching Authorization: Bearer header as shown above.

Getting an Access Token

If you don't have a token yet, omit HORIZON_ACCESS_TOKEN from the config and call horizon_login as the first tool:

Call horizon_login with:
  username: jsmith
  password: ******   ← treated as a secret, masked in server logs
  domain: CORP
  base_url: https://horizon.corp.example.com

The new session is active immediately. The server keeps the access and refresh tokens itself — the tool returns only their first 8 characters (access_token_hint, refresh_token_hint), so the tokens never enter the conversation.

When the access token expires (~8 hours) and Horizon answers a request with HTTP 401, the server refreshes it with the stored refresh token and retries the request once. If there's no refresh token, or Horizon rejects it, the tool call fails with a message asking you to call horizon_login again. horizon_refresh_token and horizon_logout use the stored refresh token when you don't pass one.

Persisting the session across restarts: tokens held in the server are lost when it restarts. To keep a session, set HORIZON_EXPOSE_TOKENS=true on the server, call horizon_login once — it then returns the full access_token and refresh_token — and put them in your MCP client config as HORIZON_ACCESS_TOKEN and HORIZON_REFRESH_TOKEN (the refresh token alone is enough; the server gets an access token from it on the first call). Then unset HORIZON_EXPOSE_TOKENS.

Security: Treat both tokens as passwords. If you expose them, clear them from the conversation after copying them to your config. Do not commit tokens to version control.

Available Tools

⚠️ = asks you to confirm before running — see Confirming destructive operations.

Auth

Tool

Description

horizon_login

Authenticate with AD credentials (password masked in logs); the server keeps the tokens and returns hints

horizon_refresh_token

Renew the access token now (the server also does this automatically on expiry)

horizon_logout

Invalidate current session

Inventory

Tool

Description

list_desktop_pools

List all VDI and RDS desktop pools (paginated)

get_desktop_pool

Get pool details

create_desktop_pool

Create a new desktop pool (VDI or RDS, automated or manual)

update_desktop_pool

Update an existing desktop pool's configuration

delete_desktop_pool

Delete a desktop pool and all its machines ⚠️

desktop_pool_action

Enable/disable a pool, or enable/disable-provisioning (⚠️ when disabling)

list_machines

List virtual desktops (filterable by pool, state; paginated)

get_machine

Get machine details

machine_action

Shutdown, restart, reset, rebuild, archive ⚠️; recover, enter/exit maintenance

assign_machine_users

Assign or unassign users to a dedicated (non-floating) desktop

list_rdsh_farms

List RDS farms (paginated)

get_rdsh_farm

Get farm details

create_rdsh_farm

Create a new RDS farm (automated or manual)

update_rdsh_farm

Update an existing RDS farm's configuration

delete_rdsh_farm

Delete an RDS farm and all its servers ⚠️

rdsh_farm_action

Enable or disable one or more RDS farms (⚠️ when disabling)

list_application_pools

List published application pools (paginated)

get_application_pool

Get application pool details

create_application_pool

Publish a new application pool from an RDS farm

update_application_pool

Update an existing application pool's configuration

delete_application_pool

Unpublish an application pool ⚠️

list_sessions

List active user sessions (paginated)

get_session

Get session details

disconnect_sessions

Disconnect sessions (keep running) ⚠️

logoff_sessions

Log off sessions (terminates apps) ⚠️

reset_or_restart_sessions

Hard-reset or gracefully restart the VMs backing sessions ⚠️

send_message_to_sessions

Send pop-up notification to sessions

Monitor

Tool

Description

get_infrastructure_health

Health across all components in one parallel call (summary, connection servers, gateways, vCenters, AD domains, farms)

get_metrics

Capacity metrics in one parallel call (pools, sessions, machines, system, RDS servers, license)

get_connection_server_health

Detailed health for a specific Connection Server

Config

Tool

Description

list_connection_servers

List connection servers

get_connection_server

Get connection server config

list_virtual_centers

List configured vCenters

get_environment_properties

Environment version and features

get_settings

Global Horizon settings

update_settings

Change a settings section: general, security, client, feature or agent-restriction ⚠️

get_global_policies

USB, clipboard, multimedia policies

update_global_policies

Change global policies ⚠️ (the prompt lists each field being changed)

list_licenses

License list and status

get_event_database

Event DB config

list_ic_domain_accounts

Instant clone domain accounts

list_image_management

Image management streams, versions, or tags (pass resource: streams|versions|tags; versions and tags also need stream_id from streams)

list_gateways

Registered UAGs

trigger_connection_server_backup

Trigger Connection Server backup

Entitlements

Tool

Description

list_pool_entitlements

All entitlements for desktop or application pools

get_pool_entitlement

Users/groups for a specific pool

set_pool_entitlements

Add, replace ⚠️, or remove ⚠️ entitlements (desktop or application) — replace is desktop-pool only, the Horizon API has no bulk-replace endpoint for application pools

External / Active Directory

Tool

Description

search_ad_users_or_groups

Find AD users and groups (paginated)

get_ad_user_or_group

Get AD entity details

list_ad_domains

List configured AD domains

list_ad_containers

AD containers (OUs) in a domain — rdn → ad_container_rdn for provisioning

get_domain_netbios_map

NETBIOS → DNS domain name map

list_audit_events

Administrative audit log (paginated)

list_base_vms

VMs available for pool base images

list_base_vm_snapshots

Snapshots of a base VM (snapshot_id for instant clone pools)

list_datastores

Datastores for provisioning (requires vcenter_id + host_or_cluster_id)

list_vm_folders

VM folders in vCenter

list_datacenters

Datacenters in a vCenter Server

list_hosts_or_clusters

Hosts and clusters in a datacenter

list_resource_pools

Resource pools on a host or cluster

list_network_labels

Network port groups on a host or cluster

list_network_interface_cards

NICs on a base VM or VM template (requires base_vm_id or vm_template_id; id → network_interface_card_id in nics)

list_vm_templates

VM templates for full/linked-clone pools

list_datastore_clusters

Storage DRS datastore clusters (requires vcenter_id + host_or_cluster_id)

list_customization_specifications

Sysprep/QuickPrep specs for OS customization during provisioning

Discovery

Tool

Description

get_api_coverage

Lists all tools, resources, and unsupported operations — call this to understand what can be managed via this server

Resources (read-only)

MCP Resources expose read-only Horizon data without consuming tool slots. Access them via horizon://<path> using your MCP client's resource protocol.

Config resources (horizon://config/...):

URI

Description

horizon://config/roles

RBAC roles and their privileges

horizon://config/permissions

Role-to-principal permission assignments

horizon://config/privileges

All selectable admin privileges

horizon://config/local-access-groups

Local access groups for admin delegation

horizon://config/federation-access-groups

CPA federation access groups

horizon://config/saml-authenticators

SAML 2.0 authenticator configurations

horizon://config/radius-authenticators

RADIUS authenticator configurations

horizon://config/gssapi-authenticators

GSSAPI/Kerberos authenticator configurations

horizon://config/jwt-authenticators

JWT authenticator configurations

horizon://config/app-volumes-managers

App Volumes Managers registered with Horizon

horizon://config/uem-servers

User Environment Manager servers

horizon://config/true-sso

TrueSSO connector configurations

horizon://config/true-sso-enrollment-servers

TrueSSO enrollment servers

horizon://config/compute-profiles

Compute profiles for provisioning

horizon://config/customization-specifications

Sysprep/QuickPrep specs (config view)

horizon://config/settings/general

General settings

horizon://config/settings/security

Security settings

horizon://config/settings/client

Client feature settings

horizon://config/settings/feature

Feature toggle settings

horizon://config/settings/agent-restriction

Allowed agent versions/types

horizon://config/syslog

Syslog configuration

horizon://config/ceip

CEIP enrollment status

horizon://config/url-redirection

URL content redirection rules

horizon://config/pre-logon-settings

Pre-logon banner/message settings

horizon://config/log-collector/log-levels

Component log levels

horizon://config/log-collector/tasks

Log collection tasks

horizon://config/gateway-access-users-or-groups

Users and groups with gateway access

horizon://config/unauthenticated-access-users

Users configured for unauthenticated (kiosk) access

horizon://config/users-or-groups-global-summary

Global summary of admin users and groups across pods

horizon://config/external-deployments

External deployments (e.g. Horizon Cloud links) registered with this pod

horizon://config/secondary-credentials

Secondary credentials configured for connection servers

horizon://config/message-clients

Message security mode clients registered with Horizon

horizon://config/rcx-servers

RCX (Remote Console) servers registered with Horizon

Monitor resources (horizon://monitor/...):

URI

Description

horizon://monitor/app-volumes-managers

App Volumes Manager health

horizon://monitor/event-database

Event database status

horizon://monitor/rds-servers

RDS server health and session load

horizon://monitor/saml-authenticators

SAML authenticator health

horizon://monitor/true-sso

TrueSSO health and certificate status

horizon://monitor/datastores/usage-metrics

Datastore usage per pool/farm

horizon://monitor/pods

Remote pod health (CPA)

horizon://monitor/pods/global-session-metrics

Aggregate session counts across pods

horizon://monitor/message-clients

Message client health

Help Desk

Tool

Description

diagnose_session

All session diagnostics in one parallel call: logon timing, display performance, historical performance, processes, remote applications

get_remote_assistance_ticket

MSRA ticket for remote support

end_remote_application

Force-close a published app in a session ⚠️

Horizon Filter Syntax

Most list tools accept a filter parameter using Horizon's JSON filter format:

// Equals
{"type": "Equals", "name": "state", "value": "AVAILABLE"}

// Contains (string)
{"type": "Contains", "name": "name", "value": "win11"}

// AND combination
{
  "type": "And",
  "filters": [
    {"type": "Equals", "name": "desktop_pool_id", "value": "pool-id"},
    {"type": "Equals", "name": "state", "value": "CONNECTED"}
  ]
}

Paginated List Results

Tools marked (paginated) in the tables above (list_desktop_pools, list_machines, list_rdsh_farms, list_application_pools, list_sessions, search_ad_users_or_groups, list_audit_events) take page (1-based) and size, and return an envelope rather than a bare list:

{
  "items": [ ... ],
  "count": 100,
  "page": 1,
  "size": 100,
  "pages_fetched": 1,
  "has_more": true,
  "next_page": 2,
  "truncated": false
}
  • has_more / next_page — call the tool again with page=next_page to continue. The Horizon REST API returns a bare array with no "more records" indicator, so has_more is inferred: it is true whenever a full page (size items) came back. When the total is an exact multiple of size, the next page simply comes back empty.

  • fetch_all=true — fetches successive pages starting at page, stopping at the first short page or after 10 pages / 5,000 items, whichever comes first. If it stops at the cap with more possibly remaining, truncated is true and next_page says where to resume. Prefer a filter when you only need a subset.

Creating Pools and Farms

create_desktop_pool and create_rdsh_farm accept a spec dict that maps directly to the Horizon REST API request body.

The nesting is not what the field names suggest. vcenter_id is top-level, not inside provisioning_settings. Datastores live under a separate top-level storage_settings block. AD/domain-join settings live under a separate top-level customization_settings block. Naming and machine count live under a separate top-level pattern_naming_settings block, and the count field is max_number_of_machines, not max_machine_count. The example below is verified against a live Horizon 2606 server (a real pool was created with this exact shape) — an earlier version of this doc had the wrong nesting throughout and would have produced a 400 on every field.

Automated Instant Clone desktop pool (minimum working example):

{
  "name": "MyPool",
  "display_name": "My Pool",
  "type": "AUTOMATED",
  "source": "INSTANT_CLONE",
  "user_assignment": "FLOATING",
  "naming_method": "PATTERN",
  "access_group_id": "<id from the horizon://config/local-access-groups resource>",
  "vcenter_id": "<id from list_virtual_centers>",
  "provisioning_settings": {
    "parent_vm_id": "<id from list_base_vms>",
    "base_snapshot_id": "<id from list_base_vm_snapshots>",
    "datacenter_id": "<id from list_datacenters>",
    "vm_folder_id": "<id from list_vm_folders>",
    "host_or_cluster_id": "<id from list_hosts_or_clusters>",
    "resource_pool_id": "<id from list_resource_pools>"
  },
  "storage_settings": {
    "datastores": [{"datastore_id": "<id from list_datastores>"}]
  },
  "customization_settings": {
    "customization_type": "CLONE_PREP",
    "ad_container_rdn": "<rdn from list_ad_containers>",
    "instant_clone_domain_account_id": "<id from list_ic_domain_accounts>"
  },
  "pattern_naming_settings": {
    "naming_pattern": "MyPool-{n:fixed=2}",
    "max_number_of_machines": 10
  }
}

nics is optional and top-level ([{"network_interface_card_id": "...", "network_label_assignment_specs": [...]}]) — if omitted, new machines simply inherit the parent image's existing network settings, which is fine for most cases.

create_rdsh_farm requires access_group_id directly, and nests everything else one level deeper, under a top-level automated_farm_settings object: automated_farm_settings.vcenter_id, .provisioning_settings, .storage_settings, .customization_settings, .pattern_naming_settings (with max_number_of_rds_servers instead of max_number_of_machines), plus a required max_session_type (LIMITED | UNLIMITED — max_sessions is required when LIMITED). This shape is verified live against a real Horizon 2606 server.

Resource ID lookup chain — follow this sequence to resolve all IDs before calling create_desktop_pool or create_rdsh_farm:

list_virtual_centers
  ├─ list_customization_specifications(vcenter_id)   ← Sysprep spec ID (SYS_PREP only)
  ├─ list_vm_templates(vcenter_id)                   ← template_id (full/linked-clone pools)
  │    └─ list_network_interface_cards(vcenter_id, vm_template_id=...)  ← optional, nics
  └─ list_datacenters(vcenter_id)
       ├─ list_vm_folders(vcenter_id, datacenter_id)
       └─ list_hosts_or_clusters(vcenter_id, datacenter_id)
            ├─ list_datastores(vcenter_id, host_or_cluster_id)
            ├─ list_datastore_clusters(vcenter_id, host_or_cluster_id)
            ├─ list_resource_pools(vcenter_id, host_or_cluster_id)
            └─ list_network_labels(vcenter_id, host_or_cluster_id)  ← optional, nics
list_base_vms(vcenter_id)                            ← parent_vm_id (instant-clone pools)
  ├─ list_base_vm_snapshots(vcenter_id, base_vm_id)  ← base_snapshot_id
  └─ list_network_interface_cards(vcenter_id, base_vm_id)  ← optional, nics
horizon://config/local-access-groups (resource)      ← access_group_id (always required)
list_ad_domains
  └─ list_ad_containers(domain_id)                   ← ad_container_rdn (instant clone)
list_ic_domain_accounts                              ← instant_clone_domain_account_id (instant clone)

create_application_pool uses explicit parameters instead — pass name, farm_id, executable_path, and optional fields directly.

For updates, retrieve the current config with get_desktop_pool / get_rdsh_farm / get_application_pool, modify the relevant fields, and pass the result to the corresponding update_* tool. get_desktop_pool and get_rdsh_farm return every field their update_* schema needs, and the unchanged get-then-update round trip is verified live against Horizon 2606 for both pools and farms.

Delete operations (delete_desktop_pool, delete_rdsh_farm, delete_application_pool) ask you to confirm in the client, naming the pool or farm. Call get_desktop_pool / get_rdsh_farm and list_sessions first so you know what will be affected.

Confirming destructive operations

Tools marked ⚠️ pause and ask you to confirm before they run, using MCP elicitation: your MCP client shows a prompt describing exactly what will happen (for example "Delete desktop pool Sales (id), all of its machines, and end any active sessions in it") with Proceed and Cancel. The AI model can't answer this prompt for you, so a prompt-injected or mistaken model can't push a destructive operation through on its own — unlike a confirm=True argument, which the model sets itself.

Tool

Asks when

delete_desktop_pool, delete_rdsh_farm, delete_application_pool

Always

machine_action

shutdown, restart, reset, rebuild, archive (not recover or maintenance mode)

logoff_sessions, disconnect_sessions, reset_or_restart_sessions

Always

end_remote_application

Always

desktop_pool_action, rdsh_farm_action

Disabling (not enabling)

set_pool_entitlements

replace or remove (not add)

update_global_policies, update_settings

Always — the prompt lists each field that changes, old → new

If your client doesn't support elicitation, these tools are refused by default. If you can't switch clients, set HORIZON_CONFIRMATION=flag on the server to accept a confirm=True argument instead — be aware the model can set that argument itself, so only do this with a client that asks you to approve each tool call.

These tools, plus the update_* tools and assign_machine_users, also carry destructiveHint=True, so clients that gate tool calls on MCP annotations will prompt before running them.

Audit log

The server writes one JSON line per event to stderr, or appends to the file named by HORIZON_AUDIT_LOG. It never writes to stdout, which stdio transport uses for the MCP protocol. Each line has a UTC timestamp (ts), the event type and the tool that triggered it:

  • confirmation — every confirmation decision: the summary shown to the user and the outcome (approved, cancelled, refused because the client can't prompt, or in flag mode approved / missing_confirm).

  • api_request — every POST, PUT and DELETE sent to Horizon: method, path, and the HTTP status (or the exception type as error), plus retried if the token was refreshed first. GETs aren't logged.

  • auth — login, logout and token refresh (manual or automatic) and their status.

Request bodies, passwords, usernames, tokens and Authorization headers are never logged.

Running Tests

uv sync --all-extras --all-groups
uv run pytest -q          # unit tests
uv run ruff check src     # lint
uv run pyright src        # type check

CI runs all of these on every pull request (tests on Python 3.11–3.13), plus a pip-audit scan of the locked dependencies.

The unit tests are offline. The live integration tests in tests/live/ are collected but skipped unless you point them at a server — see below.

Live integration tests

⚠️ Use a lab, never production. The read-only sweep changes nothing, but the opt-in write tests disable/enable a farm, publish and delete application pools, change entitlements, write settings back, and (with the destructive flag) provision and delete a real RDS farm.

tests/live/ spawns the real server over MCP stdio (the way Claude Desktop / Code run it), logs in through horizon_login, and calls tools exactly as a client would. Destructive tools are confirmed through real MCP elicitation: the test's handler approves a prompt only if it names an ID the test itself created (or HZ_TEST_FARM's ID), or — for the settings round trips — says no fields differ. Everything else is cancelled, and each test asserts that every prompt it saw was expected.

Test

Needs

What it does to the environment

test_read_only.py — one check per read-only tool, chaining IDs from list results into get calls; a check is skipped with a reason when the lab has nothing to feed it (e.g. no active sessions)

the four required vars

Nothing (logs in, reads, logs out)

test_writes.py::test_rdsh_farm_action_and_noop_update

HZ_LIVE_WRITES=1, HZ_TEST_FARM

Disables then re-enables the test farm (or the reverse if it starts disabled), writes its config back unchanged; restores the original enabled state in a finally

test_writes.py::test_application_pool_lifecycle

HZ_LIVE_WRITES=1, HZ_TEST_FARM

Publishes a uniquely named app pool (mcp-live-<random>) on the test farm, renames and restores its display name, deletes it

test_writes.py::test_application_pool_entitlements_add_remove

HZ_LIVE_WRITES=1, HZ_TEST_FARM, HZ_TEST_GROUP

Same kind of throwaway app pool; entitles the group, removes it again, deletes the pool

test_writes.py::test_update_global_policies_noop, test_update_settings_general_noop

HZ_LIVE_WRITES=1

Reads global policies / general settings and writes the identical object back; asserts nothing changed (writes the original back if anything did)

test_destructive.py::test_create_and_delete_rdsh_farm

HZ_LIVE_WRITES=1, HZ_LIVE_DESTRUCTIVE=1, HZ_BASE_VM, HZ_SNAPSHOT

Creates a throwaway 1-server instant-clone farm (mcp-live-<random>), deletes it with delete_rdsh_farm, polls until it's gone. Provisions a real VM — expect this to take many minutes.

Tests only ever modify HZ_TEST_FARM and resources they create themselves, and created resources are always deleted in teardown. If a teardown fails, the test prints MANUAL CLEANUP MAY BE NEEDED with the resource's name and ID.

Environment variables

Variable

Purpose

HZ_BASE_URL, HZ_USERNAME, HZ_DOMAIN, HZ_PASSWORD

Required — without all four, every live test is skipped

HZ_VERIFY_SSL

false for a lab with a self-signed certificate (default true)

HZ_LIVE_WRITES=1

Enable the reversible write tests

HZ_LIVE_DESTRUCTIVE=1

Additionally enable the farm create/delete test

HZ_TEST_FARM

Name of a dedicated test RDS farm the write tests may modify and publish apps from

HZ_TEST_GROUP

AD group (name or SID) to entitle to the test app pool

HZ_TEST_APP_PATH

Executable for the test app pool (default C:\Windows\System32\notepad.exe)

HZ_BASE_VM, HZ_SNAPSHOT

Base VM and snapshot (name or ID) for the throwaway farm. Use the snapshot taken after the Horizon Agent was installed

HZ_VCENTER, HZ_DATACENTER, HZ_CLUSTER, HZ_RESOURCE_POOL, HZ_VM_FOLDER, HZ_DATASTORE, HZ_ACCESS_GROUP, HZ_IC_DOMAIN_ACCOUNT

Optional (name or ID) — otherwise the first one listed is used

HZ_AD_CONTAINER

Optional AD container RDN for the throwaway farm's servers

HZ_LIVE_PROVISION_TIMEOUT

Seconds to wait for each farm provisioning/teardown step (default 1800)

HZ_LIVE_REPORT

Write an HTML report (secrets redacted) to this path, e.g. .live-reports/report.html (ignored by git)

HZ_LIVE_SERVER_LOG

Where to write the server's stderr (default: a temp file, printed at the end of the run)

Running

# Read-only sweep
export HZ_BASE_URL=https://<connection-server> HZ_USERNAME=<user> HZ_DOMAIN=<domain> HZ_VERIFY_SSL=false
read -rs HZ_PASSWORD && export HZ_PASSWORD
uv run pytest tests/live -v -rs

# Plus reversible writes, with an HTML report
HZ_LIVE_WRITES=1 HZ_TEST_FARM=<test-farm> HZ_TEST_GROUP=<ad-group> \
  HZ_LIVE_REPORT=.live-reports/report.html uv run pytest tests/live -v -rs

# Plus the farm create/delete test (slow — provisions a VM)
HZ_LIVE_WRITES=1 HZ_LIVE_DESTRUCTIVE=1 HZ_BASE_VM=<base-vm> HZ_SNAPSHOT=<agent-snapshot> \
  uv run pytest tests/live/test_destructive.py -v -s

Add -s to watch each tool call and confirmation prompt as it happens. -m "not live" deselects the suite entirely.

End-to-end lifecycle test

⚠️ Lab only, never production. This test provisions VMs, deletes pools and farms, restarts machines, changes entitlements and (optionally) logs off a real user session.

tests/live/test_lifecycle.py exercises every tool the server registers against resources it creates itself, then deletes them. One command does the whole run:

  1. Read-only sweep — the test_read_only.py checks, in their own server process.

  2. Auth & discovery — horizon_login (checks only token hints come back), get_api_coverage, the vCenter/AD lookups for placement, HZ_TEST_GROUP and HZ_TEST_USER.

  3. Cleanup — deletes leftovers from earlier runs: application pools first, then desktop pools and farms, polling until each is gone.

  4. Provision — a desktop pool, an RDS farm and an application pool (see footprint below), waiting for the machine and the RDS server to be AVAILABLE and failing fast on a provisioning error.

  5. Reads of the new items, then desktop pool updates (rename + restore; disable/enable; disable/enable provisioning), entitlements (desktop add → replace → remove, application add → remove, each verified), machine admin (assign/unassign HZ_TEST_USER, maintenance mode), farm & app pool (no-op farm update, disable/enable, app rename + restore) and config (no-op global policies and general settings round trips, one Connection Server backup).

  6. User sessions (optional, below), then machine power actions: restart, reset, recover, rebuild, archive, shutdown — each waits for AVAILABLE first. recover / rebuild / archive may not apply to an instant clone; a clean Horizon rejection is recorded as NA with its error, not a failure.

  7. Teardown (always, in a finally) — deletes the app pool, desktop pool and farm, polls until they're gone, and prints MANUAL CLEANUP MAY BE NEEDED: … if anything is left.

  8. Refresh & logout — horizon_refresh_token, a call with the new token, horizon_logout, and a check that calls are refused afterwards.

Footprint: instant clones only — one AUTOMATED / INSTANT_CLONE / DEDICATED desktop pool with a single machine provisioned up front, one AUTOMATED farm with a single RDS server, and one application pool (HZ_TEST_APP_PATH) on that farm.

Cleanup is prefix-only. Everything the run creates is named <prefix>vdi-<tag>, <prefix>farm-<tag> and <prefix>app-<tag> (HZ_E2E_PREFIX, default mcp-e2e-; the test refuses a prefix shorter than 5 characters or with anything but letters, digits, - and _). The cleanup phase deletes only application pools, desktop pools and farms whose name starts with that prefix, and nothing else. The confirmation handler approves only prompts that name the ID of such an item, or of a machine or session inside one (plus the settings no-op round trips, which say that nothing changes); everything else is cancelled and fails the test.

Coverage: at the end every registered tool gets a verdict — PASS, FAIL, SKIP (with a reason), NA (Horizon cleanly rejected an action that doesn't apply), or KNOWN (a documented quirk, e.g. update_settings general rejecting its own restricted_client_data). The test fails if any tool failed or was neither called nor skipped with a reason, if a prompt was unexpected, or if anything was left behind. The table is printed at the end and is the first section of the HTML report (HZ_LIVE_REPORT). The lab may have no event database (list_audit_events → SKIP) or no image streams (versions/tags → SKIP).

User sessions. REST can't start a session, so with HZ_E2E_WAIT_FOR_SESSION=1 the test entitles HZ_TEST_USER to the pool and the app, prints which ones to open, and waits (HZ_E2E_SESSION_TIMEOUT, default 900s) for the sessions to appear. Open both the desktop and the app: the desktop session gets get_session, diagnose_session, get_remote_assistance_ticket (redacted), send_message_to_sessions, disconnect_sessions and reset_or_restart_sessions (restart); the app session gets end_remote_application (on an app found by diagnose_session) and logoff_sessions. With one session, reset_or_restart_sessions is skipped with a reason. Without the flag, the session tools are skipped with the reason "needs a real user session".

Duration: roughly 20–60 minutes, dominated by instant-clone provisioning (twice: the pool and the farm) and the machine restart/reset waits; add the time you take to connect when waiting for a session.

Variable

Purpose

HZ_LIVE_E2E=1

Required — enables the test (plus the four required HZ_* connection variables)

HZ_POOL_BASE_VM, HZ_POOL_SNAPSHOT

Required — desktop pool base VM and snapshot (name or ID). Use the snapshot taken after the Horizon Agent was installed — the wrong one fails with AGENT_CUSTOMIZATION_FAULT

HZ_FARM_BASE_VM, HZ_FARM_SNAPSHOT

Required — RDS farm base VM and snapshot; falls back to HZ_BASE_VM / HZ_SNAPSHOT when neither is set

HZ_TEST_GROUP

Required — AD group (name or SID) for the entitlement steps

HZ_TEST_USER

Required — AD user (login name, DOMAIN\user, user@domain or SID) to assign, entitle and (optionally) connect as

HZ_E2E_PREFIX

Name prefix for everything created and the only thing cleanup deletes (default mcp-e2e-)

HZ_E2E_WAIT_FOR_SESSION=1

Wait for you to connect as HZ_TEST_USER, then test the session tools

HZ_E2E_SESSION_TIMEOUT

Seconds to wait for a session (default 900)

HZ_E2E_SKIP_BACKUP=1

Don't trigger a Connection Server backup

HZ_E2E_POLL_INTERVAL

Seconds between state polls (default 15)

HZ_LIVE_PROVISION_TIMEOUT

Seconds to wait for each provisioning, power action and delete (default 1800)

HZ_TEST_APP_PATH, HZ_VCENTER, HZ_DATACENTER, HZ_CLUSTER, HZ_RESOURCE_POOL, HZ_VM_FOLDER, HZ_DATASTORE, HZ_ACCESS_GROUP, HZ_IC_DOMAIN_ACCOUNT, HZ_AD_CONTAINER, HZ_LIVE_REPORT

As above (shared by the pool and the farm)

export HZ_BASE_URL=https://<connection-server> HZ_USERNAME=<admin-user> HZ_DOMAIN=<domain> HZ_VERIFY_SSL=false
read -rs HZ_PASSWORD && export HZ_PASSWORD
HZ_LIVE_E2E=1 \
  HZ_POOL_BASE_VM=<desktop-base-vm> HZ_POOL_SNAPSHOT=<desktop-agent-snapshot> \
  HZ_FARM_BASE_VM=<rdsh-base-vm> HZ_FARM_SNAPSHOT=<rdsh-agent-snapshot> \
  HZ_TEST_GROUP=<ad-group> HZ_TEST_USER=<ad-user> \
  HZ_E2E_WAIT_FOR_SESSION=1 HZ_LIVE_REPORT=.live-reports/e2e.html \
  uv run pytest tests/live/test_lifecycle.py -v -rs

The test streams its progress (and the "connect now" instructions) even without -s. To see every phase and tool call without a lab, run the dry run against the offline fake Horizon in tests/live/fake_horizon.py: uv run python -m tests.live.lifecycle --plan (add --no-session to plan without the session step). The same dry run runs in the unit tests (tests/test_lifecycle_plan.py), so a new tool the lifecycle doesn't cover fails CI.

Releases

Versions follow Semantic Versioning and are tagged vX.Y.Z on main. See CHANGELOG.md for what changed in each release, including breaking changes.

Security Notes

  • Store credentials in your MCP client's env block, not in code or config files tracked by git.

  • In production, always keep HORIZON_VERIFY_SSL=true (default).

  • Passwords passed to horizon_login are typed as SecretStr and masked in server-side logs.

  • Access and refresh tokens stay inside the server process: login and refresh return only 8-character hints, and expired tokens are renewed automatically, so tokens don't pass through the conversation. HORIZON_EXPOSE_TOKENS=true returns the full tokens for copying into config — leave it off otherwise, and treat the tokens as passwords.

  • The server holds one Horizon session (from HORIZON_ACCESS_TOKEN / HORIZON_REFRESH_TOKEN or the last horizon_login) shared by every client connected to it. For multiple users, run a separate instance per user with its own tokens and MCP_API_KEY, behind a reverse proxy that enforces TLS.

  • Destructive-operation decisions and every mutating Horizon request are recorded in an audit log (stderr or HORIZON_AUDIT_LOG), without request bodies or secrets.

  • Destructive operations ask the user to confirm in the MCP client and are refused if the client can't prompt — see Confirming destructive operations.

  • HTTP transport requires MCP_API_KEY, binds to 127.0.0.1 by default, and validates Host/Origin headers against DNS rebinding.

  • IDs passed to tools are percent-encoded before being placed in Horizon API paths, so an ID can't redirect a request to a different endpoint.

Available Tools

72 tools
assign_machine_usersA
DestructiveIdempotent

Assign or unassign users to a dedicated desktop machine.

Only applicable to machines in dedicated (non-floating) desktop pools. A machine can only have one assigned user at a time in most pool configurations.

Inputs: action (required), user_ids (required), machine_id (required). Returns: object

create_application_poolC

Publish a new application pool from an RDS farm.

Inputs: name (required), farm_id (required), executable_path (required), version, +5 more. Returns: object

create_desktop_poolA

Create a new desktop pool.

CAUTION: Provisioning an AUTOMATED pool immediately begins creating VMs in vCenter. Always confirm with the user before calling this.

Inputs: spec (required). Returns: object

create_rdsh_farmA

Create a new RDS farm.

CAUTION: Provisioning an AUTOMATED farm immediately begins creating VMs in vCenter. Always confirm with the user before calling this.

Inputs: spec (required). Returns: object

delete_application_poolA
Destructive

Delete a published application pool.

CAUTION: Users will immediately lose access to this application. Always confirm with the user before calling this.

Inputs: pool_id (required), confirm. Returns: object

delete_desktop_poolA
Destructive

Delete a desktop pool and all of its machines.

CAUTION: This is irreversible. All machines in the pool are deleted and any active user sessions are terminated. Always confirm with the user before calling this.

Inputs: pool_id (required), confirm. Returns: object

delete_rdsh_farmA
Destructive

Delete an RDS farm and all of its servers.

CAUTION: This is irreversible. All servers in the farm are deleted and any active user sessions are terminated. Always confirm with the user before calling this.

Inputs: farm_id (required), confirm. Returns: object

desktop_pool_actionA
DestructiveIdempotent

Enable, disable, or toggle provisioning for one or more desktop pools.

enable/disable controls whether new user sessions can be established. enable-provisioning/disable-provisioning controls whether new VMs are provisioned. Disabling provisioning is the correct way to pause scale-out during maintenance.

Inputs: action (required), pool_ids (required), confirm. Returns: object

diagnose_sessionA
Read-only

Retrieve diagnostic information for a user session in a single call.

Fetches any combination of: logon timing breakdown, real-time display protocol metrics, 15-minute historical performance, running processes, and active remote applications. Results are keyed by aspect name; a failed aspect returns {"error": ""} rather than failing the whole call.

The help desk endpoints take the session's internal_session_id, not its id (verified live: passing the id returns "Session with requested id was not found"), so this looks the session up first to get it.

Inputs: session_id (required), aspects. Returns: object

disconnect_sessionsA
Destructive

Disconnect one or more user sessions (sessions remain active, clients are disconnected).

The user's applications keep running. Use logoff_sessions to fully terminate sessions.

Inputs: session_ids (required), confirm. Returns: object

end_remote_applicationA
Destructive

Terminate a specific remote application running in a session.

CAUTION: The application will be force-closed. Unsaved data will be lost. Confirm with the user before calling this.

Inputs: session_id (required), remote_application_id (required), confirm. Returns: object

get_ad_user_or_groupB
Read-only

Get detailed information about a specific AD user or group.

Inputs: ad_id (required). Returns: object

get_api_coverageA
Read-only

List all available Horizon MCP tools, resources, and unsupported operations.

Call this to understand what can be managed via this MCP server before attempting a task, or to accurately inform users which Horizon features are and are not supported.

Returns three sections: tools — all callable tools grouped by function resources — read-only MCP Resources (horizon://) for config and monitor data not_yet_supported — Horizon API operations not yet implemented

Inputs: no named parameters. Returns: object

get_application_poolB
Read-only

Get detailed information about a specific application pool.

Inputs: pool_id (required). Returns: object

get_connection_serverC
Read-only

Get configuration details for a specific Connection Server.

Inputs: server_id (required). Returns: object

get_connection_server_healthB
Read-only

Get detailed health information for a specific Connection Server.

Inputs: server_id (required). Returns: object

get_desktop_poolA
Read-only

Get detailed configuration and status of a specific desktop pool.

Uses the v13 endpoint (not v1) specifically so this response contains every field update_desktop_pool's schema can require — verified live, zero gap. Earlier versions of this tool used v1, whose response is missing most of those fields, making a real get-then-update round trip impossible without guessing at values Horizon never returns.

Inputs: pool_id (required). Returns: object

get_domain_netbios_mapA
Read-only

Get a mapping of domain NETBIOS names to DNS names for all configured domains.

Inputs: no named parameters. Returns: object

get_environment_propertiesA
Read-only

Get environment-level properties including version, FIPS mode, and feature flags.

Inputs: no named parameters. Returns: object

get_event_databaseA
Read-only

Get the configuration and connection status of the Horizon event database.

Inputs: no named parameters. Returns: object

get_global_policiesA
Read-only

Get global VDI policies including USB redirection, multimedia redirection, clipboard settings, and other environment-wide policy settings.

Inputs: no named parameters. Returns: object

get_infrastructure_healthA
Read-only

Get health and status across Horizon infrastructure in a single call.

Components:

  • summary: overall health rollup across all component types

  • connection_servers: per-server reachability, load, and tunnel counts

  • gateways: Unified Access Gateway connectivity status

  • virtual_centers: vCenter Server connectivity and health

  • ad_domains: Active Directory domain reachability and bind status

  • farms: RDS farm health and server capacity

Results are keyed by component name. A failed component returns its error as a string rather than failing the whole call.

Inputs: components. Returns: object

get_machineC
Read-only

Get detailed information about a specific machine.

Inputs: machine_id (required). Returns: object

get_metricsA
Read-only

Get performance and capacity metrics across the Horizon environment in a single call.

Scopes:

  • pools: session and machine counts per desktop pool

  • sessions: aggregate connected/disconnected/pending session totals

  • machines: aggregate machine state counts across all pools

  • system: CPU and memory metrics for connection servers

  • rds_servers: RDS server state counts across all farms

  • license: current and peak license usage

Results are keyed by scope name. A failed scope returns its error as a string rather than failing the whole call.

Inputs: scope. Returns: object

get_pool_entitlementB
Read-only

Get the users and groups entitled to access a specific pool.

Inputs: pool_id (required), pool_type (required). Returns: object

get_rdsh_farmB
Read-only

Get detailed information about a specific RDS farm.

Uses the v10 endpoint (not v1) so this response contains every field update_rdsh_farm's schema can require — verified live, zero gap (mirrors the same fix applied to get_desktop_pool).

Inputs: farm_id (required). Returns: object

get_remote_assistance_ticketA
Read-only

Generate a Microsoft Remote Assistance ticket for a user session.

Returns an MSRA connection ticket that allows a help desk technician to view and control the user's desktop session.

Inputs: session_id (required). Returns: object

get_sessionB
Read-only

Get detailed information about a specific user session.

Inputs: session_id (required). Returns: object

get_settingsA
Read-only

Get the global Horizon configuration settings.

Includes client session timeouts, pre-launch settings, display protocol defaults, HTML Access settings, and other global options.

Inputs: no named parameters. Returns: object

horizon_loginA

Authenticate to Horizon and activate the session for this server.

The tokens are kept server-side: subsequent tool calls work immediately, and when the access token expires (~8 hours) the server renews it automatically with the refresh token. Only short token hints are returned.

Inputs: domain (required), password (required), username (required), base_url. Returns: object

horizon_logoutB

Invalidate the current Horizon session (access + refresh tokens).

Inputs: base_url, refresh_token. Returns: object

horizon_refresh_tokenA

Exchange the refresh token for a new access token.

Rarely needed: the server already refreshes an expired access token automatically.

Inputs: base_url, refresh_token. Returns: object

list_ad_containersA
Read-only

List AD containers (OUs) available in a domain for pool provisioning.

The rdn (relative distinguished name) from these results is used as ad_container_rdn in create_desktop_pool's customization_settings (or create_rdsh_farm's automated_farm_settings.customization_settings) to control which OU newly provisioned computers are placed in — NOT provisioning_settings. This is the OU picker equivalent of what the Horizon Console shows during pool creation.

Inputs: domain_id (required). Returns: result

list_ad_domainsA
Read-only

List all Active Directory domains configured in the Horizon environment.

Returns domain details including trust relationships, status, and bind accounts.

Inputs: no named parameters. Returns: result

list_application_poolsA
Read-only

List published application pools in the environment.

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, fetch_all. Returns: object

list_audit_eventsA
Read-only

List Horizon audit events (administrative actions and system events).

Useful for reviewing recent changes, troubleshooting, and compliance auditing.

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, fetch_all. Returns: object

list_base_vmsA
Read-only

List VMs in vCenter that can be used as base images for instant clone pools/farms.

Inputs: vcenter_id (required), datacenter_id. Returns: result

list_base_vm_snapshotsA
Read-only

List snapshots of a base VM that can be used as the image for an instant clone pool or farm.

The result's id is used as base_snapshot_id in create_desktop_pool's or create_rdsh_farm's provisioning_settings when source is INSTANT_CLONE.

CAUTION: don't just pick the first or most recent result. The chosen snapshot must have been taken AFTER the Horizon Agent (with Instant Clone support) was installed and configured on the VM — a snapshot from before that point will provision machines that fail customization (observed live: Horizon reports "AGENT_CUSTOMIZATION_FAULT ... IC Agent missing"). If multiple snapshots exist, check their names/descriptions for one indicating the agent is installed (e.g. containing "agent") rather than an earlier generic checkpoint (e.g. "clean"). When in doubt, ask the user which snapshot to use.

Inputs: base_vm_id (required), vcenter_id (required). Returns: result

list_connection_serversB
Read-only

List all Horizon Connection Servers in the pod.

Inputs: no named parameters. Returns: result

list_customization_specificationsA
Read-only

List vCenter customization specifications (Sysprep/QuickPrep) available for pool provisioning.

The customization_specification_id from these results is used in create_desktop_pool and create_rdsh_farm provisioning_settings to apply OS customization (hostname, domain join, license key) to provisioned VMs.

Inputs: vcenter_id (required). Returns: result

list_datacentersA
Read-only

List datacenters in a vCenter Server.

The datacenter ID is required by list_vm_folders, list_hosts_or_clusters, and create_desktop_pool / create_rdsh_farm provisioning_settings.

Inputs: vcenter_id (required). Returns: result

list_datastore_clustersA
Read-only

List datastore clusters (Storage DRS pods) available on a host or cluster.

Use the datastore_cluster_id in create_desktop_pool or create_rdsh_farm provisioning_settings when using Storage DRS for automated datastore placement.

Inputs: vcenter_id (required), host_or_cluster_id (required). Returns: result

list_datastoresA
Read-only

List datastores available in vCenter for desktop pool or farm provisioning.

Inputs: vcenter_id (required), host_or_cluster_id (required). Returns: result

list_desktop_poolsA
Read-only

List all desktop pools (VDI and RDS) in the Horizon environment.

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, fetch_all. Returns: object

list_gatewaysA
Read-only

List all registered Unified Access Gateways.

Inputs: no named parameters. Returns: result

list_hosts_or_clustersA
Read-only

List hosts and clusters in a vCenter datacenter.

The host_or_cluster_id is required by list_datastores, list_resource_pools, list_network_labels, and create_desktop_pool / create_rdsh_farm provisioning_settings.

Inputs: vcenter_id (required), datacenter_id (required). Returns: result

list_ic_domain_accountsA
Read-only

List instant clone domain accounts used for provisioning instant clone desktops.

Inputs: no named parameters. Returns: result

list_image_managementA
Read-only

List image management streams, versions, or tags.

Versions and tags belong to a stream, so Horizon requires a stream ID for them (verified live — omitting it returns 400 "im_stream_id parameter is missing"). List streams first, then pass a stream's id as stream_id.

Inputs: resource (required), stream_id. Returns: result

list_licensesA
Read-only

List all Horizon licenses and their status, mode, and expiry information.

Inputs: no named parameters. Returns: result

list_machinesA
Read-only

List machines (virtual desktops) in the environment.

To filter by pool, use: filter={"type":"Equals","name":"desktop_pool_id","value":""} To filter by state, use: filter={"type":"Equals","name":"state","value":"AVAILABLE"}

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, sort_by, +2 more. Returns: object

list_network_interface_cardsA
Read-only

List the network interface cards (NICs) on a base VM or VM template.

Horizon requires either base_vm_id (instant-clone pools/farms, optionally with base_snapshot_id) or vm_template_id (full-clone pools) — verified live, omitting both returns 400.

Each result's id is the network_interface_card_id in the top-level nics array of create_desktop_pool / create_rdsh_farm: "nics": [{"network_interface_card_id": "", "network_label_assignment_specs": [...]}]

Inputs: vcenter_id (required), base_vm_id, vm_template_id, base_snapshot_id. Returns: result

list_network_labelsA
Read-only

List network labels (port groups / distributed port groups) available on a host or cluster.

Network label IDs are used in the nics array of create_desktop_pool and create_rdsh_farm provisioning_settings: "nics": [{"nic_id": "", "network_label_id": ""}]

Inputs: vcenter_id (required), host_or_cluster_id (required). Returns: result

list_pool_entitlementsA
Read-only

List entitlements for all pools of the given type.

Returns which users and groups are entitled to each pool. Use get_pool_entitlement for a specific pool's details.

Inputs: pool_type (required). Returns: result

list_rdsh_farmsA
Read-only

List all RDS (Remote Desktop Session Host) farms in the environment.

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, fetch_all. Returns: object

list_resource_poolsA
Read-only

List resource pools on a host or cluster.

The resource_pool_id is required by create_desktop_pool and create_rdsh_farm provisioning_settings.

Inputs: vcenter_id (required), host_or_cluster_id (required). Returns: result

list_sessionsA
Read-only

List active user sessions in the environment.

Common filter fields: user_name, desktop_pool_id, machine_name, client_name, state. Session states: CONNECTED, DISCONNECTED, PENDING.

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, sort_by, +2 more. Returns: object

list_virtual_centersA
Read-only

List all vCenter Servers configured in the Horizon environment.

Inputs: no named parameters. Returns: result

list_vm_foldersA
Read-only

List VM folders in a vCenter datacenter for use in pool/farm configuration.

Inputs: vcenter_id (required), datacenter_id (required). Returns: result

list_vm_templatesA
Read-only

List VM templates available in vCenter for use as pool base images.

Templates are used for full-clone or linked-clone desktop pools (source=FULL_CLONE or LINKED_CLONE). Use the template_id in create_desktop_pool provisioning_settings instead of parent_vm_id.

Inputs: vcenter_id (required), datacenter_id. Returns: result

logoff_sessionsA
Destructive

Log off one or more user sessions, terminating their running applications.

CAUTION: This will close all running applications in the session. Unsaved data will be lost. Always confirm with the user before calling this.

Inputs: session_ids (required), forced, confirm. Returns: object

machine_actionA
Destructive

Perform a bulk action on one or more machines.

Actions:

  • shutdown: gracefully power off (use force=true to override active sessions)

  • restart: reboot the machine (use force=true to override active sessions)

  • reset: hard reset (power cycle) — may cause data loss

  • rebuild: re-provision the machine from the pool's image

  • recover: recover a machine stuck in an error state

  • enter_maintenance: put machine into maintenance mode (prevents new sessions)

  • exit_maintenance: take machine out of maintenance mode

  • archive: initiate machine archival

CAUTION: rebuild and reset are destructive and will discard unsaved user data. Always confirm with the user before calling these actions.

Inputs: action (required), machine_ids (required), force, confirm. Returns: object

rdsh_farm_actionA
DestructiveIdempotent

Enable or disable one or more RDS farms.

Disabling a farm prevents new sessions from being routed to it without terminating existing sessions — useful for draining a farm before maintenance.

Unlike desktop pools, farms have no bulk enable/disable endpoint, and Horizon's farm update schema requires several fields beyond "enabled" (verified live — a naive partial-body PUT gets rejected). So this fetches each farm's full current state first, changes only "enabled", and PUTs the complete spec back — a real get-then- update round trip, not a guess. Reports per-farm results if any still fail.

Inputs: action (required), farm_ids (required), confirm. Returns: object

reset_or_restart_sessionsA
Destructive

Reset or restart the virtual machine backing one or more sessions.

CAUTION: Both actions will terminate the user's session. reset is a hard power-cycle and may cause data loss. restart attempts a graceful reboot but the session will still end. Always confirm with the user before calling this.

Inputs: action (required), session_ids (required), confirm. Returns: object

search_ad_users_or_groupsA
Read-only

Search for AD users and groups in the Horizon environment.

Use the returned 'id' field when setting pool entitlements.

Common filter fields: name, login_name, group, domain. Example filters: Find user by login: {"type":"Equals","name":"login_name","value":"jsmith"} Find by display name: {"type":"Contains","name":"name","value":"John"} Groups only: {"type":"Equals","name":"group","value":"true"}

Returns {items, count, page, size, pages_fetched, has_more, next_page, truncated}. If has_more is true there may be more results: call again with page=next_page (or narrow the filter), or pass fetch_all=true to fetch pages automatically (stops after 10 pages or 5000 items and sets truncated=true). Never treat a result with has_more=true as the complete list.

Inputs: page, size, filter, fetch_all. Returns: object

send_message_to_sessionsA

Send a pop-up notification message to one or more active user sessions.

Inputs: message (required), session_ids (required), message_type. Returns: object

set_pool_entitlementsA
Destructive

Add, replace, or remove entitlements for a desktop or application pool.

CAUTION: action='replace' removes any existing entitlements not in the provided list. CAUTION: action='remove' immediately revokes access for the specified principals. Always confirm with the user before using replace or remove.

NOTE: action='replace' is only supported for desktop pools — the Horizon API has no bulk-replace endpoint for application pools.

Inputs: action (required), pool_id (required), pool_type (required), ad_user_or_group_ids (required), +1 more. Returns: object

trigger_connection_server_backupA

Initiate an immediate backup of one or more Connection Servers.

CAUTION: This triggers an active backup operation, not a validation check. If no server_ids are provided, all Connection Servers are backed up.

Inputs: server_ids. Returns: object

update_application_poolA
DestructiveIdempotent

Update an existing application pool's configuration.

Horizon returns supported_file_types_data with both its auto-discovered file_types and enable_auto_update_file_types=true, then rejects that combination on update ("file_types cannot be set when enable_auto_update_file_types is enabled", verified on 2606). So when auto-update is on, file_types is dropped here: Horizon manages that list itself.

Inputs: spec (required), pool_id (required). Returns: object

update_desktop_poolA
DestructiveIdempotent

Update an existing desktop pool's configuration.

Inputs: spec (required), pool_id (required). Returns: object

update_global_policiesA
DestructiveIdempotent

Update global VDI policies (USB redirection, clipboard, multimedia redirection).

Always call get_global_policies first to read current values. Only modify the specific fields you intend to change — pass the full object back.

Inputs: spec (required), confirm. Returns: object

update_rdsh_farmC
DestructiveIdempotent

Update an existing RDS farm's configuration.

Inputs: spec (required), farm_id (required). Returns: object

update_settingsA
DestructiveIdempotent

Update a Horizon settings section.

setting_type maps to these resources and endpoints: general → horizon://config/settings/general security → horizon://config/settings/security client → horizon://config/settings/client feature → horizon://config/settings/feature agent-restriction → horizon://config/settings/agent-restriction

Always read the current settings first and only modify the fields you intend to change.

general: Horizon returns restricted_client_data entries that have only a "type", but rejects them on update with "Restricted client version must be set for client type " (verified on 2606), so passing the settings back unchanged fails. Give every restricted_client_data entry a "version" before calling this.

Inputs: spec (required), setting_type (required), confirm. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 72 tools

    Disambiguation4/5

    Tools are largely separated by resource and action (create/get/update/delete_desktop_pool, list_sessions/get_session, etc.), and the *_action tools are clearly documented as bulk lifecycle toggles. There is mild overlap in the settings surface (get_settings vs get_global_policies vs get_environment_properties, and their update counterparts), but descriptions clarify boundaries.

    Naming Consistency4/5

    Names follow a predictable snake_case verb_noun convention (list_, get_, create_, update_, delete_) almost throughout, including consistent horizon_* auth tools. Minor deviations are the noun_action tools (machine_action, desktop_pool_action, rdsh_farm_action) and slightly irregular list_hosts_or_clusters, but these are still readable and systematic.

    Tool Count2/5

    At 72 tools this is a very heavy surface, well beyond the 3-15 sweet spot, and an agent must sift through many near-sibling calls. The domain (pools, farms, machines, sessions, entitlements, AD, vCenter inventory, settings, monitoring) is genuinely broad so most tools earn their place, but the sheer count risks selection errors.

    Completeness4/5

    Core lifecycles are well covered: full CRUD for desktop pools, RDS farms, and application pools, plus machine/session actions, entitlements, AD search, vCenter inventory helpers, and health/metrics rollups. Gaps are mostly read-only areas (e.g. connection servers, licenses, gateways lack update/management ops), which an agent can work around.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure management of VMware vCenter 8.0+ environments through controlled operations including VM lifecycle management, snapshots, and resource discovery with built-in RBAC authorization, audit logging, and rate limiting.
      6
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables management of VMware vCenter and ESXi environments, including VM operations, resource management, and automation with Ollama AI and n8n workflows.
      4
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with VMware vCenter 8.0 REST API via a reverse proxy, providing read-only and write tools with dry-run protection and automatic session management.
      -