Toolgovern

What toolgovern MCP server does

The toolgovern MCP server provides an MCP-facing entry point to toolgovern's policy validator. It is intended to sit before an agent tool call and decide whether that call may proceed. The validator examines the arguments supplied to the call rather than relying only on the tool name. For example, two calls made through a tool named bash can receive different decisions when one lists an allowed directory and another pipes a network download into a shell.

The policy model covers shell and process risks, filesystem boundaries, network egress, credentials and secrets, inherited permissions between agents, and optional information-flow labels. A denied call identifies the rule or rules responsible for the decision, rather than returning only a general security error.

How it works

A governed call is evaluated against a declared scope and, where applicable, the scope granted by a coordinator agent. Sub-agent permissions are constrained by the intersection of their requested scope and the coordinator's effective scope. These checks occur for each call.

The synchronous classifier contains 35 rules. Examples include destructive shell commands, pipe-to-shell patterns, path traversal, writes outside an allowed filesystem path, access to sensitive credential files, undeclared network destinations, private or metadata targets, and cross-agent scope violations. The npm package also provides an asynchronous DNS-related TG03 check for hostname arguments; it fails closed when the resolution check cannot establish that the destination is safe.

Decisions can be written as signed JSONL trace entries. Each entry records the decision, fired rule IDs, hashed arguments, declared scope, agent and session identifiers, and a link to the preceding trace entry. This makes the reason for a denial available for later review.

Setup and configuration

The repository publishes an npm package named toolgovern and a Python package named toolgovern-cli. Install the JavaScript package with npm install toolgovern; the npm CLI can be added with npm install --save-dev toolgovern-cli. For Python, install the independent port with pip install toolgovern-cli.

The library API shown in the project uses governTool, ScopeRegistry, and TraceWriter. A caller supplies an existing tool definition, the agent and session identifiers, a declared scope, and optionally a coordinator registry and trace destination. The provided material does not specify additional environment variables or MCP-client-specific configuration.

Tools and capabilities

The toolgovern MCP server presents the CLI as one generic MCP tool rather than exposing a separate MCP tool for every policy rule. Its supported validation surface includes:

• Shell and process execution checks
• Filesystem scope and path-escape checks
• Network destination and egress checks
• Credential and secret access checks
• Coordinator and sub-agent scope inheritance
• Optional information-flow control using declared labels
• Rule-specific allow or deny results
• Signed, chained JSONL decision traces

Limitations and notes

The classifier evaluates one call at a time and does not retain cross-call session state. Consequently, the TG06 high-risk tool-combination category and TG07 modified-retry detection are not implemented in the stated v0.1 rule pack. Information-flow control is opt-in and requires a caller-declared policy; it does not infer labels automatically or perform cross-call taint tracking.

The project supplies both npm and Python distributions, described as independent implementations of the same core classifier. The README excerpt does not document a client-specific setup, required environment variables, or an MCP transport configuration, so those details should be verified before deployment.