Skip to main content

Claude Code

Connect Anthropic's Claude Code CLI to TermFlow's MCP server so the agent can open terminals, split panes, run commands, and read output — including its own terminal via the "me" shorthand.

Before you start

You need TermFlow 0.1.0 running, and its MCP server listening on the default port 42032. TermFlow ships no AI and no keys — you bring your own Claude Code install and your own Anthropic credentials. Claude Code is simply an MCP client that drives TermFlow.

Get your connection details​

The in-app Connect modal is the source of truth for the exact URL and token. In TermFlow:

  1. Open Settings → Connections.
  2. Click Connect an AI agent.
  3. Choose the Claude Code tab.

The modal shows a paste-ready .mcp.json block with the live values already filled in — the MCP URL (http://127.0.0.1:42032/mcp by default) and, if you've enabled LAN access, your bearer token. You can also reveal and copy the token directly from Settings → Connections (it's the authToken, masked by default).

Where the token comes from

The credential TermFlow checks is the config authToken shown in Settings → Connections — a 64-character hex string generated on first run. That is the only value you ever paste into the Authorization header.

Add the MCP server​

Claude Code reads a project-scoped .mcp.json from the root of your project. Create (or edit) that file and add the auto-terminal server:

{
  "mcpServers": {
    "auto-terminal": {
      "type": "http",
      "url": "http://127.0.0.1:42032/mcp",
      "headers": {
        "Authorization": "Bearer <token>",
        "X-Termflow-Terminal-Id": "${TERMFLOW_TERMINAL_ID}"
      }
    }
  }
}

Replace <token> with the value from the Connect modal (or drop the Authorization header entirely on localhost — see below). The server key auto-terminal is the identifier Claude Code and the tools use; keep it as-is.

FieldValueWhat it does
mcpServers.auto-terminalserver keyNames this MCP server. Leave it as auto-terminal.
type"http"Uses TermFlow's streamable-HTTP MCP transport.
urlhttp://127.0.0.1:42032/mcpThe MCP endpoint. 42032 is the default prod MCP port; change it only if you overrode it in Settings → Connections.
headers.AuthorizationBearer <token>Bearer credential. Required only when TermFlow is exposed on the LAN (see below).
headers.X-Termflow-Terminal-Id${TERMFLOW_TERMINAL_ID}Identity header that lets get_my_terminal and the "me" shorthand resolve this agent's own terminal.

How ${VAR} expands​

Claude Code expands ${VAR} references inside header values at load time. So "${TERMFLOW_TERMINAL_ID}" is replaced with the value of the TERMFLOW_TERMINAL_ID environment variable in Claude Code's process.

That variable is injected automatically into any terminal TermFlow spawns. When you launch Claude Code inside a TermFlow terminal, the header carries that terminal's id, and the MCP tools can identify the terminal the agent is running in:

If you run Claude Code somewhere without that variable set, the identity header simply expands to an empty value — the other MCP tools still work, but get_my_terminal has no terminal of its own to resolve.

When is the Authorization header required?​

TermFlow enforces the bearer token only when the server is exposed on the LAN (Settings → Connections → "Expose on local network"). In the default localhost-only mode, every endpoint is unauthenticated — which is safe precisely because the server is bound to 127.0.0.1 and unreachable from other machines.

ModeBind hostAuthorization header
Localhost (default)127.0.0.1Optional — token is not checked. You can omit the header.
Exposed on LAN0.0.0.0Required — paste the token from the Connect modal.
Keep it simple on localhost

On a single machine you can drop the Authorization header entirely and connect with just the url and the identity header. Add the token only when you turn on LAN exposure.

Verify the connection​

  1. Save .mcp.json and start (or restart) Claude Code from a TermFlow terminal.
  2. Confirm Claude Code lists the auto-terminal server as connected.
  3. Ask Claude Code to call get_my_terminal.

If everything is wired up, get_my_terminal returns the details of the very terminal Claude Code is running in — proof that the MCP transport, the URL, and the X-Termflow-Terminal-Id identity header are all working. From there the agent can call list_terminals, create_terminal, execute_command, and the rest of the toolset.

An honest note: get_my_terminal only resolves a terminal when Claude Code runs inside a TermFlow terminal, because that's where TERMFLOW_TERMINAL_ID is injected. Launch Claude Code from an ordinary OS terminal and it can still drive TermFlow (create terminals, run commands), but it has no "own" terminal to return.

Next steps​