MCP Tools

The complete reference for the seven tools TermFlow's built-in MCP server exposes — the exact input schema, defaults, and behavior of each — so any MCP client can drive your terminals with confidence.

TermFlow ships a built-in MCP server (a small sidecar process) that speaks the Model Context Protocol over streamable HTTP. Any MCP client — Claude Code, Codex CLI, Gemini CLI, or another compatible client — connects to it and gets these seven tools. TermFlow bundles no AI of its own: you bring your own agent and your own keys, and the agent uses these tools as a client.

The server at a glance

Property	Value
Server name	auto-terminal-mcp
Transport	Streamable HTTP (POST / GET SSE / DELETE on /mcp)
Endpoint URL (prod)	http://127.0.0.1:42032/mcp
Health check	GET /health
Default MCP port	42032 (dev: 42052)
Backs onto	TermFlow's REST API at http://127.0.0.1:42031

The MCP server is a thin bridge: every tool call translates into a request against the local REST API. You do not talk to it with raw HTTP requests yourself — your MCP client does, using the config generated by the in-app Connect an AI agent modal. See The MCP server for how the pieces fit together, and Connect an agent → Overview for setup.

Localhost is unauthenticated by design

In the default localhost-only mode, the server is bound to 127.0.0.1 and every tool call is unauthenticated — safe precisely because nothing off your machine can reach it. A bearer token is required only when you turn on Expose on local network in Settings → Connections. See Local API and auth.

Environment variables

The sidecar is configured through environment variables. You rarely set these by hand — TermFlow launches the sidecar for you — but they are useful to know when running the server standalone or debugging.

Variable	Default	Purpose
MCP_PORT	42032	Port the MCP server listens on
MCP_HOST	127.0.0.1	Bind host
AUTO_TERMINAL_API_URL	http://localhost:42031	REST API the tools call into
AUTO_TERMINAL_TOKEN	—	Bearer token (preferred)
AUTO_TERMINAL_API_TOKEN	—	Bearer token (fallback)
MCP_PARENT_PID	—	Parent process to track for lifecycle
AUTO_TERMINAL_INSTANCE_ID	—	Identifies the TermFlow instance

The "me" shorthand

Anywhere a tool expects a terminalId, you can pass the literal string "me" instead of a real id. It resolves to the terminal the calling agent is running inside.

This works because TermFlow injects a $TERMFLOW_TERMINAL_ID into each terminal's environment, and MCP clients forward it as the X-Termflow-Terminal-Id header. When a tool sees "me", it maps that header back to the caller's own terminal.

Why this matters

An agent launched inside a TermFlow pane can read its own scrollback with get_terminal_output using terminalId: "me", run a command in itself with execute_command, or even close itself with close_terminal — all without ever having to discover its own id first. Use get_my_terminal when you want the full detail object instead of just referring to it inline.

Tool summary

Tool	Required inputs	What it does
list_terminals	(none)	List all active terminals
create_terminal	(none)	Open a new terminal (optionally split a pane)
execute_command	terminalId, command	Run a command in one or many terminals
get_terminal_output	terminalId	Read clean scrollback text
get_terminal_detail	terminalId	Get one terminal's full detail
get_my_terminal	(none)	Resolve the caller's own terminal
close_terminal	terminalId	Close a terminal

---

list_terminals

Lists every active terminal in the running TermFlow instance. Use it to discover terminal ids before acting on them.

Parameters: none.

{ "name": "list_terminals", "arguments": {} }

---

create_terminal

Opens a new terminal. With no arguments it creates a fresh tab using the default shell profile. Provide tabId/paneId and a direction to split an existing pane instead of opening a new tab.

Parameter	Type	Required	Default	Notes
name	string	No	—	Display name for the terminal
profile	string	No	—	Shell profile id to launch
cols	number	No	120	Initial column count
rows	number	No	40	Initial row count
cwd	string	No	—	Working directory to start in
tabId	string	No	—	Target tab when splitting
paneId	string	No	—	Pane to split from
direction	horizontal | vertical	No	—	Split direction

