toolwright 1.0.0a3

Trusted MCP supply chain for AI tools with signed approvals, fail-closed runtime, drift detection, verification, and bounded auto-repair.

Toolwright

The immune system for AI tools.

Capture any API — or wrap an existing MCP server — and get a governed tool supply chain: credentials isolated from model context, signed approvals, fail-closed runtime, drift detection, and bounded self-healing.

---

Without governance # Token hardcoded in tool config {"auth": "Bearer ghp_s3cr3t..."} # Model sees the token in context # No approval before tool runs # API changes → silent agent failure # No audit trail

With Toolwright toolwright create github export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ..." toolwright serve # Token injected at runtime, never in context # Signed lockfile gates every change # Drift detected before agents break # Every decision audited

---

Why this matters

Every AI agent needs tools. But the way tools connect to APIs today is broken:

• Credentials leak into model context — API keys land in tool definitions, logs, and prompts where the model can see and misuse them
• Tool changes happen silently — new capabilities and changed schemas go live with no human review
• APIs drift and agents break — upstream changes cause silent failures with no alerting or recovery

Generation is the on-ramp. Governance is the moat.

Concern	Typical MCP server	Toolwright
Credentials	In config, visible to model	Injected at runtime, never in context
New tools	Available immediately	Gated behind signed lockfile
API changes	Silent breakage	Drift detected, repair proposed
Failures	Retry or crash	Circuit breakers, quarantine, rollback
Audit trail	None	Every decision logged with reason codes
Recovery	Manual rebuild	Bounded self-healing with snapshots

Install

pip install "toolwright[all]"

tw works as shorthand. For selective installs see below.

Get started in 60 seconds

# Create governed tools from GitHub's API
toolwright create github

# Set your token (never enters model context)
export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_yourToken"

# Get the config snippet for Claude Desktop
toolwright config

# Paste into Claude Desktop config → restart → done.

That's it. GitHub tools — risk-classified, with behavioral rules applied. Your agent can now list repos, create issues, and manage pull requests, all under governance.

Too many tools? Serve a subset: toolwright serve --scope repos,issues

Works with anything you have

Starting point	Command
A known API	toolwright create github
A web app	toolwright mint https://app.example.com -a api.example.com
An OpenAPI spec	toolwright capture import openapi.yaml -a api.example.com
A HAR file	toolwright capture import traffic.har -a api.example.com
OTEL traces	toolwright capture import traces.json --input-format otel -a api.example.com
An MCP server	toolwright wrap npx -y @modelcontextprotocol/server-github

All paths produce the same governed artifacts: tools, policy, lockfile, baselines, and verification contracts.

How the supply chain works

                     ┌──────────────────────────────────────────────┐
  Browser traffic    │                                              │
  OpenAPI spec   ──> │   capture / mint   ──>   compile   ──>       │
  HAR / OTEL         │                                              │
                     │   toolpack (tools + policy + lockfile)       │
                     │                                              │
                     │   serve  ──>  governed MCP server            │
                     │     ├── credential injection (proxy layer)   │
                     │     ├── signed approval gates                │
                     │     ├── circuit breakers                     │
                     │     └── drift / verify / repair              │
                     └──────────────────────────────────────────────┘

1. Capture — Record real API behavior from any source
2. Compile — Generate deterministic tool definitions with schemas, risk tiers, and policies
3. Approve — Sign changes with Ed25519 keys. Nothing runs until reviewed.
4. Serve — Expose tools via MCP with auth injection, policy enforcement, and circuit breakers
5. Heal — Detect drift, verify behavior, and auto-repair within safety bounds

Core capabilities

Credentials never touch model context

Auth is resolved at runtime via environment variables — per-host, isolated. Tool definitions, logs, evidence bundles, and agent prompts are all credential-free.

export TOOLWRIGHT_AUTH_API_GITHUB_COM="Bearer ghp_..."
export TOOLWRIGHT_AUTH_API_STRIPE_COM="Bearer sk_..."
# Toolwright injects the right token for each upstream call

Every change is signed before it runs

Ed25519 signatures on a lockfile. New tools, changed schemas, expanded capabilities — all gated behind explicit approval. No silent privilege escalation.

toolwright gate allow --all              # interactive review
toolwright gate check                    # verify lockfile integrity
toolwright gate block delete_user        # block a specific tool

Fail-closed by default

Default deny. Explicit allowlists only. Network safety is hardcoded: SSRF prevention, private CIDR filtering, redirect validation, and response size limits.

Drift detection and bounded self-healing

Continuous health probing catches upstream changes before your agent breaks. Safe patches auto-apply. Risky ones escalate for approval. Snapshots enable instant rollback.

toolwright drift                              # one-shot check
toolwright serve --watch --auto-heal safe      # continuous monitoring

Behavioral rules and circuit breakers

Composable constraints at invocation time. Kill misbehaving tools instantly.

toolwright rules template apply crud-safety   # require read before delete
toolwright kill search_api --reason "500s"    # circuit breaker kill switch
toolwright enable search_api                  # bring it back

Already have an MCP server? Wrap it.

toolwright wrap npx -y @modelcontextprotocol/server-github
toolwright wrap --url https://mcp.sentry.dev/mcp --header "Authorization: Bearer $TOKEN"

wrap discovers an upstream server's tools and applies the same approval, rules, circuit breaker, and fail-closed enforcement. No tool recreation — just governance.

Serving options

toolwright serve                                    # stdio (Claude Desktop)
toolwright serve --http                             # HTTP + web dashboard
toolwright serve --scope repos,issues               # serve specific groups
toolwright serve --max-risk low                     # cap risk tier exposure
toolwright serve --watch --auto-heal safe           # continuous healing

Documentation

• GitHub API in 60 seconds — quickstart with toolwright create github
• Any REST API — browser capture for custom APIs
• User Guide — full lifecycle reference
• Architecture — internals
• Known Limitations | Troubleshooting | Glossary

Run toolwright --help for the quick reference. Run toolwright --help-all for every command.

Install options

pip install "toolwright[all]"             # MCP server + browser capture + TUI
python -m playwright install chromium     # for browser capture (use same interpreter)

Or install only what you need:

pip install toolwright                    # core
pip install "toolwright[mcp]"             # + MCP server
pip install "toolwright[playwright]"      # + browser capture
pip install "toolwright[tui]"             # + dashboard TUI

License

MIT