Skip to main content

agentwit

Debug and audit AI agent ↔ MCP server tool calls.

pip install agentwit
agentwit proxy --target http://localhost:3000 --port 8765
[agentwit] 14:32:01  tools/call  bash       HIGH ⚠  shell_exec
[agentwit] 14:32:03  tools/call  read_file  LOW  ✓
[agentwit] 14:32:05  tools/call  bash       CRITICAL 🚨 privilege_escalation  LLM06

Change one URL. No MCP server modification needed.

日本語版 · PyPI · Releases

Python 3.10+ PyPI Tests License: MIT OWASP LLM Top 10 Plugin API


🆕 What's new in v1.2.0 — Run it as a service

agentwit now runs resident instead of being watched in a GUI. Leave it in front of your MCP server and it keeps a tamper-evident record, alerts you where you already are, and is configured from one place.

pip install --upgrade agentwit
agentwit init                 # ~/.agentwit/config.yaml + secrets.env (0600)
agentwit daemon               # single process, ~60–70 MB RSS, loopback only
agentwit ui                   # local settings console (127.0.0.1)
  • Resident daemon — one process, hot-reloads config on SIGHUP, graceful stop. systemd user unit and macOS LaunchAgent under packaging/, with memory/CPU caps and hardening.
  • Notifications — Slack, Discord, generic webhook and email/SMTP, with per-route severity routing and a rate limit. Alerts reach your phone; so do agentwit summary pushes.
  • Settings console — agentwit ui: a loopback-only page to toggle detection rules, manage destinations, and review recent detections.
  • Secrets stay local — credentials live only in ~/.agentwit/secrets.env (0600). Config and the console show just ${env:NAME} references, and secrets are kept out of the witness log and the process logs.

The MCP Inspector desktop GUI is still available (agentwit gui); see MCP Inspector GUI below.


The problem

When an AI agent calls MCP server tools, you can't see what's happening.

AI Agent
↓  (black box)
MCP Server  →  bash / read_file / fetch / ...

agentwit sits between them as a transparent proxy and records everything.

AI Agent
↓
agentwit  ←  logs every call · detects risks · verifies integrity
↓
MCP Server  (zero modification)

5-minute quickstart

pip install agentwit

# 1. Create config + secrets (nothing secret ships in the package)
agentwit init

# 2. Point it at your MCP server, then run it resident
agentwit config set proxy.target http://localhost:3000
agentwit daemon                    # or: agentwit proxy --target http://localhost:3000

# 3. Point your agent to port 8765 instead of 3000. Recording starts immediately.

# 4. Audit report + integrity check
agentwit report --session ./witness_logs/SESSION_ID --format html
agentwit verify --session ./witness_logs/SESSION_ID
# Chain integrity:  VALID ✓   Signature check:  VALID ✓

Run it next to the MCP server so all traffic stays on loopback — no extra port to open. To reach the console or proxy from another machine, tunnel over SSH (ssh -L 8765:127.0.0.1:8765 your-server).

→ Full guide: docs/quickstart.md · service setup: packaging/README.md


Features

Resident service (v1.2.0)

  • agentwit daemon — single process (one thread at idle, no children, ~60–70 MB RSS). Edit config and kill -HUP (or systemctl --user reload) to apply monitor/notify changes without dropping the socket.
  • systemd user unit and macOS LaunchAgent in packaging/ with MemoryMax, CPUQuota, ProtectSystem=strict, loopback+outbound sockets.

Configuration & secrets (v1.2.0)

  • One place: ~/.agentwit/config.yaml (0644, no secrets) + secrets.env (0600). agentwit init, agentwit config get|set|validate.
  • Credentials are referenced as ${env:NAME} and resolved from env or secrets.env; nothing secret is written to config, the console, or logs.

Settings console (v1.2.0)

  • agentwit ui — loopback-only page: toggle rules, limit scored tools, manage notification destinations (secret-safe), review recent detections, live config.yaml preview. CSRF token delivered via URL fragment; the API never returns secret values.

Notifications (v1.2.0)

  • Slack, Discord, generic webhook, email/SMTP. Per-route severity routing and a per-minute rate limit. SSRF guards (https + host allow-list for webhooks; blocked ranges for SMTP). Untrusted fields are sanitized before sending.
  • agentwit summary [--push] and an optional daemon end-of-session push so a phone sees activity without opening the console.

