Connect Claude Code End-to-End

A start-to-finish walkthrough: install TermFlow, hand Claude Code the connection config from the in-app Connect modal, and watch the agent identify and drive its own terminal.

What you'll learn

By the end of this tutorial you will have:

TermFlow 0.1.0 installed and running, with its MCP server listening on the default port 42032.
Claude Code connected to TermFlow's auto-terminal MCP server via a project-scoped .mcp.json.
Verified the wiring by having Claude Code call get_my_terminal and get back the details of the very terminal it's running in.
Watched Claude Code run a real command in a TermFlow pane and read the output back.

TermFlow ships no AI

TermFlow is a terminal that AI agents drive — it bundles no model and no keys. You bring your own Claude Code install and your own Anthropic credentials. Claude Code is simply an MCP client that connects to TermFlow's local MCP server.

Prerequisites

You need	Notes
TermFlow 0.1.0 installed	See Installation. First launch starts the MCP server on `127.0.0.1:42032`.
Claude Code installed	Anthropic's CLI, with your own Anthropic credentials configured. TermFlow does not provide these.
A project folder	Claude Code reads a project-scoped `.mcp.json` from the root of the folder you launch it in.

Time: about 10 minutes.

The end-to-end picture

Steps

1. Install and launch TermFlow

Download the installer for your OS from https://termflow.app/download, run it, and open TermFlow. If you already have it, just launch it. See Installation for platform details.

On launch, TermFlow starts two local interfaces bound to 127.0.0.1: the REST + WebSocket API on port 42031 and the MCP server on port 42032. Those defaults are what Claude Code will connect to.

Verify the server is healthy

Open Settings → Connections and look at the health status dot. Healthy means the API and MCP servers are up. If it reads conflict, another instance already owns the port — see Troubleshooting.

The in-app Connect modal is the source of truth for your exact URL and token — never hand-copy these from the docs.

Open Settings (press Ctrl/Cmd+,).
Go to the Connections tab.
Click Connect an AI agent.
Choose the Claude Code tab.

+--------------------------------------------------------------+
|  Connect an AI agent                                    [ X ] |
+--------------------------------------------------------------+
|  [ Claude Code ]  [ Codex CLI ]  [ Gemini CLI ]  [ Other ]   |
|                                                              |
|  Add this to your project's .mcp.json:                       |
|  +--------------------------------------------------------+  |
|  |  { "mcpServers": { "auto-terminal": {                  |  |
|  |      "type": "http",                                   |  |
|  |      "url": "http://127.0.0.1:42032/mcp", ...          |  |
|  |  } } }                                        [ Copy ]  |  |
|  +--------------------------------------------------------+  |
+--------------------------------------------------------------+

