Reference · MCP tools

MCP tools reference.

Termalin exposes its SSH client as MCP tools an agent can call. There are two surfaces: the local server bundled with the desktop app (termalin-mcp, over stdio) with 22 tools, and the hosted endpoint at https://termal.in/api/v1/mcp with a cloud subset of 8. This page lists every one — its parameters, its limits, and whether it reads or changes state. For the overview and setup, start at the MCP server page.

Which tool on which surface

Six tools share a name across both surfaces (hosts_list, generate_password, ssh_exec, sftp_list, data_query, data_tables); file reads and writes are named differently, and the session, tunnel, live-terminal and database-inspection tools are local only.

Tool	Local	Hosted	Effect	What it does
hosts_list	✓	✓	Reads	List the servers the agent may reach
generate_password	✓	✓	Reads	Return a strong random password
ssh_exec	✓	✓	Changes	Run one command and return its output
session_open	✓	—	Changes	Open a persistent SSH session
session_exec	✓	—	Changes	Run a command in an open session
session_close	✓	—	Changes	Close a session
session_list	✓	—	Reads	List the agent’s open sessions
tunnel_open	✓	—	Changes	Open a local or SOCKS port forward
tunnel_close	✓	—	Changes	Close a port forward
tunnel_list	✓	—	Reads	List open port forwards
sftp_list	✓	✓	Reads	List a directory over SFTP
sftp_get	✓	—	Reads	Read a file over SFTP (local)
sftp_put	✓	—	Changes	Write a file over SFTP (local)
sftp_read	—	✓	Reads	Read a text file over SFTP (hosted)
sftp_write	—	✓	Changes	Write a text file over SFTP (hosted)
terminal_hosts	✓	—	Reads	List saved hosts the agent could open
terminal_sessions	✓	—	Reads	List the user’s open terminal tabs
terminal_open	✓	—	Changes	Open a live terminal tab in the app
terminal_run	✓	—	Changes	Run a command in an open tab
terminal_run_many	✓	—	Changes	Run one command across several tabs
data_list	✓	—	Reads	List the app’s saved database connections
data_tables	✓	✓	Reads	List tables / collections / keys
data_schema	✓	—	Reads	Describe one table’s columns
data_query	✓	✓	Reads *	Run a query and return rows

* data_query is read-only by default; a write runs only with a full-access key (hosted) or a connection that grants the agent full access (local).

Servers & passwords

hosts_list local · hosted

List the servers the agent may reach. No parameters. Local: returns id, name, hostname, port, username and auth type — no secrets. Hosted: returns id, name, whether the server is online, and the default login user. Reads.

generate_password local · hosted

Return one strong random password — handy when creating a user or setting a password. Parameter: length (optional, default 20, clamped 8–128). Nothing is stored. Reads.

Running commands

ssh_exec local · hosted

Run a single shell command on a server and return its combined output. Each call is a fresh connection, so cd and shell variables don’t carry between calls — chain with cd /path && cmd. Required: host, command. Hosted adds optional username (defaults to the tunnel’s user, else root) and timeoutSeconds (default 60, up to 300). Honours the host’s agent policy. Changes state.

Persistent sessions local only

session_open local

Open a persistent SSH session and keep it connected, so follow-up commands skip the auth handshake. It is the agent’s own headless connection — no app needed. Required: host. Returns a sessionId. A blocked host refuses. Changes state.

session_exec local

Run a command on an open session and return its output. Each command still runs on a fresh channel, so cwd/env don’t persist. Required: session, command. An allowlist host is re-checked per command. Changes state.

session_close local

Close a persistent session and disconnect it. Required: session. Changes state.

session_list local

List the persistent sessions the agent currently has open. No parameters. Returns sessionId, hostId and host. Reads.

Port forwards local only

tunnel_open local

Open a port forward on an open session. Required: session. type is local (default — a local port that reaches remoteHost:remotePort as the server sees it; needs remoteHost and remotePort) or dynamic (a local SOCKS5 proxy that egresses from the server). localPort optional (0 picks a free one). Returns a tunnelId and the local listenAddr. Allowed on full-access hosts only, so an allowlist host can’t be turned into a pivot. Changes state.

tunnel_close local

Close a port forward. Required: tunnel. Changes state.

tunnel_list local