Log recording

  • Tamper-proof SHA-256 chain — detect any modification
  • ed25519 signatures — prove who recorded the log
  • HTML / Markdown / JSON report generation
  • Auto-backup to ~/.agentwit/backups/ on session end
  • Secret redaction before write: key-name based and value scanning for high-confidence secrets (Bearer/Authorization, AWS/GitHub/OpenAI/Slack tokens, JWT, webhook URLs, PEM keys)

Risk detection

  • 15+ built-in patterns: shell_exec, privilege_escalation, data_exfiltration, jailbreak, ...
  • Prompt injection detection (CRITICAL/HIGH/MEDIUM/LOW)
  • Tool schema change detection
  • Agent thought & reasoning recording (LangChain)

OWASP LLM Top 10 mapping (v1.0.0)

Every detected risk is automatically tagged with the corresponding OWASP LLM category:

OWASP LLM Category Detected patterns
LLM01 Prompt Injection instruction_override / role_hijack / jailbreak
LLM02 Sensitive Info Disclosure credential_access / data_exfiltration
LLM06 Excessive Agency privilege_escalation / persistence / lateral_movement
LLM08 Integrity Failures tool_schema_change / proxy_bypass_detected
LLM10 Unbounded Consumption call_rate_anomaly / session_cost_exceeded
from agentwit.analyzer.owasp_mapper import OWASPMapper
mapper = OWASPMapper()
mapper.map("privilege_escalation")  # → "LLM06"
mapper.map_events(events)           # → adds owasp_category to each event

Plugin API (v1.0.0)

Add custom detection rules as external packages — no fork needed:

# my_package/plugin.py
from agentwit.plugins.base import PluginBase

class MyPlugin(PluginBase):
    def scan(self, event: dict) -> list[dict]:
        if "dangerous_pattern" in str(event):
            return [{"pattern": "my_pattern", "severity": "HIGH",
                     "description": "Custom detection"}]
        return []
# pyproject.toml of your plugin package
[project.entry-points."agentwit.plugins"]
my_plugin = "my_package:MyPlugin"
pip install agentwit-plugin-myname
agentwit proxy --target http://localhost:3000 --port 8765
# → plugin auto-loaded on startup

→ Full guide: docs/plugin-guide.md

SIEM integration (v1.0.0)

Forward audit logs to Splunk, Elasticsearch, or Grafana Loki via Fluent Bit:

# docker/docker-compose.siem.yml
SPLUNK_HEC_TOKEN=your-token docker compose -f docker/docker-compose.siem.yml up

Supports: Splunk HEC · Elasticsearch · Grafana Loki

MCP Inspector GUI

Optional desktop app for interactive, real-time MCP server debugging — handy at a workstation, separate from the resident daemon above. Launch with agentwit gui, or download a build:

OS File
Linux .AppImage · .deb · .rpm
macOS .dmg (Apple Silicon / Intel)
Windows .msi

→ All releases

GUI features

  • 3-pane layout: Server info + Tool list / Parameter editor + Response / History + Metrics + Compare
  • Export Report button — generate HTML audit report from History tab with one click
  • EN/JP language support
  • Real-time risk score display
┌─────────────────┬──────────────────────┬─────────────────────┐
│  Server Info    │  Parameter Editor    │  History            │
│  ─────────────  │  ──────────────────  │  ─────────────────  │
│  Tools          │  {                   │  [Export Report]    │
│  ✓ bash   EXEC  │    "command": "ls"   │                     │
│  ✓ read   READ  │  }                   │  14:32 bash  HIGH   │
│  ✓ fetch  READ  │                      │  14:33 read  LOW    │
│                 │  [Execute]           │  14:34 bash  CRIT   │
└─────────────────┴──────────────────────┴─────────────────────┘

Transports

Transport Status How to use
Streamable HTTP ✅ agentwit proxy --target http://localhost:3000
SSE (legacy) ✅ auto-detected
stdio ✅ agentwit proxy --stdio -- python mcp_server.py

LangChain integration

pip install agentwit[full]
from agentwit import AgentwitCallback

callbacks = [AgentwitCallback(output="./audit.jsonl")]

