MCP Console
Generated identifiers, timings and machine details vary.
Run a command
Run a command and inspect the result.
You want your agent to run a command and tell you whether it worked, not guess from what it printed.
Capturedmcp-console 0.13.4
YouRun the command and tell me its exit code.
Tool callterminal_run { "command": "printf 'hello-console\\n'; echo exit-check; uname -sm", "timeout": 10 }
What happensExit code 0, timedOut false, duration 0.028 seconds, output hello-console, exit-check and Linux x86_64; the terminal was created for the run and closed after it (ephemeral true).
AgentIt ran in about 30 milliseconds and exited with code 0. It printed hello-console and exit-check, and the machine is Linux on x86_64.
Keep a shell
Keep a shell across several steps.
A task takes several commands that depend on each other: move to a directory, set a variable, then use both.
Capturedmcp-console 0.13.4
YouWork in a shell of your own for this task and keep its state.
Tool callterminal_open { "name": "guide-demo", "shell": "bash", "size": { "cols": 100, "rows": 30 } }
What happensA running bash terminal named guide-demo, 100 columns by 30 rows, with its own session id.
Tool callterminal_send { "session": "<id>", "text": "cd /tmp && export GREETING=kept && echo \"state: $GREETING in $(pwd)\"", "enter": true, "await": { "until": "stable", "ms": 300 } }
What happensThe send succeeds and the returned screen change reads: state: kept in /tmp.
Tool callterminal_close { "session": "<id>" }
What happensThe terminal is terminated; the exit code reported for a close is synthetic.
AgentI worked in one shell, it kept /tmp and the variable between commands, and I closed it afterwards.
Long output
Read a long output without filling the conversation.
A build prints thousands of lines and you only care about one of them.
Capturedmcp-console 0.13.4
YouRun it and find the line for 1500.
Tool callterminal_run { "command": "seq 1 3000", "timeout": 10 }
What happensExit code 0 and truncated true: the output is cut to a head and a tail, about 12.8 kilobytes are marked omitted out of 16,893 in total, and a runId comes back with the note that the rest can be read in run_output mode.
Tool callterminal_read { "mode": "run_output", "runId": "<runId>", "filter": "^1500" }
What happensReturns the one matching line, 1500, with truncated false.
AgentThe command printed 3,000 lines. The line you asked about is there: 1500.
The capture is kept in memory, per connection, in a bounded store, so read what you need soon after the run; a restart or eviction makes it unavailable.
Screen and history
Read the right part of the screen.
A command printed more than fits on the screen, and the agent needs the part that scrolled away without losing its place.
Capturedmcp-console 0.13.4
YouPrint 25 lines in a small terminal and show me the first ones too.
Tool callterminal_open { "name": "guide-reads", "shell": "bash", "size": { "cols": 80, "rows": 10 } }
What happensA running bash terminal 80 columns by 10 rows.
Tool callterminal_send { "session": "<id>", "text": "for i in $(seq 1 25); do echo \"line-$i\"; done", "enter": true, "await": { "until": "stable", "ms": 400 } }
What happensThe send succeeds and the returned change ends with line-25 and the prompt.
Tool callterminal_read { "session": "<id>", "mode": "screen" }
What happensThe ten visible rows: line-17 to line-25 and the prompt.
Tool callterminal_read { "session": "<id>", "mode": "scrollback", "range": [0, 6], "format": "lines" }
What happensThe first six retained lines: the command that was typed and line-1 to line-5.
Tool callterminal_read { "session": "<id>", "mode": "incremental" }
What happensAll finished lines since the cursor were returned in one read, from the typed command to line-25; reading incrementally again at once returns empty content.
AgentThe screen shows only line-17 to line-25. The earlier lines are in the history, and the incremental read gave me everything new once, so a second read is empty.
Interactive programs
Talk to a program that asks questions.
A program waits for input: a Python prompt, an installer, a database client.
Illustrative conversation
YouOpen Python, compute 21 times 2 and tell me what it printed.
Tool callterminal_open { "name": "console-repl", "shell": "bash", "command": "python3" }
What happensA terminal is created and Python is started in it; the call does not wait for the prompt.
Tool callterminal_read { "session": "<id>", "mode": "screen" }
What happensThe screen shows the Python banner and the >>> prompt.
Tool callterminal_send { "session": "<id>", "text": "print(21 * 2)", "enter": true, "await": { "until": "pattern", "pattern": ">>>\\s*$" } }
What happensThe send succeeds and the screen change shows 42 followed by a new prompt.
AgentPython printed 42. I will exit Python and close this terminal now.
Tool callterminal_send { "session": "<id>", "text": "exit()", "enter": true }
Tool callterminal_close { "session": "<id>" }
What happensInspect the cleanup result and remaining terminal list.
Background job
Start a server, carry on and look back.
A task needs a server or a long build running while the agent does something else.
Illustrative conversation
YouStart the dev server in the background and tell me if it gets heavy.
Tool callterminal_run { "command": "npm run dev", "background": true, "cwd": "/work/app" }
What happensReturns at once with a runId and the terminal's session id; the server keeps running in that terminal.
Tool callterminal_read { "session": "<id>", "mode": "tail", "lines": 20 }
What happensThe last lines show the server listening on its port.
Tool callterminal_stats { "session": "<id>", "detail": true }
What happensCPU as a share of the whole machine, memory, thread and process counts, and the heaviest processes in the terminal.
AgentThe observed output says the server is listening. I will inspect the actual resource sample and keep checking until we finish.
Tool callterminal_close { "session": "<id>" }
What happensAt the agreed end of the task, inspect cleanup and the server's own shutdown observation.
Hand over
Hand a terminal to the next connection.
A long job runs in a terminal, and the connection that started it is about to end.
Illustrative conversation
YouKeep that build running and let the next session pick it up.
Tool callterminal_open { "name": "release-build", "persistent": true, "tags": ["release"], "command": "make build" }
What happensA persistent terminal is created and the build starts in it.
Tool callterminal_close { "session": "<id>", "detach": true }
What happensThe terminal is marked detached and its process keeps running; disable any browser link with
web: false before the handoff.Tool callterminal_open { "attach": true, "tags": ["release"] }
What happensFrom the next connection, action attached: the detached terminal is owned by this connection.
Tool callterminal_read { "session": "<id>", "mode": "screen" }
What happensThe screen shows the build still running.
AgentI took over the release build. It is still running, so I will not start it again.
Share a terminal
Let a person watch or type.
You want to see what the agent is doing in a terminal, or step in yourself.
Illustrative conversation
YouOpen a terminal I can watch in my browser.
Tool callterminal_open { "name": "shared-shell", "web": true }
What happensA terminal is created and the result includes an attach link for the browser. This works only when the service owner has enabled the web bridge.
AgentThe shell is open and the link is in the result. Anyone with that link can type into it, so please do not post it anywhere. When you are finished I will disable the link.
Tool callterminal_open { "session": "<id>", "web": false }
What happensThe link is disabled. To end browser access at once, close the terminal with
terminal_close, and inspect its result.