Citrix DaaS MCP Server Cloud

Last published : Nov 17, 2026
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

  1. The AI client starts the Citrix helper (@citrix/mcp-daas-proxy) as a local stdio process.
  2. The helper exchanges the service principal Client ID and Client Secret for a short-lived token from Citrix Cloud.
  3. The helper forwards each request from the AI client to the MCP server over HTTPS.
  4. The MCP server validates the token against the Customer ID in the request and calls the Citrix DaaS APIs.
  5. 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

  1. Sign in to Citrix Cloud and navigate to Identity and Access Management > API Access > Service principals.
  2. Create a service principal and assign a read-only role, such as Read Only Administrator scoped to DaaS.
  3. Set an expiry date of no more than 60 days (recommended)

Step 2: Record the credentials

  1. Copy the Client ID and Client Secret. The secret is shown only once.
  2. Copy your Customer ID, shown at the top right of the Citrix Cloud console.
  3. 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 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

  1. Restart the AI client.
  2. Ask: "Use the get_hourly_summaries tool to show me current site health."
  3. 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:
  1. Change <version> in the helper URL in the AI client configuration.
  2. Run the doctor command once to download the new version to the local cache.
  3. 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, set startup_timeout_sec = 120.
  • Verify that DAAS_MCP_URL, DAAS_CLIENT_ID, and DAAS_CLIENT_SECRET are set, and that the URL starts with https://.
  • 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=root before 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_CERTS to 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_URL is 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