Enabling & Configuring MCP
Turn on the local MCP server and connect an AI agent to it.
Enable the server
Go to Settings → MCP and toggle Enable MCP server. Ternux will:
- Generate a random bearer token (if one doesn't exist yet).
- Start listening on
127.0.0.1on the configured port (default7823).
| Field | Description |
|---|---|
| Enable MCP server | Starts/stops the local server. Only sessions open at call time are reachable — nothing is exposed while disabled. |
| Port | Local port the endpoint listens on (1024–65535). Can't be changed while the server is running — disable first. |
| Bearer token | Required on every request as Authorization: Bearer <token>. Use Copy to grab it, Regenerate to invalidate the old one and issue a new one. |
| Status | Shows Running on 127.0.0.1:<port> or Stopped. |
Regenerating the token immediately invalidates the old one — any connected agent will need the new token to keep working.
Auto-configure AI clients
Once the server is running, Ternux provides one-click setup for popular AI clients.
In Settings → MCP, look for the Add to Client buttons:
- Add to Claude (Claude Code CLI)
- Add to Cursor
- Add to OpenCode
- Add to Codex
Clicking these buttons will automatically append the correct configuration block (including your current bearer token) to the respective tool's configuration file.
Manual connection
If you are using a different MCP client, you can connect it manually. Point your MCP client at the local endpoint and supply the bearer token. For example, with Claude Code:
claude mcp add --transport http ternux http://127.0.0.1:7823/mcp \
--header "Authorization: Bearer <token>"Once connected, the client will see two tools — list_open_connections and run_command — described in Available Tools.
Headless connections
By default, an AI agent can only interact with sessions you have already opened. If you want to allow an agent to open a new session to a host in the background without opening a visible tab:
- Open the Edit Connection dialog for the desired host.
- Go to the Advanced tab.
- Check the Allow MCP headless execution box.
Disabling
Toggle Enable MCP server off in Settings → MCP. The server stops immediately and the endpoint stops accepting connections; already-open SSH tabs in Ternux are unaffected.