Model Context Protocol (MCP)

What is MCP?

MCP (Model Context Protocol) is an open standard that allows AI assistants to interact with external tools and data sources. Think of it as a universal adapter between AI assistants (like Claude) and your infrastructure.

With the @xen-orchestra/mcp package, your AI assistant can directly query your Xen Orchestra instance to answer questions about your virtualization infrastructure in natural language.

Why MCP with Xen Orchestra?

MCP enables new ways to interact with your infrastructure:

Natural language queries — Ask "How many VMs are running?" instead of navigating dashboards
AI-assisted monitoring — Get instant summaries of your infrastructure state
Quick diagnostics — Ask about specific VMs, hosts, or pools without leaving your conversation
Documentation at your fingertips — Search XO documentation directly from the assistant

All operations are read-only by design, ensuring safe interaction with your production environment.

Installation

Prerequisites

Node.js 20 or later
A Xen Orchestra instance with REST API enabled
An AI assistant that supports MCP (Claude Desktop, Claude Code, etc.)

Install the MCP server

npm install -g @xen-orchestra/mcp

Or run directly without installing:

npx @xen-orchestra/mcp

Configure authentication

The MCP server connects to Xen Orchestra via the REST API. Two authentication modes are supported: token (recommended) or username/password.

Variable	Required	Description
`XO_URL`	Yes	Xen Orchestra server URL (e.g., `https://xo.example.com`)
`XO_TOKEN`	If no username/password	Authentication token
`XO_USERNAME`	If no token	XO user with admin privileges
`XO_PASSWORD`	If no token	XO password

To generate a token, go to the XO user page (/user) or run xo-cli create-token. If both XO_TOKEN and XO_USERNAME/XO_PASSWORD are set, token authentication takes priority.

tip

Only admin users can currently use the REST API. See REST API authentication for details.

Configure your AI assistant

Claude Desktop

