# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.gotempest.app/productivity/using-ai-agents-to-manage-servers.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.