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

Step-by-step guide to install the Tempest MCP server in Claude Code, Codex CLI, Claude Desktop, Cursor, VS Code (Copilot & Continue), Zed, OpenCode, and any other Model Context Protocol-compatible AI

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 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:

   tempest --version

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

   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:

claude mcp add tempest -- tempest mcp

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

claude mcp add --scope user tempest -- tempest mcp

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

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

Verify the registration:

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:

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

For the HTTP transport:

[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:

{
  "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:

{
  "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:

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:

{
  "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):

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

Install in Windsurf

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

{
  "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.

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 — use cases, example prompts, and what the agent can actually do once installed

• Tempest AI Assistant — the in-app chat panel that lives next to your terminal

• Self-Hosted Tempest Server & Web Mode — share one MCP server across a team

• Where Tempest Stores Your Credentials — vault encryption details