MCP Server

Give AI agents like Claude Code, Cursor, and Windsurf direct access to your fleet — across AWS, OVH Cloud, Hetzner Cloud, and custom hosts — through a typed, audited tool surface with three guard tiers and an explicit confirmation protocol on mutating calls.

What is MCP?

Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI assistants connect to external tools and data sources. Think of it as a plugin system for AI agents.

Servonaut ships an MCP server in two flavours:

• Local stdio (free) — servonaut --mcp exposes the CLI's own tool surface to an agent running on the same machine.
• Hosted (Solo & Teams) — agents connect to mcp.servonaut.dev over HTTPS+SSE, and the backend relays calls back to your own CLI over a secure, authenticated relay channel. The agent can be on a colleague's laptop or in CI — but commands always run with your SSH keys, on your machine. The backend never holds your SSH keys or cloud credentials — it stores only references your CLI resolves locally.

No setup at all: the TUI's built-in AI chat

If you just want an AI assistant working on your servers, you don't need to wire up an external agent. Run servonaut and press F2 — the built-in AI chat panel opens alongside whichever screen you're on, with tool-calling against your instances drawn from the same catalog documented below (most tools are available in chat; a minority, such as raw file transfer, are reserved for the MCP surface). It works with your own provider keys (OpenAI, Anthropic, Gemini, Ollama — configure them under Tools → Settings) or with the hosted Servonaut AI gateway on Solo and Teams plans; your remaining quota and top-up balance are shown inline, and you can switch provider per-session from the panel header. The active instance's server memory is injected into the conversation automatically, with a staleness banner.

Chat tool calls go through the same guard levels as everything else. Dangerous-tier tools are never offered in chat unless your account has the dangerous-AI-tools opt-in — enforced server-side and in the client. The rest of this page is for connecting external agents — Claude Code, Cursor, CI jobs — to the same guarded, audited tool surface.

Quick install

The fastest way to wire Servonaut into your agent of choice is the auto-installer. It detects supported clients (Claude Code, Claude Desktop, Cursor, Windsurf, VS Code, OpenCode) and writes the right config block.

Install from the MCP Registry

Servonaut is listed in the official MCP Registry as dev.servonaut/servonaut, so any registry-aware MCP client or aggregator can discover and install it directly. The registry launch command runs the server straight from PyPI:

Agent-only / headless install

No TUI required — you can install Servonaut purely as an MCP backend for your coding agent. The MCP server runs fully headless: servonaut --mcp never loads the terminal UI, so it works on a server or CI box with no display and no interactive session.

Configure credentials and servers the same way as a TUI install — edit ~/.servonaut/config.json directly (see the Configuration reference). Everything an agent does goes through the same guard levels and is logged to ~/.servonaut/mcp_audit.jsonl, exactly as on a full install.

To connect a Servonaut Cloud account (config sync, hosted MCP relay, Servonaut AI), run servonaut login — a fully headless OAuth device flow. It prints a verification URL and short code; approve in any browser on any device (--no-browser skips the local browser launch, --force re-authenticates over an existing session). Tokens are stored at ~/.servonaut/auth.json (permissions 0600) and shared by every CLI subcommand, the MCP server, and the TUI — sign in once per machine. servonaut logout revokes the session and removes the stored token.

Manual setup

Each client stores its MCP config in a different file. The simplest path is to let the auto-installer figure it out: servonaut --mcp-install <client> writes the correct block in the correct file. Common locations:

• Claude Code: ~/.claude.json
• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• VS Code: ~/.config/Code/User/mcp.json on Linux. The location differs on macOS and Windows — run servonaut --mcp-install vscode and it writes the correct file for your OS.

The MCP server block itself is the same in every file:

{
  "mcpServers": {
    "servonaut": {
      "command": "servonaut",
      "args": ["--mcp"],
      "env": {}
    }
  }
}

After saving the file, restart the agent. The Servonaut tools appear in the tools panel.

Available tools

The catalog is grouped into ten families: core relay, AWS observability & security, AWS EC2, Amazon S3, incident response & diagnostics, Hetzner Cloud, OVH Cloud, Server Memory, orchestration, and session & backend. The list is filtered to what's actually usable for you: by plan, by guard level, and by configuration — Hetzner and OVH tools appear only when those providers are configured, IP-ban tools only when a ban target is defined, and memory tools only when server memory is enabled. The Hetzner Cloud, OVH Cloud, and Server Memory families are included with the Solo and Teams plans; the AWS and diagnostics families need only a paid plan, since AWS is the base provider.

The exact set returned by tools/list depends on your plan, configuration, and guard level — call it from your agent to see the live catalog.

Core relay (6)

AWS observability & security (9)

CloudWatch log analysis, CloudTrail audit lookup, and IP-ban management — relayed to your CLI, which runs them against your own AWS credentials. AWS is the base provider, so these need only a paid plan.

AWS EC2 (11) Solo & Teams

EC2 inventory reads and instance lifecycle, relayed to your CLI and run against your own AWS credentials. AWS is the base provider, so these need only a paid plan.

Amazon S3 (10) Solo & Teams

S3 bucket and object operations across providers (AWS, plus S3-compatible Hetzner / OVH object storage) — the cloud is chosen per call.

Incident response & diagnostics (12) Solo & Teams

Fast triage and mitigation when a host is under load or misbehaving: fleet-wide health, on-box traffic analysis, AWS ingress-path mapping, database and RDS diagnostics, IP enrichment, scoped WAF mitigation, and zero-config database-credential setup. Read tools need only a paid plan; the mitigation tools are dangerous tier. Discovered database passwords go straight into your configured secrets backend on your machine (local store or Bitwarden Secrets Manager — check with servonaut secrets status) and are never returned to the agent.

