ToolPermit

ToolPermit is a local-first permission policy, one-time approval, and redacted audit layer for Model Context Protocol (MCP) tool calls. Put it between a local MCP client and a stdio server to observe calls, enforce explainable allow / ask / deny rules, review exceptional actions, and replay recorded calls against a candidate policy.

Release status: v0.1.0 release candidate. The package is not on PyPI yet. Install from a checked-out commit until the first release is published.

English is authoritative for project contracts. See README.zh-CN.md for the Chinese feature overview and quickstart.

Why ToolPermit?

• Deterministic policy: strict, versioned YAML; first match wins and every result explains why.
• Exact one-time approval: an approval is bound to the canonical request, policy, session, and expiry, then consumed atomically.
• Redaction before storage: recognized secrets and sensitive keys are irreversibly replaced before SQLite persistence, display, or JSONL export.
• Offline replay: compare policies against stored, redacted calls without starting the MCP server or executing a tool.
• Local interfaces: every core workflow is available from the CLI; the optional approval UI is restricted to loopback and protected by Host, Origin, CSRF, CSP, and SameSite controls.
• Portable core: tested on Ubuntu, macOS, and Windows with Python 3.11, 3.12, and 3.13.

Ten-minute quickstart

Requirements: Python 3.11–3.13 and a local checkout.

python -m venv .venv
.venv/bin/python -m pip install -e .
.venv/bin/toolpermit init

On Windows PowerShell, use .venv\Scripts\python and .venv\Scripts\toolpermit.

Observe the contained demo. The only write target is the disposable directory you provide:

mkdir demo-workspace
.venv/bin/python examples/demo_client.py \
  --mode observe \
  --demo-dir demo-workspace
.venv/bin/toolpermit runs list

To see a one-time approval, start the same client in enforce mode. It waits before the demo file is written:

.venv/bin/python examples/demo_client.py \
  --mode enforce \
  --policy toolpermit.yaml \
  --demo-dir demo-workspace

In a second terminal, approve from the CLI:

.venv/bin/toolpermit approvals list
.venv/bin/toolpermit approvals approve APPROVAL_ID

Or launch the loopback UI with .venv/bin/toolpermit ui. Continue with the complete quickstart, including policy suggestion, replay, and cleanup.

Policy example

version: 1
default: deny
rules:
  - id: allow-demo-read
    action: allow
    explanation: Reading from the contained demo is expected.
    match:
      tool: read_demo
  - id: review-demo-write
    action: ask
    explanation: Demo writes require one-time local approval.
    match:
      tool: write_demo

Unknown keys and invalid rules fail validation. See the policy reference for matching, precedence, canonicalization, redaction uncertainty, and examples.

Supported scope

v0.1 supports one local user, MCP over stdio, YAML policy version 1, SQLite audit schema version 1, CLI approval, and a loopback-only web UI. It does not provide an operating-system sandbox, authenticate remote users, inspect calls that bypass the proxy, undo an executed tool action, or guarantee that a permitted path is safe from every symlink/TOCTOU race.

Read Security, Privacy and data lifecycle, and Known limitations before using enforcement around destructive tools.

Documentation

• Quickstart
• CLI reference
• Configuration
• Policy reference
• Architecture
• Security model
• Privacy, retention, export, and deletion
• Troubleshooting
• Known limitations
• Policy benchmark
• Contributing and support

Development

python -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"
.venv/bin/ruff check src tests examples scripts benchmarks
.venv/bin/pyright
.venv/bin/pytest --cov=toolpermit --cov-fail-under=70

The release process, compatibility policy, and stage evidence are documented in docs/releasing.md and planning/.

License

Licensed under the Apache License 2.0.