hetzner-mcp

Register or update host

hz_host_register

Register or replace an SSH host in the registry so it becomes reachable over SSH. Returns a dry-run plan by default; set confirm=true to save, with an optional SSH login test.

Instructions

Add a host to the registry (or replace its entry). Only registered hosts are reachable over SSH. Set protected=true on the mail server. test_ssh checks the login before saving.

Safety: dry run unless confirm=true.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "name": "<name>",
      "address": "<address>"
    },
    "name": "hz_host_register"
  }
}

Input Schema

Name	Required	Description	Default
`name`	Yes	Short registry name, e.g. app or mail
`port`	No
`role`	No	Free label: mail, app, coolify, db …	app
`sudo`	No	Prefix privileged commands with sudo -n. Default: user is not root
`user`	No		root
`caddy`	No
`notes`	No
`address`	Yes	IP or hostname SSH connects to
`confirm`	No	false (default) returns a dry-run plan and changes nothing. true executes the plan.
`test_ssh`	No
`protected`	No	Refuse destructive operations on this host
`stacks_dir`	No	Where compose stacks live: <stacks_dir>/<name>	/opt
`allowed_paths`	No
`hcloud_server`	No	Matching Hetzner Cloud server name
`hcloud_project`	No

Schema Changelog

Changes observed during successful MCP inspections.

First observedv0.1.0Nov 6, 2026

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare non-read-only, non-destructive, non-idempotent, open-world, but the description adds the most important operational fact the annotations cannot convey: it is a dry run unless confirm=true. It also discloses that test_ssh performs a login check before saving and that protected=true blocks later destructive operations on the host. It does not describe what the dry-run plan looks like or what happens on partial failure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Four short sentences/lines with the core action first and the safety caveat isolated at the end for emphasis. Nothing is redundant, though the mail-server instruction is oddly site-specific and reads as an aside rather than general guidance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 15-parameter mutation with a nested caddy object and no output schema, the description covers the safety model and reachability prerequisite but says nothing about the shape of the dry-run plan or how replacement of an existing entry behaves for fields left unset. That is a meaningful gap for an agent deciding how to call it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 53% schema description coverage across 15 parameters including a nested caddy object, the description only annotates three of them (protected, test_ssh, confirm) and leaves port, user, sudo, stacks_dir, allowed_paths and the hcloud fields entirely to the schema. It adds real meaning where it speaks, but does not compensate for the roughly half of parameters that are undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

"Add a host to the registry (or replace its entry)" gives a concrete verb and resource, and the parenthetical resolves the create-vs-update ambiguity that the name alone leaves open. It does not name the sibling tools it differs from (hz_host_list, hz_host_remove), so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Only registered hosts are reachable over SSH" establishes the clear precondition for calling this tool rather than the read-only siblings. There is targeted conditional guidance ("Set protected=true on the mail server") but no explicit statement of when not to use it or which sibling to pick instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server