Hetzner Cloud (11) Solo & Teams

OVH Cloud (13) Solo & Teams

Server Memory (6) Solo & Teams

Agents should call get_server_memory first, before any SSH round-trip — the cached snapshot answers OS / runtime / service / container / log questions instantly. See Server Memory docs.

Orchestration (4) Solo & Teams

Higher-level, cross-cloud building blocks that compose the per-provider tools.

Session & backend (5)

Introspection and plumbing tools an agent can use to understand its own session and reach your servonaut.dev account.

Guard levels

Guard levels let you control how much power AI agents have over your infrastructure. Set the level in config.json.

Two backstops apply regardless of guard level: run_command always refuses a hard-coded blocklist of catastrophic shell commands (rm -rf, shutdown, dd, and similar), and dangerous-tier tools require the dangerous-AI-tools opt-in on your account before Servonaut AI surfaces will offer them at all.

Confirmation protocol on mutating tools

Every mutating MCP tool's description carries a one-line instruction telling the LLM to confirm with the user before invoking it. For example, hetzner_delete_server's description ends with: "Always confirm with the user before invoking this tool — deletion is permanent and the server's data cannot be recovered." The server's top-level instructions reinforce this with a three-step protocol: summarise the exact change in plain language, state the tool name and arguments, and wait for an explicit affirmative reply before calling.

On Teams plans, the hosted MCP server adds per-tool policy on top: blocked_tools and allowed_tools lists enforced on every call, plus a require_approval list. Tools listed in require_approval are denied at invocation with the reason approval required: <tool> — the call never executes. To explicitly deny a tool, use blocked_tools or a lower guard level; use require_approval for tools that must always be refused to agents and handled by a human out-of-band.

Using with other AI agents

Servonaut's MCP server uses the standard stdio transport (local) or SSE+HTTPS (hosted) and is compatible with any MCP-capable AI assistant. Tested integrations include:

• Claude Code & Claude Desktop (Anthropic) — first-class support via --mcp-install claude.
• Cursor, Windsurf, VS Code, OpenCode — auto-installer detects each client.
• Any MCP-compatible client — use servonaut --mcp as the local stdio command (or discover it in the MCP Registry), or connect to https://mcp.servonaut.dev/mcp/sse with a Bearer token from your signed-in CLI (see Connecting a hosted agent).

Hosted MCP — Solo & Teams

The Solo and Teams plans include the hosted MCP server at mcp.servonaut.dev. Instead of running stdio on your local machine, AI agents connect over SSE and the backend relays calls back to your running servonaut connect process — your SSH keys never touch our servers.

Why use it? The agent doesn't need Servonaut (or any of your credentials) installed on its side — it just needs a token and a URL. So you can drive your fleet from a CI job, a teammate's editor, or a second machine, while every command still executes on your box with your keys, fully audited. It's the difference between "the agent runs where my keys are" and "the agent runs anywhere and the work is relayed to where my keys are."

Connecting a hosted agent

Three steps — nothing Servonaut-specific is installed on the agent's side:

1. Keep the relay alive on the machine that holds your SSH keys / cloud config: servonaut connect --bg. This is the process the backend dispatches tool calls to. It authenticates with your stored servonaut login session (automatic token refresh) — no environment variables needed. Run it in the foreground first while testing (servonaut connect, Ctrl+C stops it cleanly); --stop ends the background listener and --reconnect heals a stale connection. Signing in from the TUI auto-starts an in-process listener too — the sidebar shows ● connected.
2. Get your token — sign in from the TUI (Account → Login) or run servonaut login on headless boxes; both use the OAuth device flow. The CLI stores the token at ~/.servonaut/auth.json (mode 0600); copy the access_token value — it authenticates the agent to the hosted server as you. Note the pasted token is a static copy: the relay listener refreshes its own credentials automatically, but your agent's pasted Bearer does not. If hosted calls start failing with authentication errors, re-copy the token (sign in again first if needed).
3. Add a remote (SSE) MCP server in your agent, pointing at the hosted endpoint with an Authorization: Bearer header:

{
  "mcpServers": {
    "servonaut": {
      "type": "sse",
      "url": "https://mcp.servonaut.dev/mcp/sse",
      "headers": { "Authorization": "Bearer <access_token from ~/.servonaut/auth.json>" }
    }
  }
}

Hosted MCP benefits:

• Works from any device — agents in CI or on a colleague's laptop, no local install required on their side.
• Always-on availability (subject to your CLI being connected; servonaut connect --bg keeps it alive).
• Teams plan adds per-tool policy (allow / block / require-approval lists — see the confirmation protocol) and a team audit log of relayed activity, viewable on servonaut.dev under Account → Teams → Audit. The machine running the relay keeps its own local log at ~/.servonaut/mcp_audit.jsonl as well.
• Provider operations (Hetzner, OVH) count against your plan's monthly operation limits — see Pricing.

Headless AI tool approvals

The same relay listener also executes tool calls that originate from Servonaut AI chats — headless servonaut ai chat --tools sessions and conversations started on the web — even when no TUI is open. Because nobody is at the keyboard to confirm, approval is policy-driven: relay.ai_tool_auto_approve in ~/.servonaut/config.json sets the highest guard tier that is auto-approved — readonly, standard (the default), or dangerous (which additionally requires the dangerous-AI-tools opt-in on your account). Calls above the configured tier return a denial the model can relay back to you, and every execution is written to the local audit log marked as AI-chat-originated. See headless AI chat.