> 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/install-tempest-mcp-server-in-ai-clients.md).

# Install Tempest MCP Server in Claude Code, Codex, Cursor & More

Tempest ships a **Model Context Protocol (MCP) server** that exposes your saved SSH hosts, local shells, and Telnet sessions as tools any MCP-compatible AI agent can call. This guide walks through installing the server in each major MCP client — from one-line CLI registration in Claude Code, to JSON configuration in Cursor, to the YAML schema used by VS Code Continue.

If you want a feature overview of what the agent can do once connected (use cases, prompts, example sessions), read [AI Agents for Server Automation](/productivity/using-ai-agents-to-manage-servers.md) first. This page is the installation reference.

## Prerequisites

1. **Install Tempest** (desktop app or CLI) and make sure the `tempest` binary is on your `PATH`:

   ```bash
   tempest --version
   ```
2. **Log in and unlock your vault** — required for the saved-server tools to decrypt credentials locally:

   ```bash
   tempest login      # OAuth2 sign-in, stores token in ~/.tempest/auth.json
   tempest unlock     # cache the vault key for this session
   ```
3. Save at least one SSH host in Tempest so you can test the connection (Settings → Servers, or `tempest ssh add`).

No Node.js, Python, or `npx` proxy is required — the MCP server is compiled into the `tempest` binary.

## Choose a transport

Tempest implements both transports defined in the MCP specification. Pick whichever your client supports best:

| Transport      | When to use                                                                                                            | Command                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| **stdio**      | Default for almost every client. The client spawns `tempest mcp` as a child process and talks to it over stdin/stdout. | `tempest mcp`                                    |
| **HTTP / SSE** | When you want one long-running server shared by multiple clients, or when your client only supports HTTP MCP.          | `tempest mcp --http` (binds to `127.0.0.1:3456`) |

The HTTP transport listens on loopback only and is unauthenticated — do not expose it to a non-local network without putting an authenticating reverse proxy in front.

## Install in Claude Code

Register the server once with the Claude Code CLI:

```bash
claude mcp add tempest -- tempest mcp
```

To make it available in every project, install it globally:

```bash
claude mcp add --scope user tempest -- tempest mcp
```

For the HTTP transport (start `tempest mcp --http` first):

```bash
claude mcp add --transport http tempest http://127.0.0.1:3456/mcp
```

Verify the registration:

```bash
claude mcp list
```

In a Claude Code session, type `/mcp` to see the active servers and their tools.

## Install in Codex CLI

Edit `~/.codex/config.toml` (or `.codex/config.toml` at your project root) and add:

```toml
[mcp_servers.tempest]
command = "tempest"
args    = ["mcp"]
```

For the HTTP transport:

```toml
[mcp_servers.tempest]
type = "sse"
url  = "http://127.0.0.1:3456/sse"
```

Restart any open Codex session — on next launch, Codex spawns `tempest mcp` automatically and the tools become available to the model.

## Install in Claude Desktop

Open **Claude → Settings → Developer → Edit Config**, which opens `claude_desktop_config.json`. Add a `mcpServers` entry:

```json
{
  "mcpServers": {
    "tempest": {
      "command": "tempest",
      "args": ["mcp"]
    }
  }
}
```

Save the file and fully quit Claude Desktop (⌘Q on macOS), then reopen. The 🔌 icon in the input box should now list `tempest` and its tools.

If Claude Desktop reports `spawn tempest ENOENT`, use the absolute path returned by `which tempest` (typical: `/usr/local/bin/tempest` or `/opt/homebrew/bin/tempest`) as the `command` value.

## Install in Cursor

Open **Cursor → Settings → Tools & MCP → Add new MCP server**. Cursor writes to `~/.cursor/mcp.json`; paste:

```json
{
  "mcpServers": {
    "tempest": {
      "command": "tempest",
      "args": ["mcp"]
    }
  }
}
```

Reopen the MCP panel and toggle `tempest` on. Cursor's Composer (`⌘I`) and Agent mode will pick up the tools.

## Install in VS Code (GitHub Copilot Chat)

Open the Command Palette and run **MCP: Add Server**. Choose **Command (stdio)** when prompted, then enter:

* **Command:** `tempest`
* **Arguments:** `mcp`
* **Server ID:** `tempest`

This appends an entry to `.vscode/mcp.json` (project-scoped) or your User `settings.json` under `"mcp.servers"`. Copilot Chat's Agent mode will list the new tools in its picker.

## Install in VS Code (Continue extension)

Continue uses YAML. Edit `~/.continue/config.yaml`:

```yaml
mcpServers:
  - name: tempest
    command: tempest
    args:
      - mcp
```

Reload the Continue panel and the tools appear under the **Tools** tab.

## Install in Zed

Open the Command Palette → **agent: add context server**, or edit `~/.config/zed/settings.json` directly:

```json
{
  "context_servers": {
    "tempest": {
      "source": "custom",
      "command": "tempest",
      "args": ["mcp"]
    }
  }
}
```

