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.

# 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

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.

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

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