> 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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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