mcp-ssh-orchestrator

The MCP SSH Orchestrator provides zero-trust, policy-driven, auditable SSH orchestration for AI-assisted operations. It runs the orchestrator inside a container and enforces deny-by-default access with declarative YAML policies that specify hosts, credentials, and allowed commands. The system is designed to integrate with MCP-aware clients (like Claude Desktop or Cursor) and can be extended to additional MCP-enabled agents. You’ll interact with the policy files (config/servers.yml, config/credentials.yml, config/policy.yml) to define which hosts can be reached, which credentials may be used, and which commands the AI is permitted to execute. Audit logs are generated in JSON for each action, enabling traceability and post-incident analyses. Typical workflows involve starting the container, mounting your local config directory, and letting the policy engine validate and enforce commands before they run.

Prerequisites:

• Docker installed on the host machine
• Access to pull images from GitHub Container Registry
• Optional: a local directory with MCP configuration files (config/servers.yml, config/credentials.yml, config/policy.yml)

1. Install Docker

   • Follow your platform’s instructions at https://docs.docker.com/get-dordocker/

2. Pull and run the MCP SSH Orchestrator container

   • If you have pre-existing config, mount it into the container and expose necessary ports as needed by your environment:

# Create a directory for MCP configuration if you don’t already have one
mkdir -p ~/mcp-ssh/config

# Optional: populate config/servers.yml, config/credentials.yml, config/policy.yml inside ~/mcp-ssh/config
# Example: copy example files or generate your own policies

# Run the MCP SSH Orchestrator container with your local config mounted
docker run -it \
  -v ~/mcp-ssh/config:/mcp/config \
  -e MCP_CONFIG_DIR=/mcp/config \
  ghcr.io/samerfarida/mcp-ssh-orchestrator:latest

3. Verify startup

   • Check container logs for startup messages and policy load status. Ensure the orchestrator reports that policy files are loaded and ready.

4. Optional: Configure environment variables

   • MCP_CONFIG_DIR: Path inside the container where policy/config files live (default /mcp/config)
   • MCP_LOG_LEVEL: Set to info, warn, error to control logging verbosity

5. Integrate with MCP clients

   • Use your MCP client tooling to issue policy-compliant commands and rely on the orchestrator to enforce policies and output structured audit logs.

Tips and common considerations:

• Always keep config/servers.yml, config/credentials.yml, and config/policy.yml under version control to maintain a reproducible audit trail.
• Use IP allowlists and host-key verification as described in the policy docs to maximize zero-trust protections.
• If you encounter permission errors, verify that Docker can access the mounted config directory and that file permissions match expected user IDs inside the container.
• The output and audit trails are JSON-formatted; use jq or a JSON viewer to parse and analyze results efficiently.
• Regularly rotate credentials and update policies to reflect changes in your infrastructure.
• When testing, run with a dry-run policy (if supported by your MCP version) to validate what would execute without making changes.