Add the following to your Claude Desktop configuration file (~/.config/claude-desktop/config.json on Linux, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Using a token (recommended):

{
  "mcpServers": {
    "xo": {
      "command": "npx",
      "args": ["@xen-orchestra/mcp"],
      "env": {
        "XO_URL": "https://your-xo-server",
        "XO_TOKEN": "your-token"
      }
    }
  }
}

Using username/password:

{
  "mcpServers": {
    "xo": {
      "command": "npx",
      "args": ["@xen-orchestra/mcp"],
      "env": {
        "XO_URL": "https://your-xo-server",
        "XO_USERNAME": "admin@example.com",
        "XO_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

# Using a token (recommended)
claude mcp add xo \
  -e XO_URL=https://your-xo-server \
  -e XO_TOKEN=your-token \
  -- npx @xen-orchestra/mcp

# Using username/password
claude mcp add xo \
  -e XO_URL=https://your-xo-server \
  -e XO_USERNAME=admin@example.com \
  -e XO_PASSWORD=your-password \
  -- npx @xen-orchestra/mcp

Other MCP-compatible clients

Run the MCP server with environment variables set:

# Using a token (recommended)
XO_URL=https://your-xo-server \
XO_TOKEN=your-token \
npx @xen-orchestra/mcp

# Using username/password
XO_URL=https://your-xo-server \
XO_USERNAME=admin@example.com \
XO_PASSWORD=your-password \
npx @xen-orchestra/mcp

The server communicates via stdio using the MCP protocol (JSON-RPC), compatible with any MCP client.

Multiple XO instances

To manage several XO servers from the same assistant, add one entry per instance with a different name:

{
  "mcpServers": {
    "xo-production": {
      "command": "npx",
      "args": ["@xen-orchestra/mcp"],
      "env": {
        "XO_URL": "https://xo-production.example.com",
        "XO_TOKEN": "prod-token"
      }
    },
    "xo-staging": {
      "command": "npx",
      "args": ["@xen-orchestra/mcp"],
      "env": {
        "XO_URL": "https://xo-staging.example.com",
        "XO_TOKEN": "staging-token"
      }
    }
  }
}

With Claude Code:

claude mcp add xo-production \
  -e XO_URL=https://xo-production.example.com \
  -e XO_TOKEN=prod-token \
  -- npx @xen-orchestra/mcp

claude mcp add xo-staging \
  -e XO_URL=https://xo-staging.example.com \
  -e XO_TOKEN=staging-token \
  -- npx @xen-orchestra/mcp

Each entry starts its own process with its own credentials. The assistant gets a separate set of tools per instance, so you can ask about a specific environment by name ("list running VMs on xo-production").

tip

Pick descriptive names (xo-production, xo-dr-site, ...) so the assistant knows which instance you're referring to.

How it works

MCP architecture workflow

You ask a question in natural language to your AI assistant.
The assistant determines which MCP tool to call.
The MCP server queries the XO REST API (/rest/v0/...).
Results are returned to the assistant, which formats a natural language answer.

Available Tools

`check_connection`

Test the connection to the Xen Orchestra server. Use this to validate your setup before querying infrastructure.

Parameters: None

Example question: "Can you connect to my XO server?"

`list_pools`

List all pools in Xen Orchestra with their basic information.

Parameter	Type	Required	Description
`fields`	string	No	Comma-separated fields to return (default: `id,name_label,name_description,auto_poweron,HA_enabled`)

Example question: "List all my pools"

`get_pool_dashboard`

Get an aggregated dashboard for a specific pool, including host status, top resource consumers, and active alarms.

Parameter	Type	Required	Description
`pool_id`	string	Yes	The pool ID

Example question: "Show me the dashboard for pool X"

`list_hosts`

List all hosts (hypervisors) in Xen Orchestra with optional filtering.

Parameter	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `productBrand:XCP-ng`)
`fields`	string	No	Comma-separated fields (default: `id,name_label,productBrand,version,power_state`)
`limit`	number	No	Maximum number of results

Example question: "Show me all XCP-ng hosts"

`list_vms`

List virtual machines in Xen Orchestra with optional filtering.

Parameter	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `power_state:Running`, `name_label:web*`)
`fields`	string	No	Comma-separated fields (default: `id,name_label,power_state,CPUs,memory`)
`limit`	number	No	Maximum number of results

Example question: "How many VMs are currently running?"

`list_vdis`

List virtual disks (VDIs) in Xen Orchestra with optional filtering.

Parameter	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `VDI_type:User`, `name_label:backup*`)
`fields`	string	No	Comma-separated fields (default: `id,name_label,name_description,$SR,size,usage,VDI_type`)
`limit`	number	No	Maximum number of results

Example question: "List all user VDIs larger than 100GB"

`list_srs`

List storage repositories (SRs) in Xen Orchestra with optional filtering.

Parameter	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `SR_type:lvm`, `shared:true`)
`fields`	string	No	Comma-separated fields (default: `id,name_label,SR_type,allocationStrategy,size,usage,physical_usage,shared`)
`limit`	number	No	Maximum number of results

Example question: "List all shared storage repositories"

`get_sr_details`

Get detailed information about a specific storage repository.

Parameter	Type	Required	Description
`sr_id`	string	Yes	The SR ID or UUID

Example question: "Give me the details of SR abc123"

`list_networks`

List all networks in Xen Orchestra with optional filtering.

Parameter	Type	Required	Description
`filter`	string	No	Filter expression (e.g., `bridge:xenbr0`)
`fields`	string	No	Comma-separated fields (default: `id,name_label,name_description,bridge,MTU,nbd`)
`limit`	number	No	Maximum number of results

Example question: "List all networks using bridge xenbr0"

`get_network_details`

Get detailed information about a specific network.

Parameter	Type	Required	Description
`network_id`	string	Yes	The network ID

Example question: "Give me the details of network abc123"

`get_vm_details`

Get detailed information about a specific virtual machine.

Parameter	Type	Required	Description
`vm_id`	string	Yes	The VM ID or UUID

Example question: "Give me the details of VM abc123"

`get_infrastructure_summary`

Get a high-level summary of the entire XO infrastructure, including pool count, host count, and VM counts by power state (running, halted, other).

Parameters: None

Example question: "Give me an overview of my infrastructure"

`search_documentation`

Search and retrieve Xen Orchestra documentation. Useful for learning about XO features, configuration, and best practices.

Parameter	Type	Required	Description
`topic`	enum	Yes	One of: `installation`, `configuration`, `backups`, `restapi`, `manage`, `users`, `architecture`, `troubleshooting`, `releases`

Example question: "How do I configure backups in XO?"

Prompts

The MCP server also provides a built-in prompt:

`infrastructure-overview`

Generates a natural language overview of the XO infrastructure. When invoked, the assistant calls get_infrastructure_summary and formats the results as a readable summary with pool names, host counts, and VM statistics.

Example Conversations

Infrastructure overview:

Querying infrastructure with MCP

Searching documentation:

Searching XO documentation with MCP

Troubleshooting

Connection refused

Verify that XO_URL is correct and includes the protocol (https:// or http://). Make sure the XO server is reachable from the machine running the MCP server.

Authentication failed (401)

If using token authentication, check that XO_TOKEN is valid — the token may have expired or been revoked. If using username/password, check XO_USERNAME and XO_PASSWORD. Only admin users can currently access the REST API.

Timeout errors

The MCP server has a 30-second timeout for API requests. If you experience timeouts, check network connectivity between the MCP server and your XO instance.

Missing required environment variables

XO_URL is always required. You must also set either XO_TOKEN or both XO_USERNAME and XO_PASSWORD. When using Claude Desktop, make sure they are in the env section of the MCP server configuration.

What is MCP?​

Why MCP with Xen Orchestra?​

Installation​

Prerequisites​

Install the MCP server​

Configure authentication​

Configure your AI assistant​

Claude Desktop​

Claude Code​

Other MCP-compatible clients​

Multiple XO instances​

How it works​

Available Tools​

check_connection​

list_pools​

get_pool_dashboard​

list_hosts​

list_vms​

list_vdis​

list_srs​

get_sr_details​

list_networks​

get_network_details​

get_vm_details​

get_infrastructure_summary​

search_documentation​

Prompts​

infrastructure-overview​

Example Conversations​

Troubleshooting​