Workspaceguard

What workspaceguard MCP server does

The workspaceguard MCP server connects an MCP-compatible agent to the WorkspaceGuard CLI used alongside Odysseus or a compatible self-hosted AI assistant backend. WorkspaceGuard registers workspaces, associates each one with an identity value, counts messages by workspace and month, and optionally enforces a monthly message cap.

The MCP distribution is included with the Python package as an optional extra. Rather than defining a separate tool for each administrative action, it exposes one generic run tool. An agent supplies the same argument list used with the workspaceguard command, such as usage --json or status --json.

How it works

The MCP tool starts the installed CLI as a subprocess, reads its JSON output, and returns the parsed result. Failures are converted into an error dictionary instead of being raised by the MCP server. This covers cases such as a missing executable, launch failure, timeout, non-zero exit status, or output that cannot be parsed.

WorkspaceGuard's request path resolves the workspace, checks its quota, calls the backend, and records usage. A workspace at its cap receives a quota error before the backend is called. If the usage store cannot be read, the guard blocks the request rather than resetting the count. Backend failures can open a circuit after three consecutive failures; a later half-open probe can close it after a successful call.

Setup and configuration

Install the Python package with its MCP extra:

pip install "workspaceguard-cli[mcp]"

The CLI itself can also be installed from npm with npm install -g workspaceguard-cli, or run through npx workspaceguard-cli. The installed command is workspaceguard.

Initialize the data directory, register workspaces, and optionally set caps with the CLI. For example, workspaceguard add-workspace alex --identity alex@example.com registers an identity, while workspaceguard set-cap alex 1000 applies a monthly limit. The MCP server then invokes these commands through run.

Data is stored under --data-dir when supplied, otherwise under the WORKSPACEGUARD_DATA_DIR environment variable, and finally under ~/.workspaceguard. The --force option is limited to initialization and permanently invalidates data encrypted with an unrecoverable old key.

Tools and capabilities

The workspaceguard MCP server provides the generic run tool. Through it, an agent can invoke:

• init to initialize configuration and the vault
• add-workspace to register a workspace and identity
• status --json to list configured workspaces
• usage --json to retrieve counts, caps, percentages, period, and estimated bytes
• set-cap to set or clear a monthly message limit
• rotate-key to re-encrypt a workspace's secrets under a new key
• scan --json to run the current isolation scan stub

Every command accepts --json; structured output is intended for agents and orchestrators rather than terminal scraping.

Limitations and notes

The MCP layer is a subprocess wrapper, not a separate quota engine. The workspaceguard executable must be installed and available to it. The scan command is currently a scaffold and always returns an empty finding list, so it should not be treated as an active isolation audit.

The README names Claude Desktop and Claude Code as MCP-compatible clients. WorkspaceGuard's underlying backend is described as Odysseus or a compatible self-hosted assistant deployment; compatibility with other backends is not specified beyond that description.