> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/productivity/using-ai-agents-to-manage-servers.md). # AI Agents for Server Automation (Codex, Claude Code, OpenCode) Tempest ships a built-in **MCP (Model Context Protocol) server** that gives any compatible AI agent a full SSH terminal. The agent can open sessions to your saved servers, type commands, read the rendered screen, drive interactive TUIs (htop, vim, dialog), and close connections — all over the same tool protocol that Claude Desktop, Codex CLI, and OpenCode understand natively. No shell scripts. No Ansible playbooks for one-off tasks. Just describe what you want, and the agent handles the keystrokes. ## How it works ``` ┌─────────────┐ MCP (stdio / HTTP) ┌──────────────────────┐ │ AI agent │ ←────────────────────────→ │ tempest mcp server │ │ (Codex CLI, │ tool calls & results │ │ │ Claude, │ │ ssh_connect │ │ OpenCode…) │ │ feed_from_terminal │ └─────────────┘ │ feed_from_session │ │ list_ssh_servers │ │ … (15 tools total) │ └──────────┬───────────┘ │ libssh2 / PTY ▼ ┌──────────────────────┐ │ your remote host │ └──────────────────────┘ ``` The MCP server runs locally on your machine and acts as the SSH client. Credentials stay in your encrypted Tempest vault — the AI only ever sees server names and terminal output, never passwords or private keys. ## Setup This page focuses on what the agent can do once it's connected. For step-by-step installation in Claude Code, Codex CLI, Claude Desktop, Cursor, VS Code, Zed, OpenCode, and other MCP clients — plus prerequisites, transport options, the full tool reference, and troubleshooting — see [Install Tempest MCP Server in Claude Code, Codex, Cursor & More](/productivity/install-tempest-mcp-server-in-ai-clients.md). The short version: `claude mcp add tempest -- tempest mcp` (Claude Code), or the equivalent config entry in your client. Then ask the agent *"List my saved SSH servers"* to confirm it's wired up. ## Practical examples ### Check disk usage across all your servers Prompt: > List my saved SSH servers, connect to each one, run `df -h`, and give me a table of filesystem usage. Flag any filesystem over 80%. The agent will: 1. Call `list_ssh_servers` to enumerate your vault. 2. For each host, call `ssh_connect_saved` → `feed_from_terminal` (`"df -h\r"`) → `feed_from_session` to read the output. 3. `disconnect` when done. 4. Summarize results in a markdown table. ### Restart a failing systemd service Prompt: > SSH into my web-01 server and restart the nginx service. Show me the journal output after restart and confirm it's running. The agent will: 1. `list_ssh_servers` → pick `web-01` → `ssh_connect_saved`. 2. `feed_from_terminal`: `"sudo systemctl restart nginx\r"`. 3. `feed_from_session` to read any password or error prompts; respond if needed. 4. `feed_from_terminal`: `"sudo journalctl -u nginx -n 50 --no-pager\r"`. 5. `feed_from_session` → paste output back to you. 6. `disconnect`. ### Investigate a full disk Prompt: > My db-02 server is reporting a full disk. SSH in and find what's taking up space under /var. ``` du -sh /var/* | sort -rh | head -20 ``` The agent runs the command, reads the screen, drills down into the largest directory, and proposes what to clean up — all without you touching a terminal. ### Drive an interactive TUI Prompt: > Open htop on my dev server and tell me which process is consuming the most CPU right now. The agent: 1. `ssh_connect_saved` → dev server. 2. `feed_from_terminal`: `"htop\r"`. 3. Waits \~300ms, then calls `feed_from_session`. 4. Reads the rendered htop grid — process list, CPU bars, memory gauges — and summarizes the top consumer. 5. Sends `"q"` to quit, then `disconnect`. `feed_from_session` returns the terminal screen **as rendered** (cursor position, alternate-screen flag, styled text with color annotations). The agent sees exactly what you would see. ### Batch deploy a config change to multiple servers Prompt: > Update /etc/sysctl.conf on all my "production" group servers to set net.core.somaxconn=4096, then reload without rebooting. The agent opens sessions in sequence (or asks if you want parallel), runs `echo` / `tee` / `sysctl -p`, reads each server's output, and reports which hosts succeeded. ## Tips for writing effective prompts **Name your servers clearly.** The agent calls `list_ssh_servers` and picks by name. A server named `db-primary-us-east` is easier to reason about than `srv-04`. **Prefer saved servers over ad-hoc credentials.** `ssh_connect_saved` keeps credentials out of the conversation entirely — the vault decrypts locally. If you must use `ssh_connect` with a password, the password will appear in the agent's tool call log. **Ask the agent to disconnect when done.** Sessions leak resources if left open. A prompt like *"clean up all connections when finished"* is enough. **For long-running commands**, tell the agent to wait before reading: *"Run the backup script and give it 60 seconds before checking the output."* The agent can send the command, tell you it's waiting, then call `feed_from_session` after the delay. ## Auditing the agent at runtime Most agent CLIs show tool calls before executing them — Codex CLI's `--approval-policy auto` vs. `cautious`, Claude Code's confirmation prompt, Cursor's per-tool approval. Review the `feed_from_terminal` calls before approving, especially for destructive operations (`rm`, `systemctl stop`, `DROP TABLE`). For broader credential and transport-level security, see the [Security notes](/productivity/install-tempest-mcp-server-in-ai-clients.md#security-notes) in the installation guide and [Reset Your Tempest Password](/account-and-privacy/resetting-password.md) for vault key rotation. ## See also * [Install Tempest MCP Server in Claude Code, Codex, Cursor & More](/productivity/install-tempest-mcp-server-in-ai-clients.md) — full installation reference for every MCP client * [Tempest AI Assistant](/productivity/tempest-ai-assistant.md) — built-in chat panel for ad-hoc questions in an open terminal tab * [SSH Snippets & Scheduled Commands](/productivity/snippets-scheduled-runs.md) — run recurring commands on a schedule without an AI agent * [Self-Hosted Tempest Server & Web Mode](/deployment/self-hosted-tempest-server.md) — host the MCP server on a remote machine for team use * [Where Tempest Stores Your Credentials](/account-and-privacy/where-tempest-stores-credentials.md) — vault encryption details