List the port forwards currently open. No parameters. Returns tunnelId, sessionId, kind, listenAddr and target. Reads.

Files over SFTP

sftp_list local · hosted

List a directory over SFTP. Required: host. Local also requires path and returns name, path, isDir, size, permissions and modified time. Hosted makes path optional (defaults to the login home, .) and adds optional username. Reads.

sftp_get local

Read a file over SFTP. Required: host, path. UTF-8 text comes back as text; binary comes back base64. Capped at 4 MB — MCP results travel into a model’s context, so reads stay modest. The hosted equivalent is sftp_read. Reads.

sftp_put local

Write a file over SFTP, creating or overwriting it. Required: host, path, content. Optional base64 writes decoded binary. Allowed on full-access hosts only. The hosted equivalent is sftp_write. Changes state.

sftp_read hosted

Read a text file over SFTP and return its contents. Required: host, path. Optional username. Files over 512 KB or non-text (binary) files are refused — use ssh_exec (tail, sed) for those. Reads.

sftp_write hosted

Create or overwrite a text file over SFTP. Required: host, path, content (written as UTF-8). Optional username. Capped at 512 KB; for binary uploads use a terminal or scp. Changes state.

The live desktop app local only

These drive the running desktop app through its consent-gated control server. terminal_hosts and terminal_sessions need “Agent in Terminal” enabled; terminal_open, terminal_run and terminal_run_many need the “Let agents run commands” consent.

terminal_hosts local

List the saved hosts the agent could open a session for. No parameters. Returns hostId, name, connectionType, authMethod and canOpenHeadless (false means opening it needs you — a password or a locked key). Reads.

terminal_sessions local

List the terminal tabs you currently have open that the agent can act in. No parameters. Returns tabId, hostId, title, connected and attached. Reads.

terminal_open local

Open a new terminal session for a host on the agent’s own initiative — a background tab in your app that glows so you can see it’s the agent’s. Required: hostId. Hosts needing a password or a locked key open but stay unconnected until you finish. Changes state.

terminal_run local

Run a command in one of your open terminal tabs, as if you typed it; the tab glows while the agent acts. Required: tabId, command. Optional timeoutSeconds (default 120, up to 3600 — set it generously for builds). Returns the captured output. Changes state.

terminal_run_many local

Run the same command across several open tabs at once (mass operations, Ansible-style). Required: tabIds (array), command. Optional timeoutSeconds (default 120, up to 3600). Returns per-session output or error. Changes state.

Databases

The local data tools work the saved “Data” connections in the app (id from data_list) and need the app running and unlocked; they’re off by default and read-only unless a connection grants full access. The hosted data tools work a server’s own database client over the keyless tunnel (host id from hosts_list), using the database’s local trust — no database password is sent or stored.

data_list local

List the saved database connections (PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, ClickHouse, MongoDB, Redis, Elasticsearch, RabbitMQ, Cassandra, Neo4j, InfluxDB). No parameters. Returns each connection’s id, name, engine and whether the agent may write. Reads.

data_tables local · hosted

List the tables / collections / keys of a database. Local: required hostId (from data_list), optional database. Hosted: required host (from hosts_list), optional engine (postgres default, or mysql/mariadb/redis/mongodb/sqlite), database, username. Reads.

data_schema local

Describe one table’s columns (name, type, nullable, primary key). Required: hostId, table. Optional schema, database. Reads.

data_query local · hosted

Run a query and return the rows, in the connection’s own language (SQL, a Redis command, a MongoDB shell expression, Cypher, InfluxQL, and so on). Local: required hostId, query; optional database, maxRows (default 200). Hosted: required host, query; optional engine (postgres default), database, username, allowWrites (full-access keys only), timeoutSeconds (default 60, up to 300). Read-only by default — only SELECT/SHOW-style statements run unless writes are granted.

Connect an agent

Point your client at whichever surface matches where the agent runs — the local server for hosts you export from the app, the hosted endpoint for servers enrolled with a Connector.

• Claude Code — claude mcp add termalin -- <path>/termalin-mcp
• Cursor and Codex — one entry in the client’s MCP config pointing at the same binary
• claude.ai and ChatGPT — the OAuth connector at termal.in/mcp
• Any HTTP client — an API key against https://termal.in/api/v1/mcp

FAQ

MCP overview → · SSH for AI agents → · Database client →