Connect Your AI Agent

Connect a local stdio MCP client to the installed App. The agent and desktop share experiment files, runs and configuration records.

Before you start

Complete Install and Start and open the App. It includes the isolated MCP runtime; no separate environment or copied access token is required. The App does not register itself in your AI client automatically.

Configure your client

Use this executable with no arguments:

/Applications/CulsmaOS Preview.app/Contents/MacOS/culsma-mcp

For clients that accept this JSON structure:

{
  "mcpServers": {
    "culsma-os": {
      "command": "/Applications/CulsmaOS Preview.app/Contents/MacOS/culsma-mcp",
      "args": []
    }
  }
}

Use the configuration format required by your client. If the App is installed elsewhere, copy its generated command from ~/Library/Application Support/culsmaOS/preview/mcp-config.json. Restart or reconnect the client's MCP session after saving.

Driver capabilities, configuration checks and layout conversion are provided by the running OS resident. The MCP bridge queries that resident; it does not need a second copy of the device driver. A driver unavailable to the resident remains unavailable through MCP.

Check the connection

Check the CulsmaOS connection. Tell me the selected workstation, the actual connected driver, whether it is ready, which experiment files are available, and whether any experiments are running. Read information only.

Expect real tool responses and the bundled Transfer/transfer.culs program. Then ask:

Open the workstation page in the CulsmaOS desktop and confirm whether it was displayed.

Reading status can work with the desktop window closed. Showing a page requires a live desktop session. Display requests can be deferred to preserve unsaved edits; inspect the receipt before claiming that a page opened.

Choose another installed workstation

Show the installed workstation choices and the current selection. Explain which restart steps would be needed before changing it.

After choosing an available target, ask the agent to select it for the next App start. This saves the choice without switching the running driver. Follow the returned restart instructions: close and reopen the App and reconnect MCP when requested. Read workstation status again to verify the actual driver.

The selection tools also work while the App is closed. A named workstation is not evidence of connected hardware; the default distribution includes the Opentrons simulator, while other drivers require their own installation.

Preparation handoff

Before starting, the agent should explain the checked loading requirements, execution mode and remaining blockers. Simulation loading can proceed automatically. Physical loading attestation belongs to the operator and is not exposed as an MCP tool; the 0.2.0 desktop hardware-run action is disabled.

Next: Your First Simulation, or Installation and Connection Help.