MCP Tool Reference

The toolset is published as Cndctr Terminal, version 1.0. Every tool delegates to the editor subsystem that owns the real implementation.

Addressing a terminal

Two different conventions, and mixing them up is the most common mistake:

• SplitActivePane and CloseActivePane act on the active host — the status-bar panel drawer when it is open, otherwise an open terminal tab. They take no index.
• Everything else takes a TerminalIndex, which is 0-based: 0 is Terminal 1, 1 is Terminal 2, and so on, up to 3.

Call ListTerminals() first. It is the only reliable way to learn which indices are live and what the session names actually are.

Return value contract

There are two kinds of tool, and they do not share a contract.

Action tools return a status string beginning OK: or Failed:. Check the prefix. SplitActivePane, CloseActivePane, NotifyUser, CreateSession, SwitchSession, SendKeys, SetTerminalSetting.

Read tools return their data directly, with no prefix. ListTerminals and GetTerminalSettingsJson return JSON; GetDebugSummary returns a summary line; ReadTerminalOutput returns text; GrepTerminalOutput returns matching lines or No matches for '<pattern>'.

From any tool, a string beginning Failed: is an error.

---

Layout

SplitActivePane(Orientation)

Split the focused pane of the active terminal, adding a sibling pane with its own shell. Follows the same code path as the toolbar split buttons and never opens a new window.

Parameter	Type	Notes
Orientation	string	"Horizontal" (side by side) or "Vertical" (stacked)

Returns OK: ... or Failed: ....

CloseActivePane()

Close the focused pane of the active terminal — the same action as the close button.

Returns OK: ... or Failed: ....

---

Sessions

ListTerminals()

List the open terminal tabs and their sessions. Call this first. It is how you discover valid TerminalIndex values and the backend session names SwitchSession needs.

{
  "maxTerminals": 4,
  "tabs": [
    {
      "index": 0,
      "activeSession": "T1_2",
      "workspaceMode": "PSMuxWorkspace",
      "workspaceName": "cndctr-T1",
      "sessions": ["T1_1", "T1_2"]
    }
  ]
}

CreateSession(TerminalIndex)

Start a fresh session in a numbered tab, using that tab’s current shell/workspace profile.

Parameter	Type	Notes
TerminalIndex	int32	0-based

SwitchSession(TerminalIndex, SessionName)

Point a numbered tab at an already-tracked session, addressed by its internal name.

Parameter	Type	Notes
TerminalIndex	int32	0-based
SessionName	string	Internal name from ListTerminals, e.g. "T1_2" — not the display label

---

Input and output

SendKeys(TerminalIndex, Data)

Feed raw input straight to a tab’s PTY.

Parameter	Type	Notes
TerminalIndex	int32	0-based
Data	string	Raw bytes/text sent verbatim

No newline is added

SendKeys does not append anything. To submit a command line you must include \r yourself.

And OK: means the bytes were sent — nothing more. It does not mean the command ran, succeeded, or printed what you expected. Follow up with ReadTerminalOutput or GrepTerminalOutput if you need to know what happened.

ReadTerminalOutput(TerminalIndex, MaxLines)

Read the tail of a tab’s output — visible screen plus scrollback — as plain text. This is how the agent sees.

Parameter	Type	Notes
TerminalIndex	int32	0-based
MaxLines	int32	Newest last. <= 0 uses the default of 200; capped at 2000

Returns the captured text, or Failed: ... when there is no readable buffer.

GrepTerminalOutput(TerminalIndex, Pattern)

Return only the lines containing a substring, case-insensitively, each prefixed with its logical row number. Cheaper than pulling the whole buffer when you know what you are looking for.

Parameter	Type	Notes
TerminalIndex	int32	0-based
Pattern	string	Substring, case-insensitive. Not a regular expression

Returns matching row: text lines (capped at 200), No matches for '<pattern>', or Failed: ....

---

Talking to the human

NotifyUser(Title, Body)

Show a non-intrusive toast in the bottom-right of the Unreal Editor. Use it when you have finished something, or you are blocked and need input.

Parameter	Type	Notes
Title	string	Short headline, e.g. "Build finished". Length-bounded
Body	string	Optional detail line, e.g. "12 files compiled, 0 errors". May be empty

It does not raise or focus any window, and it has no click action — it is purely informational. Identical messages within a few seconds are de-duplicated, so call it once per event rather than polling.

A user preference is not a failure

If the user has turned agent notifications off, the call still returns OK: ... (nothing shown). That is their choice, not an error. Do not retry, and do not report it as a problem.

---

Settings

GetTerminalSettingsJson()

Serialise the current terminal settings to a JSON object string.

SetTerminalSetting(PropertyName, Value)

Assign a value to a setting and persist it to disk.

Parameter	Type	Notes
PropertyName	string	A property name from the Settings Reference
Value	string	Imported through UE reflection — "14" for an int, "true" for a bool, an enum member name for an enum

SetTerminalSetting("FontSize", "16")
SetTerminalSetting("bShowTopBars", "false")
SetTerminalSetting("WorkingDirectoryPolicy", "EngineRoot")

GetDebugSummary(TerminalIndex)

A terse, read-only status snapshot of one tab. Includes among other things psmuxResolved=1|0, which is how the agent’s skill knows whether PSMux Workspace mode is available.

---

A workflow that works

1. ListTerminals() — discover tabs and session names. GetDebugSummary(0) for a deeper look at one tab.
2. SplitActivePane — lay out the panes you need, e.g. one for a build, one for logs.
3. CreateSession / SwitchSession to manage shells; SendKeys to type.
4. ReadTerminalOutput or GrepTerminalOutput after anything you sent — SendKeys alone tells you nothing about the result.
5. CloseActivePane to tear down when finished.
6. NotifyUser when you need the human, once per event.