The modal fills in the live MCP URL (http://127.0.0.1:42032/mcp by default) and, if you've enabled LAN access, your bearer token.

3. Copy the `.mcp.json` into your project

Click Copy in the modal, then create (or edit) a .mcp.json file at the root of your project and paste it in. It looks like this:

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

Field	Value	What it does
server key	`auto-terminal`	Names the MCP server. Keep it exactly as-is — it's the identifier the tools use.
`type`	`"http"`	Uses TermFlow's streamable-HTTP MCP transport.
`url`	`http://127.0.0.1:42032/mcp`	The MCP endpoint. `42032` is the default prod MCP port; change it only if you overrode it in Settings → Connections.
`headers.Authorization`	`Bearer <token>`	Bearer credential. Only required when TermFlow is exposed on the LAN.
`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.

Two things worth knowing:

On localhost, the token is optional. TermFlow only enforces the bearer token when you turn on "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. You can drop the Authorization header entirely on a single machine.
Claude Code expands ${VAR} inside header values at load time, so "${TERMFLOW_TERMINAL_ID}" becomes the value of that environment variable in Claude Code's process. TermFlow injects TERMFLOW_TERMINAL_ID into every terminal it spawns — which is what makes the next step work.

4. Start Claude Code from a TermFlow terminal

This is the step that makes the identity header meaningful. Open a terminal inside TermFlow (a new tab or pane), cd into your project folder, and start Claude Code there:

cd /path/to/your/project
claude

Because you launched it from a TermFlow terminal, Claude Code inherits that terminal's TERMFLOW_TERMINAL_ID, and the identity header now carries a real id.

The first time Claude Code sees a project-scoped .mcp.json, it will ask you to approve the auto-terminal server — approve it. Then confirm it connected by listing MCP servers in Claude Code (its /mcp command) and checking that auto-terminal shows as connected.

5. Verify with `get_my_terminal`

Ask Claude Code to call the get_my_terminal tool. In plain language:

Call the get_my_terminal tool and tell me the terminal id.

get_my_terminal takes no parameters — it resolves the caller's own terminal from the X-Termflow-Terminal-Id header. If the wiring is correct, it returns the details of the exact terminal Claude Code is running in (including its tabId). That single successful call proves three things at once: the MCP transport works, the URL is right, and the identity header is being read.

6. Run a command in a TermFlow pane

Now let the agent drive the terminal. Ask Claude Code to run a command in its own terminal:

Use execute_command to run echo hello from termflow in terminal "me", then read the output back with get_terminal_output.

Under the hood the agent calls execute_command with terminalId: "me" and your command. That call is asynchronous — it submits the command and returns immediately — so the agent then calls get_terminal_output to read what the pane produced. You'll see the command run live in the TermFlow pane, and Claude Code will report the captured output.

tip

"me" works everywhere a terminal id is expected

Every TermFlow MCP tool accepts the string "me" as shorthand for the caller's own terminal — so the agent never has to look up its own id first. It can also target other terminals by their real id, or fan a command out to several at once by passing an array of ids to execute_command.

Expected results

When everything is connected you should be able to check off all of these:

Claude Code's server list shows auto-terminal as connected.
get_my_terminal returns a terminal id and tabId — matching the TermFlow terminal you launched Claude Code in.
execute_command on "me" makes text appear in that TermFlow pane, and get_terminal_output returns it.
The agent can go on to call list_terminals, create_terminal, get_terminal_detail, and close_terminal — the full toolset described in the MCP tools reference.

Troubleshooting

Symptom	Likely cause	Fix
`auto-terminal` not listed in Claude Code	`.mcp.json` isn't at the project root, or you didn't approve the server	Confirm the file is in the folder you launched `claude` from; re-run and approve the project MCP server prompt.
Server listed but connection fails	Wrong port, or MCP server not running	Check Settings → Connections: health dot should read healthy, and the MCP port should match the `url` (default `42032`).
`get_my_terminal` returns nothing / no own terminal	Claude Code wasn't launched inside a TermFlow terminal, so `TERMFLOW_TERMINAL_ID` isn't set	Start Claude Code from a TermFlow tab or pane (Step 4). Other tools still work without it — only the "me" identity needs it.
Auth / unauthorized error	TermFlow is exposed on the LAN, which requires the token	Paste the bearer token from the Connect modal into the `Authorization` header. On plain localhost the token isn't checked and the header is optional.
Health dot reads conflict	Another instance already owns port `42031`/`42032`	Close the other instance, or change the ports in Settings → Connections and update the `url` in `.mcp.json` to match.

An honest note: Hosting Claude Code inside TermFlow as a managed panel is on the roadmap, not shipped. Today the flow is exactly what this tutorial describes — you run your own Claude Code process (in a TermFlow terminal so it inherits its terminal id), and it connects out to TermFlow's MCP server. TermFlow provides the terminal and the tools; you provide the agent and the keys.

Next steps

Connect an agent · Claude Code — the reference page for the config fields and the localhost-vs-LAN auth model.
Fan a command to many panes — put execute_command's array/batch fan-out to work across several terminals at once.

What you'll learn​

Prerequisites​

The end-to-end picture​

Steps​

1. Install and launch TermFlow​

2. Open the Connect modal​

3. Copy the .mcp.json into your project​

4. Start Claude Code from a TermFlow terminal​

5. Verify with get_my_terminal​

6. Run a command in a TermFlow pane​

Expected results​

Troubleshooting​

Next steps​