MCP tools

ShellWatch’s MCP server exposes seven tools at /mcp. All are scoped to the calling agent’s AgentSession — agents can only see and control their own terminal sessions.

For the high-level guide (auth, OAuth flow, notifications) see Guides → MCP integration.

shellwatch_create_session

Open a terminal session against a configured endpoint.

Param	Type	Required	Notes
endpointId	string	yes	The UUID of an endpoint visible to this account.

Returns: { sessionId, endpointId, status }.

This triggers an endpoint-auth PendingAction that an approver must resolve in the browser before the SSH handshake can complete.

shellwatch_list_sessions

List sessions owned by this MCP client connection.

No params. Returns an array of { sessionId, endpointId, status, createdAt }.

shellwatch_send_keys

Send keystrokes / text to a session.

Param	Type	Required	Notes
sessionId	string	yes	Must be owned by this agent.
keys	string[]	yes	An array of key tokens — see below.

Key tokens:

• text:<literal> — verbatim characters (e.g. "text:ls -la")
• Named keys — enter, tab, escape, backspace, space, up, down, left, right, home, end, pageup, pagedown, delete, insert, f1–f12
• Modifier-prefixed — ctrl:c, ctrl:d, ctrl:l, alt:f, etc.

Example: ["text:vim file.txt", "enter"].

shellwatch_read_output

Read session output. Buffer is append-only with a byte offset.

Param	Type	Required	Notes
sessionId	string	yes
afterOffset	number	no	Read bytes added after this offset. Pair with the previous endOffset.
limit	number	no	Max bytes to return. Long output may be paginated.

Returns: { data, startOffset, endOffset, truncated }.

Typical loop: receive output_available notification with offset → call shellwatch_read_output(sessionId, afterOffset=offset).

shellwatch_close_session

Close a session.

Param	Type	Required
sessionId	string	yes

Sessions are also auto-closed when the MCP transport disconnects.

shellwatch_manage_endpoints

CRUD for SSH endpoints. The agent can list, create, update, or delete endpoints visible to its account.

Param	Type	Required	Notes
action	"list" | "create" | "update" | "delete"	yes
endpoint	object	depends	For create / update.
endpointId	string	depends	For update / delete.

Operators who don’t want agents managing their own targets simply don’t tell the agent the tool exists, or use a key without endpoint write access.

shellwatch_manage_keys

List SSH keys (file + passkey) available to the account.

Param	Type	Required
action	"list"	yes

Returns key metadata only — never the private key material.

Notifications

Notification	Fired when	Payload
output_available	New output is buffered for one of the agent’s sessions (debounced, default 100 ms).	{ sessionId, offset }
session_status	A session’s status changes (open, closed, errored).	{ sessionId, status, endpointId }

Configurable via notifications.mcp.debounceMs.

Errors

Standard MCP error responses. Common cases:

• 404 style — sessionId not owned by this agent (deliberately indistinguishable from “doesn’t exist” to prevent enumeration).
• 403 style — no browser is connected to approve the endpoint-auth PendingAction.
• Sign timeout — approver didn’t respond within 60 s.