mait.sh1.69.2

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

Docs / MCP tool

MCP Console tools and settings reference

Arguments and results for the eight terminal tools, and the settings an installation exposes.

Tools that act on several terminals return one outcome per terminal; inspect each.

Settings apply to the server environment, not to the shell of a separate client.

Advanced
Problems and fixes

terminal_run

Runs a command in an existing shell, or creates a terminal for it. Without session, a foreground run is ephemeral.

ArgumentContract
commandRequired shell command
sessionOptional existing terminal; omit to create one
shellCreation shell; bash by default, also zsh, fish, sh
cwd, envWorking directory and environment for a new terminal
stdinData piped into a subshell that runs the command
timeoutForeground wait in seconds, default 120
backgroundDefault false; true leaves the terminal for observation
maxOutputBytesInline preview budget; by default a short head and tail
Argument
command
Contract
Required shell command
Argument
session
Contract
Optional existing terminal; omit to create one
Argument
shell
Contract
Creation shell; bash by default, also zsh, fish, sh
Argument
cwd, env
Contract
Working directory and environment for a new terminal
Argument
stdin
Contract
Data piped into a subshell that runs the command
Argument
timeout
Contract
Foreground wait in seconds, default 120
Argument
background
Contract
Default false; true leaves the terminal for observation
Argument
maxOutputBytes
Contract
Inline preview budget; by default a short head and tail

Foreground results include runId, session, exitCode, output, duration, timedOut and ephemeral. An ephemeral capture can be read back with terminal_read in run_output mode while the service still keeps it.

terminal_open

Creates a terminal, changes one you own, or attaches an eligible detached persistent terminal.

ArgumentContract
sessionChange your own terminal first; otherwise try detached attachment by identifier
attachWith tags and no identifier, request attachment by tag
name, groupName on creation or change; group on creation
sizeColumns and rows, default 80 by 24
shell, command, cwd, envCreation shell, initial command, directory and environment
tagsTags on creation, added tags on change, or search keys for attachment
persistentDefault false; set on creation
webTrue exposes or rotates the browser token; false removes it
Argument
session
Contract
Change your own terminal first; otherwise try detached attachment by identifier
Argument
attach
Contract
With tags and no identifier, request attachment by tag
Argument
name, group
Contract
Name on creation or change; group on creation
Argument
size
Contract
Columns and rows, default 80 by 24
Argument
shell, command, cwd, env
Contract
Creation shell, initial command, directory and environment
Argument
tags
Contract
Tags on creation, added tags on change, or search keys for attachment
Argument
persistent
Contract
Default false; set on creation
Argument
web
Contract
True exposes or rotates the browser token; false removes it

The response reports action (created, mutated or attached) and the terminal session. Read the screen to see when the program is ready.

terminal_send and terminal_read

terminal_send takes session or group, text, enter, ordered named keys, the ctrl, alt and shift modifiers, and an optional await of stable, prompt, pattern or none. It reports input delivery; read the screen for the application's response.

terminal_read supports these modes:

ModeMeaning
screenThe current view (default)
tailThe bottom rows of the view
incrementalFinalized lines after the shared cursor
scrollbackRetained history, by line count or ordered range
regionA rectangle of the current screen
framesRetained screen-change frames, after enabling a frame watch
run_outputA stored foreground capture, by runId
Mode
screen
Meaning
The current view (default)
Mode
tail
Meaning
The bottom rows of the view
Mode
incremental
Meaning
Finalized lines after the shared cursor
Mode
scrollback
Meaning
Retained history, by line count or ordered range
Mode
region
Meaning
A rectangle of the current screen
Mode
frames
Meaning
Retained screen-change frames, after enabling a frame watch
Mode
run_output
Meaning
A stored foreground capture, by runId

Output formats are text, ansi and lines.

terminal_watch, terminal_stats, terminal_list, terminal_close

  • terminal_watch selects one output mode (frame, idle or incremental output) and optionally a resource watcher with CPU and memory thresholds. off: true cancels both.
  • terminal_stats returns process-tree samples for a session or group; detail: true adds the top processes, whose arguments can contain private data. CPU is normalized to total machine capacity.
  • terminal_list lists terminals visible to this session, filtered by session, group, state or tags; detail adds working directory and execution history.
  • terminal_close selects session, group or all: true; force or signal choose forceful removal, and detach: true hands a single terminal off.

Installation settings

SettingDefaultEffect
MCP_CONSOLE_MAX_TERMINALS50Terminal admission check per client session
MCP_CONSOLE_MAX_ATTACHED_IDLE3600 secondsIdle threshold for attached terminals
MCP_CONSOLE_MAX_DETACH_DURATION86400 secondsExpiry threshold for detached persistent terminals
MCP_CONSOLE_RESOURCE_INTERVAL_MS2000Default resource watch interval
MCP_CONSOLE_RESOURCE_DEFAULT_SUSTAINED_MS15000How long a threshold breach lasts before an alert
MCP_CONSOLE_WEBOffEnables the browser bridge
MCP_CONSOLE_WEB_ADDRDerived address, port 7680Bind and advertised address for the bridge
MCP_CONSOLE_WEB_MAX_CONN4Concurrent browser connections per terminal
Setting
MCP_CONSOLE_MAX_TERMINALS
Default
50
Effect
Terminal admission check per client session
Setting
MCP_CONSOLE_MAX_ATTACHED_IDLE
Default
3600 seconds
Effect
Idle threshold for attached terminals
Setting
MCP_CONSOLE_MAX_DETACH_DURATION
Default
86400 seconds
Effect
Expiry threshold for detached persistent terminals
Setting
MCP_CONSOLE_RESOURCE_INTERVAL_MS
Default
2000
Effect
Default resource watch interval
Setting
MCP_CONSOLE_RESOURCE_DEFAULT_SUSTAINED_MS
Default
15000
Effect
How long a threshold breach lasts before an alert
Setting
MCP_CONSOLE_WEB
Default
Off
Effect
Enables the browser bridge
Setting
MCP_CONSOLE_WEB_ADDR
Default
Derived address, port 7680
Effect
Bind and advertised address for the bridge
Setting
MCP_CONSOLE_WEB_MAX_CONN
Default
4
Effect
Concurrent browser connections per terminal

Coordinate changes with the installation owner.