mait.sh1.132.1

Private beta: features and content may change. No warranty; use at your own risk.

Install and configure mcp-xsession

Check that MCP XSession is installed, connect it to your agent, create a first private desktop and look at it.

Beta
OverviewGet startedUse casesToolsProblems and fixesAll components
Steps

Five steps from install to your first desktop.

MCP XSession is an MCP tool: you check it is installed, point your agent at it, and then ask in plain language. The desktops are Linux desktops. On macOS and Windows, MCP XSession runs in the managed Linux environment that AIDC Launch provides. It needs no network setup and no root access.

  1. Capturedmcp-xsession 0.5.5
    Check the version
    $ mcp-xsession --version
    mcp-xsession 0.5.5
    Check the programs it uses
    $ command -v mcp-xsession Xvnc xrandr openbox
    Step 1 of 5

    Check that it arrived

    The MAIT image ships mcp-xsession and updates it with the image. The desktop server it needs, Xvnc, is not part of the image: install it in your environment (the full getting started has the command), then check that everything runs and is on the PATH.

    Only Xvnc is required. Without xrandr the desktop cannot be resized; a window manager such as openbox is needed only if you ask for one. See mait-image.

    What you get

    The version command answers, and the one required program, Xvnc, is found.

  2. mcpServers entry
    {
  "mcpServers": {
    "xsession": {
      "command": "mcp-xsession",
      "args": ["serve"]
    }
  }
}
    Step 2 of 5

    Connect it to your agent

    Any client that accepts an mcpServers launch entry uses this shape. Place it where your client keeps server configuration and restart the client.

    The server speaks over standard input and output and keeps each client's sessions separate. If you reach your tools through the registry instead, add xsession once with mcp_registry_add and the tools carry the xsession__ prefix (registry guide).

    What you get

    A client that starts the service on its own, and an agent that can call the seven xsession tools.

  3. Capturedmcp-xsession 0.5.5
    YouCreate a 1280 by 720 desktop called guide-demo with the Openbox window manager.
    Tool callxsession_create { "name": "guide-demo", "resolution": "1280x720", "wm": "openbox" }
    What happensThe session starts with three components (a display server, a remote desktop service and a window manager) and state running; RDP listens on 127.0.0.1 port 33890 over TLS.
    Agentguide-demo is running at 1280 by 720. It listens on loopback only; the access token is in the result and I will not repeat it.
    Step 3 of 5

    Create a session

    Ask your agent for a desktop. It calls xsession_create and gets back the session's id, its components and an rdp block with the host, port, username and a secret token.

    What you get

    A running desktop with an id, an RDP endpoint on loopback and a token that only this session accepts.

  4. Capturedmcp-xsession 0.5.5
    YouShow me what is on the desktop.
    Tool callxsession_get_env { "sessionId": "guide-demo" }
    What happensReturns DISPLAY :101, the session's XAUTHORITY path, WAYLAND_DISPLAY null (there is no Wayland compositor) and the same rdp block.
    Tool callrdp_connection_create { "connectionId": "guide-demo", "host": "127.0.0.1", "port": 33890, "username": "xsession", "password": "<token from the rdp block>", "security": "tls", "graphicsMode": "rfx" }
    Tool callrdp_screenshot { "connectionId": "guide-demo", "filename": "desktop.png" }
    What happensA 1280 by 720 image is published as a resource.
    AgentThe desktop is up: the Openbox background with one window open. I saved desktop.png.
    Step 4 of 5

    Look at it

    The session is a desktop, not a picture. xsession_get_env returns the display and the endpoint a viewer needs, and mcp-rdp connects to it and takes a screenshot. Connecting is not the same as seeing a desktop, so look at the image.

    The captured image shows the Openbox desktop with one window open.

    Use mcp-rdp with this endpoint only from the same machine, over loopback, with the exact host and port the session returned. Set the viewer's security to TLS.

    What you get

    A real screenshot of the desktop, which proves the session is serving and not merely running.

  5. Capturedmcp-xsession 0.5.5
    YouI am done with it. Clean up.
    Tool callrdp_connection_drop { "connectionId": "guide-demo" }
    Tool callxsession_destroy { "sessionId": "guide-demo" }
    What happensThe session's processes stop and its runtime directory is removed.
    Agentguide-demo is destroyed and the viewer is disconnected.
    Step 5 of 5

    Finish the session

    A session lasts until you destroy it. Ask the agent to clean up when it is done.

    If you froze a session with stop, resume it before destroying it: a destroy of a frozen session is slow and can time out.

    What you get

    Nothing left running, and the session's files removed.

Result

A desktop that starts, shows and goes away.

MCP XSession is installed, connected to your agent and creating desktops you can see. Keep the calls on one connection: sessions belong to the connection that created them, so a different client or command does not see them unless a server runs in shared mode.

Next

Where to go next.