Skip to main content

Overview

Connecting an AI agent to TermFlow means pointing an MCP client at TermFlow's built-in MCP server so the agent can open terminals, split panes, run commands, and read output. This page shows the authoritative way to do it and where each client's step-by-step guide lives.

TermFlow ships no AI and sells no AI usage — you bring your own agent and your own keys. Agents connect as clients over the Model Context Protocol; TermFlow is the terminal they drive.

The one server URL you need​

Every MCP client connects to the same local endpoint:

http://127.0.0.1:42032/mcp
  • 42032 is the default MCP port for the installed app (the REST + WebSocket API runs separately on 42031).
  • The server speaks streamable HTTP — a single /mcp endpoint handling POST, GET (SSE), and DELETE.
  • Both the host and port are overridable in Settings → Connections. If you change the MCP port, use your value in the URL above.
tip

Don't hand-write the config from memory. TermFlow generates it for you — read on.

The authoritative way: the Connect modal​

The source of truth for connection config is the in-app Connect modal:

Settings → Connections → "Connect an AI agent"

The modal generates paste-ready configuration for your client, already filled in with your current host, port, and auth token. This matters because the exact key names, header shapes, and token differ per client — copying from the modal removes the guesswork.

+--------------------------------------------------------------+
|  Connect an AI agent                                    [ x ] |
+--------------------------------------------------------------+
|  Server URL   http://127.0.0.1:42032/mcp                     |
|                                                              |
|  Choose your client:                                         |
|   ( ) Claude Code   ( ) Codex CLI   ( ) Gemini CLI           |
|                                                              |
|  +--------------------------------------------------------+  |
|  |  { generated config for the selected client }          |  |
|  |                                              [ Copy ]   |  |
|  +--------------------------------------------------------+  |
|                                                              |
|  Auth token is included automatically when needed.           |
+--------------------------------------------------------------+
info

The modal lives inside the Connections settings tab, alongside the port fields, the "Expose on local network" toggle, and the auth token controls. See Settings → Connections & Network for the full panel.

Three first-class clients​

TermFlow generates copy-paste config for three clients. Each writes the same server, keyed as auto-terminal, but into a different file with a different schema:

ClientConfig fileServer keyGuide
Claude Code.mcp.jsonauto-terminalClaude Code
Codex CLIconfig.tomlauto-terminalCodex CLI
Gemini CLIsettings.jsonauto-terminalGemini CLI

All three point at http://127.0.0.1:42032/mcp. The differences that matter:

  • Claude Code expands ${VAR} inside header values, so it can carry the identity header (see below) directly.
  • Codex CLI uses a dedicated env_http_headers mechanism to inject the identity header from an environment variable.
  • Gemini CLI does not env-expand header values, so the identity header is omitted from its generated config.

Everything else is a generic MCP client​

Any client that supports a streamable-HTTP MCP server works too — point it at the same URL. Editors and tools like Cursor and Goose fall here, and aider works through an MCP wrapper. There's no generated config for these, but nothing special is required beyond the server URL. See Other MCP Clients.

An honest note: Only Claude Code, Codex CLI, and Gemini CLI get generated, paste-ready config from the Connect modal. "Other MCP clients" are honestly framed as also works because they speak MCP — not as first-class, pre-templated integrations.

Authentication: usually nothing to do​

In the default localhost-only mode, the MCP server is bound to 127.0.0.1 and every endpoint is unauthenticated. This is safe precisely because it is reachable only from your own machine — no token is required to connect.

Authentication is enforced only when you turn on "Expose on local network" in Settings → Connections. In that mode the server binds to 0.0.0.0 and every request must carry a Bearer token:

Authorization: Bearer <token>

The real credential is the authToken shown (masked, with reveal / copy / rotate) in Settings → Connections — the same token the Connect modal drops into your generated config. When you expose on LAN, copy the config again so the token is included.

warning

The Authorization header is optional on localhost and required once you expose the server on your LAN. If a remote agent gets 401/403, it's almost always a missing or stale Bearer token — re-copy the config from the modal after rotating.

For the full auth model — how the token is generated, when it's checked, and how rotation behaves — see Local API & Auth.

The identity header: how an agent finds "its own" terminal​

When an agent runs inside a TermFlow terminal, that terminal injects a $TERMFLOW_TERMINAL_ID environment variable. Passing it back to the server via the identity header lets the agent identify the terminal it's living in:

X-Termflow-Terminal-Id: ${TERMFLOW_TERMINAL_ID}

With this header set, the agent can call the get_my_terminal tool — or use the "me" shorthand anywhere a terminal id is expected — to read, write, or close its own terminal without first listing and guessing which one it is.

  • Claude Code carries this header in its generated config (it expands ${VAR}).
  • Codex CLI injects it via env_http_headers.
  • Gemini CLI omits it (no header env-expansion); pass $TERMFLOW_TERMINAL_ID explicitly if a tool needs it.

How it fits together​

The agent talks only to the MCP server; the server bridges to TermFlow's local API, which owns the actual terminals and panes.

Prefer raw HTTP instead?​

If you're building your own orchestrator rather than connecting an existing agent, you can skip MCP entirely and drive TermFlow over its REST + WebSocket API. See The REST/WS alternative.

Next steps​