Skip to main content

The MCP Server

TermFlow ships a built-in MCP sidecar — a small local process that exposes the terminal to any Model Context Protocol client over streamable HTTP, so an AI agent can open terminals, split panes, run commands, and read output.

What the sidecar is​

The desktop app runs two cooperating local servers:

  • the API server (Axum, Rust) that actually owns the terminals, and
  • the MCP sidecar — a separate process that speaks MCP to your agent and translates each tool call into a call against that API.

Keeping MCP in its own process means the protocol surface your agent talks to is decoupled from the terminal engine. The sidecar is a thin bridge: it holds no terminal state of its own, it just forwards.

By default both servers bind to 127.0.0.1 (loopback only), so nothing outside your machine can reach them.

Endpoint and address​

In a normal installed build the sidecar listens here:

PropertyValue
MCP endpointhttp://127.0.0.1:42032/mcp
TransportStreamable HTTP (POST / GET for the SSE stream / DELETE on /mcp)
Health checkhttp://127.0.0.1:42032/health
Config key / server nameauto-terminal

The server key you write into a client config is auto-terminal (the sidecar advertises its own identity internally as auto-terminal-mcp, but the key you type is auto-terminal). This is the same identifier used in every generated config in Connect an Agent.

Dev vs. installed ports

The values above are for an installed build. When you run TermFlow from source with tauri dev, the sidecar moves to 42052 (and the API to 42051). You can also change the MCP port yourself in Settings → Connections (any value in 1024–65535). The rest of this page uses the installed defaults.

The /health endpoint is unauthenticated and always available — it is the cheapest way for a client (or you, with curl) to confirm the sidecar is up before attempting a connection.

curl http://127.0.0.1:42032/health

Environment variables​

The app launches the sidecar for you and passes it everything it needs through environment variables. You rarely set these by hand — they matter mainly if you run the sidecar standalone or are debugging why it can't reach the API.

VariableDefaultWhat it does
MCP_PORT42032Port the sidecar listens on
MCP_HOST127.0.0.1Bind address for the sidecar
AUTO_TERMINAL_API_URLhttp://localhost:42031Where the sidecar finds the TermFlow API server
AUTO_TERMINAL_TOKEN(none)Bearer token the sidecar uses when calling the API (preferred)
AUTO_TERMINAL_API_TOKEN(none)Same token, fallback name if AUTO_TERMINAL_TOKEN is unset
MCP_PARENT_PID(none)PID of the app; lets the sidecar exit if its parent goes away
AUTO_TERMINAL_INSTANCE_ID(none)Identifies which TermFlow instance this sidecar belongs to

The 7 tools​

The sidecar exposes exactly seven tools. Every tool that takes a terminal id also accepts the literal string "me", which resolves to the caller's own terminal (see Identity below).

ToolWhat it does
list_terminalsList the currently active terminals
create_terminalOpen a new terminal, optionally as a split pane in a given tab
execute_commandType a command into one or more terminals and submit it (fan-out to an array of ids)
get_terminal_outputRead back a terminal's output as clean text, with paging
get_terminal_detailGet metadata about a terminal (including its tabId)
get_my_terminalResolve the caller's own terminal via the identity header
close_terminalClose a terminal ("me" self-terminates)

This is an overview. For the full parameter list of each tool — types, which fields are required, and every default (for example create_terminal defaults to cols=120, rows=40, and execute_command's cliType defaults to copilot) — see the MCP Tools reference.

How clients connect​

Any client that supports a streamable-HTTP MCP server can connect by pointing at http://127.0.0.1:42032/mcp with the server key auto-terminal. TermFlow generates paste-ready configuration for three first-class clients:

Other MCP clients (Cursor, Goose, and anything else that speaks streamable HTTP) work too — point them at the same URL. aider doesn't speak MCP natively, so it needs a small wrapper. See Other MCP clients for the generic setup and the aider wrapper. The fastest way to get a correct config is the in-app Connect an AI agent modal under Settings → Connections, which fills in your actual port and token.

Authentication​

TermFlow's auth is deliberately quiet in the common case, and this is the honest picture:

  • In the default localhost-only mode, the sidecar is unauthenticated. Every request to /mcp is accepted. This is safe because the sidecar is bound to 127.0.0.1 — only processes already on your machine can reach it.
  • Auth is enforced only when you expose TermFlow on your LAN (Settings → Connections → "Expose on local network"). Once the servers bind to 0.0.0.0, a bearer token is required on every call.

The real credential is the authToken shown in Settings → Connections — a 64-hex string generated on first run, which you can reveal, copy, and rotate there. When a token is required, clients send it as an Authorization: Bearer <token> header; the sidecar itself receives the same token through the AUTO_TERMINAL_TOKEN environment variable so it can authenticate its own calls to the API.

The /health endpoint is always exempt, in every mode.

An honest note: The generated client configs always include the Authorization header for convenience, but on localhost that header is simply ignored. You only need it once "Expose on local network" is turned on. The full auth model — LAN exposure, token rotation, WebSocket ?token=, and one JWT endpoint the gate does not check — is covered in Local API and Auth.

Identity: the "me" shorthand​

When an agent runs inside a TermFlow terminal, that terminal injects a $TERMFLOW_TERMINAL_ID into its environment. If the client forwards that value as the X-Termflow-Terminal-Id header, the sidecar can tell which terminal the call is coming from. That is what makes get_my_terminal and the "me" shorthand work — an agent can operate on "its own" pane without ever being told the id.

The first-class client configs wire this header up for you where the client supports it. (Gemini CLI does not expand variables inside header values, so its generated config omits the identity header; you pass $TERMFLOW_TERMINAL_ID explicitly if you need it.)

Next steps​