Citrix DaaS MCP Server Cloud
The Citrix DaaS MCP Server Cloud enables MCP-capable AI agents to connect to your Citrix DaaS environment. Once connected, administrators can query site information, investigate session and machine issues, and retrieve performance data using natural language.
The MCP server is hosted in Citrix Cloud and provides 28 tools. All tools are read-only queries and diagnostics, including one tool that runs the built-in VDA health check. No tool changes the configuration or state of your Citrix DaaS environment.
Note:
This feature is in preview. You only need a Citrix Cloud service principal to get started.
Example questions:
-
Why did the logon fail for this user
<jane.doe>? -
Show me the session performance metrics for this user
<jane.doe> -
Show me machines stuck on boot in the past hour.
-
Which machines are in maintenance mode?
-
Which multi-session VDAs are the most loaded right now?
-
Why did this session launch fail? Transaction ID
<transaction_id>.
For on-premises sites, see Citrix DaaS MCP Server Local. To compare both options, see Citrix DaaS MCP Server.
How it works
-
The AI client starts the Citrix helper (
@citrix/mcp-daas-proxy) as a local stdio process. -
The helper exchanges the service principal Client ID and Client Secret for a short-lived token from Citrix Cloud.
-
The helper forwards each request from the AI client to the MCP server over HTTPS.
-
The MCP server validates the token against the Customer ID in the request and calls the Citrix DaaS APIs.
-
The result returns to the AI client. The helper renews the token automatically before it expires.
Security and authentication
-
Service principal access: Citrix Cloud enforces the role of the service principal on every API call. With a read-only role, any operation beyond reading is rejected.
-
Fixed tool catalog: The MCP server exposes only the tools listed in available tools. Power actions, session controls, and catalog or delivery group changes are not available.
-
Account isolation: Every request is bound to the Customer ID in the service URL. Access to other Citrix Cloud accounts is not possible.
-
Encryption in transit: All traffic uses HTTPS (TLS 1.2 or later).
-
Credential storage: By default, the Client Secret is stored in the AI client configuration. Storing it in the OS credential vault is recommended.
Supported AI clients
| AI client | Notes |
|---|---|
| Claude Code | Configured with the claude mcp add command |
| Codex CLI | Configured in ~/.codex/config.toml |
| MCP Inspector | Use to verify the connection |
Usage telemetry
The helper and the MCP server do not collect telemetry from user devices. For each tool call, the service records the time, tool name, outcome, AI client user agent, Customer ID, and the Citrix Cloud user ID from the access token. With a service principal, the user ID is that of the administrator who created the service principal.
Data stored in Citrix Cloud is used to measure adoption, improve reliability, and performance.
Prerequisites
-
Citrix DaaS
-
Node.js 24 LTS (recommended) or Node.js 22 LTS
-
Windows or Linux machine that runs an AI client
-
A Citrix Cloud service principal. A read-only role is recommended
-
Outbound HTTPS (port 443) to the hosts in Network requirements
-
Administrator permissions to create service principals in Citrix Cloud
-
Optional: To use the VDA health check tool, the service principal needs the Perform Built-In Scripted Task on Machines/Sessions permission and meet the feature prerequisites
Network requirements
Allow outbound HTTPS (port 443) from every machine that runs an AI client. No inbound ports, VPN, or changes to your Citrix environment are required.
| Host | Purpose |
|---|---|
| copilot.cloud.com | Citrix DaaS MCP Server Cloud for US region |
| copilot-eu.cloud.com | Citrix DaaS MCP Server Cloud for EU region |
| api-us.cloud.com | Citrix Cloud identity service |
| registry.npmjs.org | Package resolution by npx. Allow by host name, not by IP address |
Note:
To confirm the identity host for your account, run
curl https://copilot.cloud.com/cvad/<customer_id>/.well-known/oauth-authorization-server and allow the host shown in token_endpoint.
Getting started
Create a service principal
Step 1: Create the service principal
-
Sign in to Citrix Cloud and navigate to Identity and Access Management > API Access > Service principals.
-
Create a service principal and assign a read-only role, such as Read Only Administrator scoped to DaaS.
-
Set an expiry date of no more than 60 days (recommended)
Step 2: Record the credentials
-
Copy the Client ID and Client Secret. The secret is shown only once.
-
Copy your Customer ID, shown at the top right of the Citrix Cloud console.
-
Record the expiry date and set a reminder before it.
Install Node.js
Skip this section if
node -v returns v24.x.x or v22.x.x.
Step 1: Install Node.js
| Platform | Install |
|---|---|
| Windows | Download the LTS installer from nodejs.org, or run winget install OpenJS.NodeJS.LTS |
| Linux | Install the Node.js 24 package for your distribution |
Step 2: Verify the installation
Open a new terminal and run:
node -v
npm -v
Verify that
node -v returns v24.x.x or v22.x.x. If npm -v returns 12.x or later, see Troubleshooting.
Connect the MCP server to your AI client
In the commands in this section, replace
<version> with the current helper version. To find the latest version, see {release notes link TBD}. Change the DAAS_MCP_URL based on region.
Step 1: Store the Client Secret in the OS credential vault (recommended)
The helper can read the Client Secret from Windows Credential Manager or the Linux Secret Service instead of from the AI client configuration.
Windows PowerShell:
$env:DAAS_SECRET_STORE = "keychain"
$env:DAAS_MCP_URL = "https://copilot.cloud.com/cvad/<customer_id>/mcp"
$env:DAAS_CLIENT_ID= "<client_id>"
npx -y https://copilot.cloud.com/cvad/artifacts/citrix-mcp-daas-proxy-<version>.tgz login
Linux:
DAAS_SECRET_STORE=keychain \
DAAS_MCP_URL="https://copilot.cloud.com/cvad/<customer_id>/mcp" \
DAAS_CLIENT_ID="<client_id>" \
npx -y https://copilot.cloud.com/cvad/artifacts/citrix-mcp-daas-proxy-<version>.tgz login
Enter the Client Secret when prompted. In Step 2, replace the
DAAS_CLIENT_SECRET entry with DAAS_SECRET_STORE set to keychain.
Note:
Delete the
DAAS_CLIENT_SECRET entry completely. If it remains, the helper uses the plain-text value whenever the vault has no entry. Run the doctor command and check the Credential source stage to confirm which source is in use.
Step 2: Configure the AI client
Replace
<customer_id>, <client_id>, <client_secret>, and <version> with your values. Restart the AI client afterward.
Claude Code
claude mcp add daas-mcp-server --scope user \
-e DAAS_MCP_URL=https://copilot.cloud.com/cvad/<customer_id>/mcp \
-e DAAS_CLIENT_ID=<client_id> \
-e DAAS_CLIENT_SECRET=<client_secret> \
-- npx -y https://copilot.cloud.com/cvad/artifacts/citrix-mcp-daas-proxy-<version>.tgz
Run
claude mcp list to confirm the server is registered.
Codex CLI (
~/.codex/config.toml)
[mcp_servers.daas-mcp-server]
command = "npx"
args = ["-y", "https://copilot.cloud.com/cvad/artifacts/citrix-mcp-daas-proxy-<version>.tgz"]
startup_timeout_sec = 120
[mcp_servers.daas-mcp-server.env]
DAAS_MCP_URL = "https://copilot.cloud.com/cvad/<customer_id>/mcp"
DAAS_CLIENT_ID = "<client_id>"
DAAS_CLIENT_SECRET = "<client_secret>"
For other AI clients (manual setup)
Configure the AI client to run
npx -y <helper URL> as the MCP server command. Set DAAS_MCP_URL, DAAS_CLIENT_ID, and DAAS_CLIENT_SECRET in the environment block of the client configuration.
Step 3: Verify the connection
-
Restart the AI client.
-
Ask: "Use the get_hourly_summaries tool to show me current site health."
-
Verify that the response includes connection failures, failed machines, and connected sessions.
If the request fails, ask the AI client to "run the Citrix DaaS proxy doctor." For more information, see Troubleshooting.
Available tools
Common tool parameters
Several tools share the same input parameters. The following tables describe the accepted formats.
Machine name formats
Tools that accept a machine name support the following formats:
| Format | Example |
|---|---|
| Canonical (DOMAINHOSTNAME) | CTXCOTestVDA1 |
| Hostname only | TestVDA1 |
| Fully qualified domain name (FQDN) | TestVDA1.ctxco.local |
If a name does not match a single machine exactly, the tool runs a fuzzy lookup. If several machines match, the tool returns a clarification that lists the candidates.
Username format
User names use the domain\username format, for example CTXCO\john.smith. Search tools also support partial matching.
Time window parameters
Some tools accept a time window that controls how far back data is retrieved:
| Parameter | Default | Maximum | Used by |
|---|---|---|---|
| latest_hours | 2 hours | 2 hours | get_session_metrics, get_endpoint_metrics |
| offset_hours | 2 hours | 7 days | get_connection_failures (by user) |
Available tools
The Citrix DaaS MCP Server Cloud provides 28 tools, grouped by area. All tools are read-only, they query your Citrix DaaS environment and return data without modifying any resources.
Site overview
| Tool | Description |
|---|---|
| get_hourly_summaries | Returns current connection failure counts by type and failed VDI and RDS machine counts by type, with connected session activity for the past hour. |
| get_hypervisors_info | Lists all hypervisor connections, or returns the detailed configuration of one hypervisor. |
| get_group_policy_list | Returns the site's group policies with name, priority, enabled state, settings, and filters. |
Delivery Groups
| Tool | Description |
|---|---|
| search_delivery_groups | Searches and lists Delivery Groups. Filters: name, maintenance mode, enabled state, sharing kind, and session support. |
| get_delivery_group_details | Returns detailed information for one Delivery Group, by name or ID. |
Machine Catalogs
| Tool | Description |
|---|---|
| search_machine_catalogs | Searches and lists Machine Catalogs. Filters: name, physical machines, allocation type, provisioning type, and session support. |
| get_machine_catalog_details | Returns detailed information for one Machine Catalog, by name or ID. |
VDA machines
| Tool | Description |
|---|---|
| search_vda_machines | Searches machines. Filters: Delivery Group, Machine Catalog, agent version, OS type, tags, maintenance mode, power state, registration state, session state, and fault state. |
| get_vda_machine_details | Returns detailed information for one VDA machine, by name or ID. |
| get_vda_machine_resource_usage | Analyzes machine resource usage for the past 7 days with a health assessment and statistical profiling (mean, P95, max). Detects anomalies and saturation patterns, and gives actionable recommendations. |
| list_top_vda_machines_by_load_index | Lists the most heavily loaded multi-session OS VDA machines, ranked by effective load index. |
| get_vda_machine_failure_logs | Returns failure logs for one VDA machine, with machine context. |
| check_vda_machine_service_status | Returns the health of critical VDA services on one machine. |
Sessions
| Tool | Description |
|---|---|
| search_sessions | Searches sessions. Filters: user, machine, Delivery Group, Machine Catalog, agent version, OS type, session state, session support, and applications in use. |
| get_session_details | Returns full details for one session, by session ID. |
| get_session_metrics | Returns session performance metrics, such as ICA RTT, bandwidth, and FPS, for a user or session over the past 2 hours. A gap in metrics may indicate that the session was disconnected during that period. |
| get_session_logon_breakdown_metrics | Returns a user's logon duration breakdown, with the duration, start time, and end time of each step. |
| get_gateway_service_latest_metrics | Returns the latest Citrix Gateway service network metrics for a session. |
Users and endpoints
| Tool | Description |
|---|---|
| get_active_machines_by_user | Lists the VDA machines where a user has active sessions, with machine name, DNS name, IP address, and agent version. |
| get_active_users_by_machine | Lists the users with active sessions on one or more machines, with user name, UPN, full name, and domain. |
| get_endpoint_metrics | Returns endpoint (client) device metrics for a user or session over the past 2 hours. |
| get_connection_failures | Returns failed connection attempts, with the failure reason and machine status at the time of failure. Looks back up to 7 days by user, or up to 90 days by transaction ID. |
Session launch transactions
| Tool | Description |
|---|---|
| analyze_failed_transaction | Returns the component-level root cause of a failed session launch (VDA, Gateway, Connector, or StoreFront), with recommended actions. |
| get_transaction_logs | Returns the raw logs from each component for a session launch transaction. |
Advanced queries
| Tool | Description |
|---|---|
| run_dynamic_odata | Runs custom OData queries against the Citrix Monitor OData service, with automatic pagination up to 10,000 rows. |
| get_odata_reference | Returns the Citrix Monitor OData reference (entities, fields, enums, and query examples), by topic and section. The AI client uses it to build queries for run_dynamic_odata. |
Manage credentials
| Task | Action | User impact |
|---|---|---|
| Extend | Move the service principal expiry date out by no more than 60 days. | None. The Client ID and Client Secret do not change. |
| Rotate | Issue a new primary secret. The previous secret moves to the secondary slot and continues to work. Delete the secondary secret after all users update. | Each user updates the Client Secret, or reruns login, and restarts the AI client. |
| Revoke | Disable or delete the service principal in Citrix Cloud. | New tokens are blocked immediately. A token already issued remains valid for up to one hour. |
Rotate secrets at least every 60 days. Citrix Cloud notifies administrators with the Notifications permission before a service principal expires. Users of the credential are not notified.
Update the configuration
The helper version is part of the download URL, so updates never change behavior without notice. To update:
-
Change
<version>in the helper URL in the AI client configuration. -
Run the doctor command once to download the new version to the local cache.
-
Restart the AI client.
Note:
Older helper versions are removed over time. A configuration that references a removed version fails to start.
Known limitations
| Limitation | Details |
|---|---|
| Session and endpoint metrics window | get_session_metrics and get_endpoint_metrics return data for the last 2 hours only. |
| Connection failure lookback | get_connection_failures supports up to 7 days by username. |
| OData row limit | run_dynamic_odata returns a maximum of 10,000 rows per query. |
| Orchestration tool limit | Tools retrieving configuration details have a limit of up to 500. Machine and session lists may be truncated. Add filters, such as Delivery Group, catalog, state, or time window, or use the Monitor OData API for full exports. |
| One account per AI session | Each server is bound to one Customer ID, and tool names are identical across servers. Enable only one server per AI session. Name each server after its account, for example daas-mcp-conto. |
| Credential expiry | An expired service principal returns the same error as an incorrect Client Secret. |
Troubleshooting
The helper includes a doctor command that tests the connection stage by stage. The output never includes the Client Secret or tokens, so it is safe to attach to a support case.
| Stage | Checks |
|---|---|
| Configuration | Required settings are present and the service URL is valid |
| Credential source | Secret was read from the OS vault or from the environment variable |
| Network reachability | DNS lookup, TCP connection, and TLS handshake |
| OAuth discovery | Citrix Cloud sign-in endpoint is found |
| Token exchange | Client ID and Client Secret return a token |
| Upstream session | MCP server accepts the session, and the number of tools offered |
Ask the AI client to "run the Citrix DaaS proxy doctor," or run it from a terminal when the helper does not start:
DAAS_MCP_URL="https://copilot.cloud.com/cvad/<customer_id>/mcp" \
DAAS_CLIENT_ID="<client_id>" \
DAAS_CLIENT_SECRET="<client_secret>" \
npx -y https://copilot.cloud.com/cvad/artifacts/citrix-mcp-daas-proxy-<version>.tgz doctor
The MCP server times out or shows as failed when the AI client starts?
Solution:
-
Run the doctor command from a terminal once. This downloads the helper to the local cache before the AI client times out.
-
Increase the startup timeout. For Claude Code, start it with
MCP_TIMEOUT=120000. For Codex CLI, setstartup_timeout_sec = 120. -
Verify that
DAAS_MCP_URL,DAAS_CLIENT_ID, andDAAS_CLIENT_SECRETare set, and that the URL starts withhttps://. -
Fully restart the AI client.
The helper fails with npm error code EALLOWREMOTE?
Solution:
-
Run
npm -v. This error occurs with npm 12 or later. -
Add
--allow-remote=rootbefore the helper URL in the args list. This setting is safe on earlier npm versions. -
Do not run
npm config set allow-remote all. It allows URL installs for every package on the machine.
The helper fails with ECONNREFUSED, ETIMEDOUT, or ENOTFOUND for registry.npmjs.org?
Solution:
-
Allow outbound HTTPS to registry.npmjs.org by host name.
-
Verify that the firewall rule does not cover only
*.cloud.com. The npm registry is a separate host. -
If your network inspects TLS traffic, set
NODE_EXTRA_CA_CERTSto the path of your corporate CA bundle.
The AI client connects, but no Citrix tools appear, or only the diagnostic tool appears?
Solution:
-
Ask the AI client to "run the Citrix DaaS proxy doctor" and fix the failed stage.
-
Fully restart the AI client. Most AI clients read the tool list only once, when they connect.
Authentication fails, but the Client ID and Client Secret are correct?
Solution:
-
Check the service principal expiry date in Citrix Cloud. Extend the expiry date to restore access without changing user configurations.
-
Check whether the secret was rotated and the secondary secret deleted. Update the Client Secret and restart the AI client.
-
Check the configuration for a trailing space or a truncated secret.
-
Wait one minute and retry. Many simultaneous AI client connections can trigger rate limiting.
The token exchange succeeds, but every query returns an authorization error?
Solution:
-
Verify that the Customer ID in
DAAS_MCP_URLis correct. -
Verify that the service principal was created in the same Citrix Cloud account.
Command reference
| Command | Purpose |
|---|---|
npx -y <helper URL> |
Starts the helper. The AI client runs this command. |
npx -y <helper URL> login |
Stores the Client Secret in the OS credential vault. Requires DAAS_SECRET_STORE=keychain. |
npx -y <helper URL> logout |
Removes the stored Client Secret from the OS credential vault. Requires DAAS_SECRET_STORE=keychain. |
npx -y <helper URL> doctor |
Runs the connection self-test. |
| Environment variable | Required | Description |
|---|---|---|
| DAAS_MCP_URL | Yes | https://copilot.cloud.com/cvad/<customer_id>/mcp or use copilot-eu.cloud.com |
| DAAS_CLIENT_ID | Yes | Service principal Client ID |
| DAAS_CLIENT_SECRET | Yes, unless DAAS_SECRET_STORE is set | Service principal Client Secret |
| DAAS_SECRET_STORE | No | Set to keychain to read the Client Secret from the OS credential vault |
| NODE_EXTRA_CA_CERTS | No | Path to a corporate CA bundle, for networks that inspect TLS traffic |
| DAAS_LOG_LEVEL | No | error (default), warn, info, or debug |