sherlock/docs/gssh-mcp.md

gssh-mcp

Stdio MCP for the Gssh gateway. It lets an agent list allowed hosts, initialize the operator's Gssh session, and run one command on one host without exposing local SSH keys.

Exact tool schemas live in cmd/gssh-mcp/tools_*.go.

Auth

gssh-mcp uses sherlock-managed OAuth with wallet key gssh, normally through the shared Authentik sherlock-cli provider. Gssh must trust that issuer and audience for bearer auth.

Config is [services.gssh] with provider or inline OAuth identity plus base_url. sherlock logout gssh clears the session.

Operation

When gssh-mcp is installed, sherlock <agent> includes it in the generated MCP config. The first tool call authenticates lazily. gssh-mcp --probe verifies auth against Gssh without an agent.

run_command opens a WebSocket to Gssh's exec endpoint for the selected host. The server caps remote command runtime at 60 seconds; the client caps returned output at 256 KiB stdout and 64 KiB stderr.

Set SHERLOCK_DEBUG_LOG to capture MCP-side HTTP/WebSocket traces.