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

# Use Tempest in AI Agents (Desktop or CLI)

Give your AI client access to Tempest through MCP. Use Desktop to watch and share live terminals, or CLI to let the AI manage its own sessions without the app.

Stay in your preferred AI client — Claude Code, Codex, Cursor, OpenCode, or another MCP-compatible client — and ask it to connect to your servers, run commands, read terminal output, and transfer files through Tempest. MCP is the connection that gives your agent these tools.

There are two ways to connect. **Use Desktop if you want to work alongside the AI. Use CLI if you want the AI to manage the sessions itself.**

Want to chat with an AI agent inside the Tempest app instead? See [Use AI Agents in Tempest](/ai-and-automation/using-ai-agents-to-manage-servers.md).

## Choose Desktop or CLI

|                                 | Tempest Desktop MCP                                                                 | Tempest CLI MCP                                                                      |
| ------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| How you work                    | You and the AI share live terminal sessions in Tempest.                             | The AI opens and controls its own sessions.                                          |
| What you see                    | Commands and output appear in the app in real time. You can take over.              | Results appear in your AI client. Sessions are independent of Desktop tabs.          |
| Does Desktop need to stay open? | Yes. The MCP server runs inside the app.                                            | No. The AI client starts a separate `tempest mcp` process.                           |
| Setup                           | Enable the app's HTTP MCP server and copy the client configuration.                 | Install the CLI and register `tempest mcp` in your AI client.                        |
| Best for                        | Troubleshooting together, watching progress, and handing a terminal back and forth. | Delegating a task, working across several servers, or using Tempest without the app. |

Both modes can use saved servers and interactive terminals, including programs such as `htop` and `vim`. The difference is who manages the sessions and whether you share them in the app.

## Option 1: Desktop — work alongside the AI

1. Open Tempest Desktop, sign in, and unlock your vault.
2. Go to **Settings → AI → Tempest MCP Server** and turn the server on.
3. Under **Client Setup**, choose your client and copy its configuration. Use **Manual** for other clients that accept HTTP MCP configuration.
4. Restart your AI client or start a new session. Keep Tempest open while you use it.

For example, the **Codex** snippet goes in `~/.codex/config.toml`:

```toml
[mcp_servers.tempest]
url = "http://127.0.0.1:PORT/mcp?token=YOUR_TOKEN"
```

Use the actual URL copied from Tempest. It includes the listening port and access token; the default port is assigned automatically. If you want the URL to stay the same across restarts, set a fixed port in the MCP settings and save it.

Ask your agent:

> List the open Tempest terminal sessions. Use my web-01 session, run uptime, and explain the result.

When the agent uses an open Tempest terminal, you can watch its commands and output in the app. To take over, ask the agent to pause, then continue in that terminal yourself. Ask it to use your existing session when you want to work together; separately created MCP sessions may not appear as app tabs.

The access token grants access to your Tempest tools. Keep the copied configuration private. Desktop requires this token and listens on localhost by default.

## Option 2: CLI — let the AI manage the sessions

Install the [Tempest CLI](/cli/tempest-cli.md), then check it is available and unlock your saved servers:

```bash
tempest --version
tempest login
tempest unlock
tempest ssh list
```

Save hosts in the Tempest app first if you do not already have any. Desktop and CLI share the local account and vault; CLI sessions still run independently of the app.

Configure a **local/stdio** MCP server in your AI client with command `tempest` and arguments `["mcp"]`. For example:

**Claude Code:**

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

**Codex:**

```bash
codex mcp add tempest -- tempest mcp
```

Or add this to `~/.codex/config.toml`:

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

Restart your AI client or start a new session. The client launches the MCP process automatically; you do not need to run `tempest mcp` in another terminal or keep Desktop open. No Node.js or `npx` is needed for the Tempest CLI MCP server.

Ask your agent:

> List my saved SSH servers. Connect to web-01, check disk usage, and report the result. Disconnect when finished.

The AI owns the connection, runs the commands, reads the output, and closes the session. You follow its progress in your AI client; these sessions do not appear as shared Desktop tabs. Your AI client's tool approval settings still apply.

Register one mode under the server name `tempest`. To switch modes, replace its configuration and restart your AI session. In Codex, this means replacing the `[mcp_servers.tempest]` entry.

For Codex configuration details, see the [official MCP documentation](https://developers.openai.com/codex/mcp).

## Client configuration reference

Use the configuration format your client expects. Both modes work with MCP-compatible clients that support the corresponding transport.

**Desktop:** copy the appropriate snippet from Tempest's **Client Setup** section. For a client with a manual HTTP setup, use the copied URL including its token and select **Streamable HTTP**.

For Claude Code, the copied command looks like:

```bash
claude mcp add --transport http tempest "http://127.0.0.1:PORT/mcp?token=YOUR_TOKEN"
```

For clients that accept `mcpServers` JSON with HTTP entries, use:

```json
{
  "mcpServers": {
    "tempest": {
      "type": "http",
      "url": "http://127.0.0.1:PORT/mcp?token=YOUR_TOKEN"
    }
  }
}
```

Replace the placeholder URL with the one copied from Tempest.

**CLI:** configure a local/stdio MCP server with command `tempest` and arguments `["mcp"]`.

For example, clients that use `mcpServers` JSON, such as Claude Desktop and Cursor, accept:

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

If the client cannot find `tempest`, replace the command with the executable's absolute path.

## Optional: run CLI MCP over HTTP

CLI MCP normally uses stdio: your AI client starts the process and communicates with it directly. If your client requires HTTP, you can instead start:

```bash
tempest mcp --http 127.0.0.1:3456
```

Then configure `http://127.0.0.1:3456/mcp` as a Streamable HTTP server in your client. For example, in Codex:

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

Keep that process running. This is still **CLI mode**: using HTTP does not attach it to Desktop or make its sessions visible in the app. Use `/mcp` with Streamable HTTP, not `/sse`.

Unlike Desktop's HTTP server, standalone CLI HTTP has no transport access token. Keep it on localhost; exposing it to a network requires an authenticating proxy.

## Troubleshooting

* **Desktop connection fails:** check that Tempest is open and its MCP server is running. Copy the client configuration again if the port or token changed.
* **`401 Unauthorized` from Desktop:** use the URL including the token from Client Setup, or send the token as `Authorization: Bearer <token>` if your client supports headers.
* **`command not found` / `spawn tempest ENOENT`:** the AI client cannot find the CLI. Use the executable's absolute path as `command`.
* **Vault is locked or saved hosts are missing:** sign in to the intended account and unlock its vault. For CLI, run `tempest login`, `tempest unlock`, and check `tempest ssh list` before restarting the AI session.
* **A command is waiting:** ask the AI to read the current terminal screen. A password prompt, confirmation, or pager may need input.

## Security notes

Saved-server credentials are decrypted locally by Tempest, so the agent can connect without you pasting passwords or private keys into chat. Server metadata, terminal output, and files the agent reads can still be sent to its model provider. Anything you type into the AI conversation is also visible to that provider.

External AI clients control their own tool approvals. Seeing an action in a Desktop terminal is not an approval gate. Review your client's settings before delegating changes to a server.

See [Storm AI Security Model](/ai-and-automation/tempest-ai-security-model.md) and [Where Tempest Stores Your Credentials](/accounts-vaults-and-privacy/where-tempest-stores-credentials.md) for more detail.