# 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.