Split direction:

• horizontal → splits to the right (new pane beside the current one).
• vertical → splits to the bottom (new pane below the current one).

MCP vs REST defaults differ

create_terminal defaults to 120×40. The equivalent REST endpoint (POST /api/terminals) defaults to 80×24. If you mix the two interfaces, set cols/rows explicitly to avoid surprises. See Terminals.

{
  "name": "create_terminal",
  "arguments": {
    "name": "build",
    "cwd": "/work/app",
    "tabId": "tab-1",
    "paneId": "pane-3",
    "direction": "vertical"
  }
}

---

execute_command

Runs a command in one terminal — or fans the same command out to many terminals at once. The call is asynchronous: it submits the command and returns immediately without waiting for the command to finish. Read the result afterward with get_terminal_output.

Parameter	Type	Required	Default	Notes
terminalId	string | string[]	Yes	—	One id, or an array to fan out
command	string	Yes	—	The command text to run
cliType	default | claude | gemini | chatgpt | copilot	No	copilot	How the input is submitted
useBracketedPaste	boolean	No	—	Wrap input in bracketed-paste markers

Batch fan-out. Pass an array of terminal ids to terminalId and the same command is dispatched to each of them. This is how you drive several agents or panes in parallel from a single call. See the tutorial Fan a command to many panes.

cliType. Different agent CLIs expect input to be submitted differently (for example, how a newline or submit keystroke is sent). cliType selects the submission style; the default is copilot. Choose the value that matches the CLI running in the target terminal.

{
  "name": "execute_command",
  "arguments": {
    "terminalId": ["term-1", "term-2", "term-3"],
    "command": "git pull --rebase",
    "cliType": "default"
  }
}

tip

Because the call returns right away, a typical loop is: execute_command → wait briefly → get_terminal_output to check what happened.

---

get_terminal_output

Reads a terminal's scrollback as clean, terminal-escape-free text. Supports paging so you can pull just the tail or walk back through history.

Parameter	Type	Required	Default	Notes
terminalId	string	Yes	—	Terminal to read (or "me")
lines	number	No	50	Number of lines to return
offset	number	No	0	Paging offset; 0 = the last lines

The response returns the cleaned text in a raw field, alongside totalLines and the offset used. An offset of 0 gives you the last lines lines (the most recent output); increase the offset to page further back through history.

{
  "name": "get_terminal_output",
  "arguments": { "terminalId": "me", "lines": 100, "offset": 0 }
}

---

get_terminal_detail

Returns the full detail object for a single terminal, including its tabId. Use it when you need more than the summary from list_terminals — for example, to learn which tab a terminal belongs to before splitting it.

Parameter	Type	Required	Default	Notes
terminalId	string	Yes	—	Terminal to inspect (or "me")

{ "name": "get_terminal_detail", "arguments": { "terminalId": "term-1" } }

---

get_my_terminal

Resolves the terminal the calling agent is running inside and returns its detail. It uses the X-Termflow-Terminal-Id identity header that the MCP client forwards from the terminal's environment.

Parameters: none.

{ "name": "get_my_terminal", "arguments": {} }

An honest note: get_my_terminal only works when the agent is actually running inside a TermFlow terminal and its client forwards the identity header. An external client with no terminal of its own has no "me" to resolve — use list_terminals to pick a target instead.

---

close_terminal

Closes a terminal. Pass "me" to have the caller terminate its own terminal.

Parameter	Type	Required	Default	Notes
terminalId	string	Yes	—	Terminal to close; "me" = self-terminate

{ "name": "close_terminal", "arguments": { "terminalId": "me" } }

warning

Closing a terminal ends its shell process. Any unsaved work in that session is lost. When an agent closes "me", it terminates the very terminal it is running in.

Next steps

• Connect an agent → Overview — generate paste-ready config and point your client at http://127.0.0.1:42032/mcp.
• REST & WebSocket alternative — the same actions over plain HTTP when you are building your own tooling instead of using an MCP client.