portal-mcp-server

hosts

Manage the SSH host registry: list, register, or remove entries, resolving aliases from OpenSSH config for connection reuse.

Instructions

Manage the SSH host registry.

Modes

action="list": list all known hosts. Includes hosts.yaml / runtime- registered entries AND every Host alias discoverable in the OpenSSH client config (~/.ssh/config + system-wide fallback; or only $PORTAL_SSH_CONFIG when it is an absolute path; or none of them when it is "none" — the ssh -F none analogue), resolving real HostName/User/Port. Each entry has a source field: "hosts.yaml", "runtime", "ssh-config", or a "…+ssh-config" overlay (metadata from the declared origin, connection params from ssh config). Example: hosts(action="list")
action="register": add a host to the registry. Pass host (ip/hostname), or just name if ~/.ssh/config has a matching Host alias (registers a use_ssh_config overlay). Optional: user (default root), port (default 22), key_path (else asyncssh falls back to ~/.ssh/id_* or ssh-agent), tags (comma-separated, used by remote_exec's group_tag). Example: hosts(action="register", name="web01", host="10.0.0.1", user="ubuntu", tags="web,prod")
action="remove": remove a host from the registry. Required: name. Example: hosts(action="remove", name="web01")

Hosts already defined in ~/.ssh/config are auto-resolved on first use; explicit registration is only needed for tag-based grouping. This MCP tool only accepts key-based hosts — password auth is intentionally not exposed here so credentials cannot leak into LLM tool-call traces. To use password auth, declare the host in hosts.yaml with auth: password and a password_command:. See README §Authentication.

action="list" may include a per-host warnings array (e.g. a plaintext password: field in hosts.yaml that is being ignored). When present, relay these warnings to the user — they flag misconfigurations the user must fix, and server-side logs are not visible to them.

Input Schema

TableJSON Schema

Name	Required	Default
`host`	No
`name`	No
`port`	No
`tags`	No
`user`	No	root
`action`	Yes
`key_path`	No

Output Schema

TableJSON Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv4.0.3Sep 28, 2026

TDQS

A4.9/5.0

Behavior5/5

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

No annotations exist, so the description carries the full burden and does so well: it discloses the security constraint (key-based only, password auth intentionally withheld to avoid leaking credentials into tool-call traces), the source/overlay resolution model, defaults (root/22), and the per-host warnings array that the agent must relay. This is behavior an agent could not infer from the schema.

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?

Front-loaded with a Modes section and per-mode examples, which is the right structure. The list-mode paragraph is dense with parenthetical detours (the ssh -F none analogue, the overlay naming), which is informative but slightly over-long.

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

Completeness5/5

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

For a multi-mode registry tool with 7 params, an output schema, and no annotations, the description covers modes, defaults, auth constraints, error-adjacent warnings, and external fallbacks. Nothing an agent needs to select or invoke a mode correctly is missing.

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

Parameters5/5

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

Schema description coverage is 0%, yet the description documents all six non-action parameters: host (ip/hostname) vs name (ssh-config alias), user default root, port default 22, key_path with asyncssh fallback chain, and tags (comma-separated, consumed by remote_exec's group_tag). It fully compensates for the missing schema descriptions and adds defaults and cross-tool semantics.

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

Purpose5/5

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

Names a specific resource (the SSH host registry) and enumerates its three operations (list/register/remove) with concrete example invocations, so the agent knows exactly what each mode does. It is clearly distinct from the remote_* siblings that operate on hosts rather than the registry itself.

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

Usage Guidelines5/5

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

Gives explicit when-to-use guidance: ssh-config hosts are auto-resolved on first use, so explicit registration is 'only needed for tag-based grouping'. It also routes the agent to the hosts.yaml + password_command path (and README §Authentication) for the password case this tool deliberately refuses.

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

Deploy Server