Metadata-Version: 2.4
Name: writ-mcp
Version: 0.2.2
Summary: Writ MCP server: point-of-action policy checks for AI agent writes (ALLOW/DENY/STEP_UP) with a tamper-evident audit log
License-Expression: MIT
Project-URL: Homepage, https://withwrit.com
Project-URL: Repository, https://github.com/withwrit/pywrit/tree/main/mcp
Project-URL: Documentation, https://docs.withwrit.com
Keywords: ai-agents,mcp,policy,audit-log,guardrails
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp<2,>=1.0
Requires-Dist: httpx>=0.27
Dynamic: license-file

# writ-mcp

The [Writ](https://withwrit.com) gate as an MCP server. Give any MCP-compatible
agent point-of-action control: the agent calls Writ **before** a consequential
write, gets back `ALLOW`, `DENY`, or `STEP_UP`, and every outcome creates an
audit receipt.

<!-- mcp-name: io.github.withwrit/writ -->

## Install

```bash
pip install writ-mcp
```

Requires Python 3.9+. Installs the `writ-mcp` command (stdio transport).

## Configure

```bash
export WRIT_API_KEY="writ_..."        # required; get one free: POST /v1/keys with an email
export WRIT_SPONSOR_TOKEN="..."       # only for sponsor tools (grant, revoke, reinstate)
# export WRIT_BASE_URL="..."          # default: https://api.withwrit.com
```

## Add to your agent

Claude Code:

```bash
claude mcp add writ --env WRIT_API_KEY="$WRIT_API_KEY" -- writ-mcp
```

Claude Desktop (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "writ": {
      "command": "writ-mcp",
      "env": { "WRIT_API_KEY": "writ_..." }
    }
  }
}
```

Any MCP client (generic stdio config):

```json
{
  "command": "writ-mcp",
  "env": {
    "WRIT_API_KEY": "writ_...",
    "WRIT_SPONSOR_TOKEN": "writ_sp_..."
  }
}
```

Hermes (NousResearch/hermes-agent) catalog entry — once published, this
package is installable from the `optional-mcps` catalog:

```bash
hermes mcp install writ
```

## The check-before-write loop

The tool descriptions teach the agent this flow, but the short version:

1. `writ_check(sponsor_id, agent_id, verb, target, purpose)` — before the write.
2. `ALLOW` → you get a 90-second `authToken` bound to that exact write.
3. `writ_verify_token(auth_token, verb, target, purpose)` — immediately before
   executing, to prove the authorization still matches what you're doing.
4. `DENY` → do not proceed. `STEP_UP` → a human sponsor approves
   (via `writ_grant` or the dashboard), then check again.
5. `writ_lease(auth_token, system_id, method, path, body)` - convert the ALLOW
   token into a single-use lease bound to the exact upstream request.
6. `writ_execute(lease_id, method, path, body)` - run the gated write with the
   same method/path/body; the gate forwards it with the vaulted credential and
   returns the upstream response verbatim.

## Tools

| Tool | Who | What |
|---|---|---|
| `writ_check` | agent | Decision + 90s purpose-bound token |
| `writ_verify_token` | agent | Point-of-action token verification |
| `writ_lease` | agent | Convert an ALLOW token into a single-use gated-execution lease |
| `writ_execute` | agent | Run one gated upstream request with a lease or ALLOW token |
| `writ_grant` | sponsor | Approve a STEP_UP (one-time grant) |
| `writ_revoke` / `writ_reinstate` | sponsor | Kill switch on/off for a principal |
| `writ_receipts` | agent | Audit trail of decisions |
| `writ_policy` | agent | Tenant verb policy |
| `writ_sandbox` | anyone | Free 90-second demo grant, no key needed |
| `writ_github_installations` | admin | List connected GitHub App installations |
| `writ_github_set_threshold` | admin | Set the check-run fail threshold per install |
| `writ_github_toggle_pr_comments` | admin | Enable/disable the PR-comment bot |
| `writ_manifests` | agent | List repos with risk profiles or fetch one manifest |
| `writ_explain_receipt` | agent | Explain a receipt in plain language |
| `writ_tenant_notify` | admin | Get or update step-up notification settings |
| `writ_principals` | admin | List the tenant's principals |
| `writ_verbs` | admin | List the tenant's verb vocabulary |
| `writ_keys` | admin | List API key metadata |

Try it with no key: `writ_sandbox` → `writ_check` with `verb="demo_write"`.

## Source

Public repo: [withwrit/pywrit](https://github.com/withwrit/pywrit) (`mcp/`
directory). License: MIT.

Directory listings: [Glama](https://glama.ai/mcp/servers/withwrit/pywrit) ·
MCP Registry `io.github.withwrit/writ`.