# Agent thoughts and reasoning are also recorded:
# {"type": "agent_thought", "thought": "...", "tool_selected": "bash",
#  "reasoning": "...", "timestamp": "..."}

CLI reference

# Setup & config
agentwit init
agentwit config set proxy.target http://localhost:3000
agentwit config get monitor
agentwit config validate

# Run resident (recommended) or one-shot proxy
agentwit daemon
agentwit proxy --target http://localhost:3000 --port 8765
agentwit proxy --stdio -- python mcp_server.py

# Settings console (loopback only)
agentwit ui

# Session summary (view, or push to Slack/Discord/email)
agentwit summary
agentwit summary --push

# Reports
agentwit report --session ./witness_logs/SESSION_ID --format json
agentwit report --session ./witness_logs/SESSION_ID --format markdown
agentwit report --session ./witness_logs/SESSION_ID --format html --output ./report.html

# Verification
agentwit verify --session ./witness_logs/SESSION_ID
agentwit replay --session ./witness_logs/SESSION_ID
agentwit diff --session-a ./witness_logs/A --session-b ./witness_logs/B

→ Full reference: docs/api-reference.md


Guard vs. Witness

Tool Approach Blocks calls Tamper-proof log
mcp-scan Proxy + Guard ✅ ❌
Intercept Policy proxy ✅ ❌
agentwit Witness proxy ❌ ✅

agentwit does not block. It witnesses.
A blocked call leaves no trace. A witnessed call leaves evidence.


Version history

Version Date Highlights
v0.1.0 2026-03-14 MVP: HTTP/SSE/stdio proxy, SHA-256 chain log
v0.2.0 2026-03-15 HTML report, LangChain, Slack/Discord webhook
v0.3.0 2026-03-16 MCP Inspector GUI, standard /mcp endpoint
v0.4.0 2026-03-21 MCP spec auto-follow, injection detection, tool monitoring
v0.5.0 2026-03-22 ed25519 signatures, bypass detection, anomaly detection
v0.6.0 2026-03-22 GUI Export Report, agent thought recording, error handling
v0.7.0 2026-03-22 OWASP LLM Top 10 mapping, Windows build (GitHub Actions)
v1.0.0 2026-03-22 Plugin API, SIEM integration, full docs, GUI tests
v1.1.0 2026-03 MCP Inspector desktop app (agentwit gui)
v1.2.0 2026-10-26 Resident daemon, config+secrets layer, notification hub (Slack/Discord/email), settings console, value redaction, summary push, security review

Documentation

Doc Contents
docs/quickstart.md 5-minute getting started guide
docs/architecture.md Architecture and design philosophy
docs/api-reference.md Full CLI and Python API reference
docs/plugin-guide.md Plugin development guide
CONTRIBUTING.md How to contribute
CHANGELOG.md Full version history

License

MIT — see LICENSE

Metadata

Release files for agentwit 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for agentwit 1.2.0
File Size Uploaded Provenance Actions
agentwit-1.2.0.tar.gz 135.9 kB Without provenance Details for agentwit-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for agentwit 1.2.0
File Interpreter ABI Platform Actions
agentwit-1.2.0-py3-none-any.whl Python 3 none any Details for agentwit-1.2.0-py3-none-any.whl

Total release size: 226.6 kB

Release files / agentwit-1.2.0.tar.gz

Download URL agentwit-1.2.0.tar.gz
Size 135.9 kB
Tags Source
SHA-256 checksum
How to use checksums
7ac72eabd3c301c03a965042558452b07f463952a4f0b30dcb6d377035690e84
BLAKE2b-256 checksum
How to use checksums
ec4fc1447732ced56fbaed3c2d0e61f1d1a30def4d7e3a9bb8a77b11749635d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Release files / agentwit-1.2.0-py3-none-any.whl

Download URL agentwit-1.2.0-py3-none-any.whl
Size 90.7 kB
Tags Python 3
SHA-256 checksum
How to use checksums
78a5d1f9965266a912802ed0913a5630e80cb85b58a775837abacb43a288d8ec
BLAKE2b-256 checksum
How to use checksums
3fe3c84eac1c78bfdad0682168e58d1626e6e71170c9b70c92e178374ef69d98
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.5

Security for agentwit 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page