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.

Current release: v0.1.1 on PyPI, with a matching GitHub Release.

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.

Codex Skill

Install the ToolPermit Codex Skill from this GitHub repository with the built-in plugin manager:

codex plugin marketplace add sunhao123456sun-svg/toolpermit --ref main
codex plugin add toolpermit@toolpermit

For a reproducible installation of this release, replace main with v0.1.1 in the first command.

Start a new task, then ask:

Use $toolpermit to install ToolPermit and safely wrap my local MCP stdio server in observe mode.

The Skill checks the environment, installs the compatible Python package when authorized, preserves existing files, shows MCP client changes before writing them, and keeps enforcement and exact approvals user-controlled. See the Codex Skill installation and usage guide for updating, removal, trigger examples, and limitations.

Ten-minute quickstart

Requirements: Python 3.11–3.13. A local checkout is also needed for the contained demo scripts.

python -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install "toolpermit==0.1.1"
.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
• Codex Skill
• 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 plugins
.venv/bin/pyright
.venv/bin/python scripts/check_codex_plugin.py
.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.