ssh-mcp-pro: Instructions file for Codex

AGENTS.md - ssh-mcp-pro

Guidance for AI agents using ssh-mcp-pro v2.

Quick Start

{
  "name": "ssh-mcp-pro",
  "command": "ssh-mcp-pro",
  "type": "stdio"
}

Secure Defaults

• Host-key verification is strict by default.
• Root SSH login is denied unless policy allows it.
• Raw proc_sudo is denied unless policy allows it.
• Destructive commands and filesystem operations are policy-controlled.
• Use policyMode: "explain" before mutations when you need a plan or user confirmation.

Recommended Workflow

1. ssh_list_configured_hosts to discover aliases when useful.
2. ssh_open_session with hostKeyPolicy: "strict" or expectedHostKeySha256.
3. os_detect to learn platform capabilities.
4. Read ssh-mcp-pro://policy/effective before privileged or destructive work.
5. Use task tools: fs_*, proc_exec, ensure_*, file_*, tunnel_*.
6. ssh_close_session when work is complete.

Explain Mode

Use explain mode when a request may mutate a remote host, change files, start or stop services, install packages, open tunnels, or require user approval before execution. Explain mode is a planning and policy-preview path; it is not a permission bypass and it does not execute the requested mutation.

Use policyMode: "explain" when you need a non-mutating preview from normal SSH tools. For example, ssh_open_session with policyMode: "explain" returns a connection plan with wouldConnect instead of opening a live SSH connection. Write, transfer, process, ensure, and tunnel tools that honor the session policy mode return explain-only plans instead of performing the change.

Use policyMode: "enforce" only after the plan has been reviewed, the target host and path are correct, strict host-key verification is active, and the effective policy allows the concrete operation. Enforce mode is the default mode for actual work.

Connector clients can use ssh_policy_explain before opening sessions or running task tools. It evaluates an optional hostAlias, action class, command, and path against policy, returns executed: false, includes the policy decision, and marks non-inspection requests as requiring explicit user confirmation.