Seven tools.
Four tools have command-line equivalents; actions, adoption and unadoption exist only as tools. Every tool except xsession_adopt accepts a session's id or its name; adoption needs the exact id.
Create, list and inspect sessions.
| Tool | Use it to | Parameters |
|---|---|---|
xsession_create | Create and start a desktop session and get back its record plus the endpoint and token a viewer needs to connect. An input it does not know, such as a misspelled port name, fails the call. | none required; see the options below |
xsession_list | List the sessions this connection owns, and optionally the unowned ones. Unowned sessions show only their id, name, state, audio and creation time, enough to choose one to adopt but not to act on. | includeOrphaned (optional, default false) |
xsession_get_env | Read what a local program needs to reach a session: the display, authority file, runtime directory, sound path and remote desktop endpoint. There is no Wayland compositor, so the Wayland display is always empty. | sessionId (required, id or name) |
Why: create once, then read the attach facts instead of guessing them. A local program needs both DISPLAY and XAUTHORITY to open the display, and a viewer needs the rdp block; xsession_get_env is the one place both are reported.
Every input of xsession_create is optional:
| Option | Default | Use it to |
|---|---|---|
sessionId | generated | Choose the id: 1 to 64 letters, digits, ., _ or - |
name | the id | Give it a friendly name, unique among your sessions; accepted anywhere an id is |
resolution | 1920x1080 | Set the desktop size, WxH |
wm | none | Start a window manager: openbox, fluxbox, icewm, twm or dwm |
audio | the audio default set by your launcher, else bridge | Choose sound: off (none), on (sound to the viewer and microphone from it), host (the same, plus an output that plays on the host's audio server) or bridge (the same as on) |
rdpPort | from 33890 | Pick the loopback port; a port held by another session or one that cannot be bound fails the call and is never substituted |
rdpToken | generated | Supply your own token (16 to 256 letters, digits, _ or -); its strength is then yours to guarantee |
displayNumber | from 100 | Leave it unset: the record shows the number that was assigned. A value held by another session is skipped, and a value already claimed on the host fails the call |
Resize, freeze, rotate and destroy.
| Tool | Use it to | Parameters |
|---|---|---|
xsession_action | Stop, resume, destroy, resize or issue a new token for a session, one at a time or as a batch of up to 50 independent items. It is the one call for every change to a running session. | one item (sessionId, action) or actions, never both |
xsession_destroy | Tear a session down and remove its files. | sessionId (required, id or name) |
The actions of xsession_action:
| Action | Extra inputs | Use it to |
|---|---|---|
stop | force (optional) | Freeze every process the session supervises, the desktop included; nothing is torn down |
resume | force (optional) | Unfreeze them |
destroy | none | Remove the session, as xsession_destroy does |
resize | width and height, both required | Change the desktop size live; a connected viewer follows. The session must be running |
rotate-token | none | Issue a fresh token. Later connections need it; an open connection is not evicted |
Why: change the session you have rather than starting another. Resume a stopped session before destroying it: a destroy does not thaw it first, and a batch that destroys several frozen sessions can exceed the 60-second call limit. force applies to stop and resume only: on stop it retries a session already recorded as stopped, and on resume it is the way to try to thaw a degraded one.
A batch returns one result per item with success and, on failure, an error, plus a total, succeeded and failed summary. The call itself succeeds even when every item failed, so read failed. It is refused before anything runs when it is empty, has more than 50 items or names an action that does not exist.
Adopt and release ownership.
| Tool | Use it to | Parameters |
|---|---|---|
xsession_adopt | Claim a session that no connection owns and get its full record. It creates and destroys nothing, and fails if you already own the session, if its name collides with one of yours, or if it is not available. | sessionId (required, the exact id, never a name) |
xsession_unadopt | Release ownership of a session without destroying it. Its processes keep running, so use it only for a deliberate handoff. | sessionId (required, id or name) |
Why: a crash or a handoff leaves a session nobody owns. Find it with xsession_list and includeOrphaned, adopt it by its exact id, and finish it. For ordinary completion, call xsession_destroy instead of unadopting.
What a session can be.
| State | Meaning |
|---|---|
running | Started and serving: the normal state after a successful create |
stopped | Frozen by stop; everything is kept in place and resume returns it to running |
degraded | One or more of its processes exited after a successful create. Read the component logs, then destroy it |
destroying | Teardown is in progress; actions on it fail |
What to expect when a call fails.
A tool failure comes back as a tool error with a message, not as a protocol error. The limits that matter:
| Limit | Value |
|---|---|
| Calls | 30 per minute across the tool prefix |
| One call | 60 seconds by default; MCP_XSESSION_TOOL_TIMEOUT_SECS changes it |
| Items per batch | 50 |
| Viewers | one RDP viewer per session |
| Resize | any size within the session's own limits, up to 32768 by 32768 on the desktop server this starts, and only while the session is running |
| Listening | 127.0.0.1 only; reaching a session from another machine is your own deployment choice, such as an SSH tunnel |
A destroy that reports errors has still removed the session's record; the message names what could not be cleaned up. See Troubleshooting.