Create a client connection token and a 15-minute invitation. Set multi_device=true for multiple simultaneous devices and a reusable invitation; otherwise the invitation is single-use and only one device may connect. First show display_text including both platform commands in a progress message, then follow next_action: call list_clients with client_token and wait_ms=20000 repeatedly until a device connects, the invitation expires, or the user cancels. Do not end the turn after showing the invitation or after an empty result. Immediately notify the user when a device connects. Use client_id to target devices for multi-device tokens. Session tools use session_id after starting a session. Treat tokens and commands as credentials and share privately. Saying you are waiting is insufficient: the same response must actually call list_clients; invitation creation alone does not complete this task.

Run a non-interactive shell command on the selected authorized target device and wait for completion. This can modify or delete files and perform any operation allowed to the target user; obtain user approval for destructive commands. client_token is required with management access (including stdio and no-password mode); client_id is required for multi-device tokens. Each call starts a fresh shell: set cwd and env explicitly; changes do not persist between calls. timeout_ms defaults to 60000 (60 seconds), 0 disables the timeout, and the maximum is 86400000 (24 hours). Captured stdout and stderr share a 1 MiB limit; excess output is discarded and truncated=true. The result contains stdout, stderr, exit_code, timed_out, canceled, truncated and optional error; a nonzero exit, timeout, cancellation or execution failure sets isError. Canceling the MCP request sends a best-effort cancellation request; it does not undo effects already performed. Commands are not automatically retried. Use session_start/read/write/stop for prompts, incremental output or long-running jobs.

List online devices belonging to this client_token. Set wait_ms=20000 to wait server-side while no device is online; a connection returns immediately. After creating an invitation, show display_text in a progress message and keep calling with wait_ms=20000 until the target connects, the invitation expires, or the user cancels. An empty result is only a wait timeout: continue waiting without ending the turn or asking the user to check. Immediately notify the user when connected. With wait_ms omitted or 0, return a snapshot immediately. Use client_id to execute commands or start sessions. For multi-device tokens, any online device completes the wait; use snapshots to discover additional devices.

Read incremental output and terminal state for an owned session. This does not send input or stop the process. Start with cursor=0, then use the returned next_cursor on each read; cursors are byte offsets, not character counts. wait_ms is 0-20000 (default 0): return immediately for new output or a terminal state, otherwise wait up to that many milliseconds. Empty output with done=false is only a polling timeout; continue polling. If older output was dropped from the 1 MiB buffer, truncated=true and reading resumes at the earliest retained byte; a cursor beyond available output is an error. done=true means a terminal result or a closed connection; only then are exit_code, timed_out, canceled and optional error included. A disconnect error is not proof of a remote command's success or confirmed cancellation. Use session_stop to terminate and session_write to supply input. Finished records expire after 30 minutes and server restarts invalidate them.

Start a new interactive terminal process on an authorized target device. The command can change files or system state with the target user's permissions. Supply client_id for multi-device tokens; set cwd and env for this new process. timeout_ms defaults to 0 (no timeout), with a maximum of 86400000 (24 hours). Returns session_id and the initial byte cursor 0, not command completion. Repeated calls start separate processes. Use session_read with the last next_cursor to collect incremental output until done=true, session_write to answer prompts (include a newline), and session_stop to cancel. Each token retains up to six sessions, and only the latest 1 MiB of each session's output is retained. Finished history expires after 30 minutes or can be evicted by later sessions; keep the session_id and poll promptly. Server restarts invalidate sessions. For a short non-interactive command with a final stdout/stderr result, use execute_command instead.

Request termination of a terminal session created by session_start. Requires its session_id and, with management access (including stdio and no-password mode), its owning client_token; it cannot stop a session owned by another token. Stopping can interrupt writes and lose unsaved work, and cannot undo completed side effects. wait_ms defaults to 1000 and can be 0-20000: 0 returns immediately after sending the request, otherwise wait up to that many milliseconds for a terminal result. accepted=true means a stop request was sent or is already pending, not that termination is confirmed. status=stopping and done=false require polling session_read until done=true; use its output/cursor to collect final output. status=stopped requires a terminal canceled=true report. status=finished means the session ended for another reason; inspect canceled, timed_out, exit_code and error, especially on disconnect. Repeating a stop is safe: an already-ended session returns already_done=true and accepted=false without sending another request. Unknown or unauthorized session IDs are errors. Use session_read to observe progress and session_write for input; stopping does not revoke the device token or disconnect other sessions.

Send text to the stdin of an owned running terminal session. Include a newline (for example, "yes\n") to submit an answer or command. Input can trigger destructive operations and may be echoed in session output, including secrets; only send input the user authorized. accepted=true confirms the input was sent to the device connection, not that the program consumed it or completed an action. Use session_read afterward to observe the response. Repeating a write sends the input again, so do not retry blindly. Unknown, unauthorized or ended sessions are errors. This does not start a session or cancel it; use session_start or session_stop for those operations.