Open the Assistant panel and the Tempest tools will be available in agent mode.

## Install in OpenCode

Add to `opencode.json` at your project root (or `~/.config/opencode/opencode.json` for global):

```json
{
  "mcp": {
    "tempest": {
      "type": "local",
      "command": "tempest",
      "args": ["mcp"]
    }
  }
}
```

## Install in Windsurf

Open **Windsurf → Settings → Cascade → MCP Servers → Edit raw config** and add:

```json
{
  "mcpServers": {
    "tempest": {
      "command": "tempest",
      "args": ["mcp"]
    }
  }
}
```

Hit **Refresh** in the MCP panel.

## Install in any other MCP client

Most clients accept either a stdio command or an HTTP URL. For Tempest the values are:

* **stdio:** `command = tempest`, `args = ["mcp"]`
* **HTTP / SSE:** start `tempest mcp --http` and point the client at `http://127.0.0.1:3456/mcp` (streamable HTTP) or `http://127.0.0.1:3456/sse` (SSE).

Tempest implements the MCP 2024-11-05 specification.

## Verify the installation

After registering the server in your client, ask the model:

> List my saved SSH servers.

The agent should call `list_ssh_servers` and return your vault entries. If that works, try:

> Connect to `<one of your hosts>` and run `uptime`.

You'll see the agent call `ssh_connect_saved`, `feed_from_terminal`, and `feed_from_session` in sequence.

## Tools exposed by the server

| Tool                   | Purpose                                                                     |
| ---------------------- | --------------------------------------------------------------------------- |
| `list_ssh_servers`     | List saved SSH hosts (id, name, group, host:port) — no credentials returned |
| `ssh_connect_saved`    | Open SSH session to a saved host, credentials decrypted locally             |
| `ssh_connect`          | Open SSH session to an ad-hoc host (user/host/auth supplied inline)         |
| `telnet_connect_saved` | Open Telnet session to a saved host                                         |
| `local_shell_start`    | Spawn a local bash / zsh / fish / pwsh shell in a PTY                       |
| `feed_from_terminal`   | Send keystrokes to a session — commands, control codes, arrow keys          |
| `feed_from_session`    | Snapshot the rendered terminal screen, including TUI layouts                |
| `list_sessions`        | List all open sessions and their state                                      |
| `resize`               | Resize a session's PTY                                                      |
| `disconnect`           | Close a session and free resources                                          |

For prompt patterns and full use-case walkthroughs, see [AI Agents for Server Automation](/productivity/using-ai-agents-to-manage-servers.md).

## Troubleshooting

**`spawn tempest ENOENT` / `command not found`.** The client's PATH does not include the directory holding the `tempest` binary. Use the absolute path from `which tempest` as the `command` value, or launch the client from a shell where `tempest --version` works.

**Tools return `vault is locked`.** Run `tempest unlock` in a terminal before starting the agent session, or enable the OS keyring integration in **Settings → Vault → Keyring** so the key persists between launches.

**HTTP transport refuses the connection.** Confirm `tempest mcp --http` is running and printed `listening on 127.0.0.1:3456`. If you changed the port, update the client URL to match (`--port 4000` → `http://127.0.0.1:4000/mcp`).

**Saved-server tools are missing but `local_shell_start` works.** You're logged out or your token expired. Run `tempest login` and try again.

**The agent connects but its commands "hang."** Some interactive prompts (sudo password, `yes/no`, pager) wait for input. Ask the agent to call `feed_from_session`, observe the prompt, and respond with the matching `feed_from_terminal` payload (e.g. `"y\r"`).

## Security notes

* **Credentials never leave your device.** The MCP server decrypts vault entries locally; the AI only ever sees server metadata (name, group, host:port) and terminal output.
* **Prefer SSH agent authentication.** With keys loaded into `ssh-agent`, no secret material flows through any tool call.
* **Audit destructive tool calls.** Each client surfaces tool calls before executing them — review `feed_from_terminal` payloads when the agent is about to run `rm`, `systemctl stop`, `DROP TABLE`, etc. Codex CLI's `--approval-policy cautious`, Claude Code's confirmation prompt, and Cursor's per-tool approval all serve this purpose.
* **The HTTP transport trusts localhost.** Do not expose `tempest mcp --http` beyond `127.0.0.1` without an authenticating reverse proxy.

## See also

* [AI Agents for Server Automation — Codex, Claude Code & OpenCode](/productivity/using-ai-agents-to-manage-servers.md) — use cases, example prompts, and what the agent can actually do once installed
* [Tempest AI Assistant](/productivity/tempest-ai-assistant.md) — the in-app chat panel that lives next to your terminal
* [Self-Hosted Tempest Server & Web Mode](/deployment/self-hosted-tempest-server.md) — share one MCP server across a team
* [Where Tempest Stores Your Credentials](/account-and-privacy/where-tempest-stores-credentials.md) — vault encryption details