clayseal-capabilities

# Clay Seal

<!-- mcp-name: io.github.clayseal/clayseal -->

<img src="https://raw.githubusercontent.com/clayseal/clayseal-capabilities/main/docs/assets/clay-seal-logo.png" alt="Clay Seal logo" width="420">

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%20%E2%80%93%203.14-blue.svg)](pyproject.toml)
[![Tests](https://img.shields.io/badge/tests-3300%2B%20passing-brightgreen.svg)](.github/workflows/ci.yml)
[![PyPI](https://img.shields.io/badge/pip-clayseal-orange.svg)](https://pypi.org/project/clayseal/)

**Incorporating business-process-logic constraints into AI systems.**

Your agent has a $1,000 refund ceiling. It issues eleven refunds of $900. Every
call is inside the per-refund limit, so every per-call check passes, and $9,900
goes out the door. Nothing that looks at one call at a time can see this.

Clay Seal sits in front of your tools and judges each call against the whole
session: the grant, the running totals, where the arguments came from, and what
the agent has already done.

## Contents

| | |
| --- | --- |
| [Start here](#start-here) | install and watch it stop two attacks |
| [Use it in two lines](#use-it-in-two-lines) | wrap tools you already have |
| [In front of an MCP server](#or-put-it-in-front-of-an-mcp-server) | no code change |
| [Write the policy](#write-the-policy) | the grant an operator seals |
| [How it works](#how-it-works) | the six layers, in the order they run |
| [What it measures](#what-it-measures) | the numbers, and what they are not |
| [Where the boundary is](#where-the-boundary-is) | what this does not do |
| [Documentation](#documentation) | [docs/START.md](https://github.com/clayseal/clayseal-capabilities/blob/main/docs/START.md) first, then [docs/](https://github.com/clayseal/clayseal-capabilities/blob/main/docs/README.md) |
| [Build from source](#build-from-source) | and run the tests |

**Working on the code?** [docs/INTEGRATION.md](https://github.com/clayseal/clayseal-capabilities/blob/main/docs/INTEGRATION.md) names which
modules the shipped gateway actually executes, which is the fastest way to tell
the live path from the parts that are not wired in. The decision itself is
`SessionBroker._authorize_locked` in
[clayseal/capabilities/broker.py](https://github.com/clayseal/clayseal-capabilities/blob/main/clayseal/capabilities/broker.py); most refusals
come from `_floor` in the same file.

## Start here

If you are a coding agent, [skip to the deploy runbook](#if-you-are-an-agent).

```bash
pip install clayseal
clayseal try
```

`clayseal try` takes about a minute. It runs two attacks in front of you and
shows the gateway stopping them. There is nothing to configure, no key to get
and nothing leaves your machine.

<img src="https://raw.githubusercontent.com/clayseal/clayseal-capabilities/main/docs/assets/clayseal-try.svg" alt="clayseal try: eleven $900 refunds against a $1,000 ceiling, the first allowed and the rest refused, then an injected email recipient held for a person" width="820">

Every verdict there is decided live by the same gateway you would deploy. The
picture is generated from a real run by `python scripts/render_try_svg.py`, and
a test fails if it drifts from what the command prints, so it cannot become a
screenshot of something that used to work.

Python 3.10 to 3.14. Two dependencies, `cryptography` and `pyyaml`.

> **On names.** The directory is `agentauth-capabilities`, the package is
> `clayseal`, and the import is `clayseal.capabilities`. The project was renamed
> at 0.6; `agentauth` still imports as a deprecation shim. See
> [Naming](#naming) at the end for the detail.

## If you are an agent

Do this in the project you are editing, in order:

```bash
clayseal try --fast
clayseal howto
clayseal policy new > policy.yaml
# rename your_* tools; put mailboxes in egress.recipients; then:
clayseal policy lint policy.yaml
clayseal skill --write
```

Python functions: `Guardrail.from_policy_file("policy.yaml").wrap_all({...})`
and bind the wrappers. Keys must match `tools.allow`. Construct one
`Guardrail` per session (a new one resets ceilings). Catch `Refused`
(budget / not granted) and `StepUpRequired` (held — typical for off-list
email). Non-file tools go in `paths.pathless`.

Already an MCP server (Claude Desktop / Cursor): `clayseal proxy`, not
`clayseal serve`. Do not point `proxy` at a plain `.py` file. `clayseal howto`
is the runbook.

## Use it in two lines

Wrap the tools you already have. Nothing else about your agent changes.

```python
from clayseal.capabilities import Guardrail, Refused, StepUpRequired

def list_open_refunds():
    return [{"invoice": "INV-001", "amount": 900.0},
            {"invoice": "INV-002", "amount": 900.0}]

def issue_refund(invoice, amount):
    return f"refunded {invoice} ${amount:.2f}"

guard = Guardrail.from_dict({
    "version": 1,
    "goal": {"id": "refund-run",
             "summary": "Refund the invoices the customer disputed."},
    "expires_at": "2030-01-01T00:00:00Z",
    "tools": {"allow": ["list_open_refunds", "issue_refund"],
              "harmless": ["list_open_refunds"],
              "effects": {"list_open_refunds": "read", "issue_refund": "transfer"}},
    "paths": {"pathless": ["list_open_refunds", "issue_refund"]},
    "budgets": {"value": {"ceilings": {"refunds": "1000.00"},
                          "tracked": {"issue_refund": {"arg": "amount",
                                                       "budget": "refunds"}}}},
})
tools = guard.wrap_all({"list_open_refunds": list_open_refunds,
                        "issue_refund": issue_refund})

# Call them exactly as before. The gateway decides before the tool runs.
for row in tools["list_open_refunds"]():
    try:
        print(tools["issue_refund"](invoice=row["invoice"], amount=row["amount"]))
    except Refused as exc:
        print("refused:", exc.reasons)      # hand the reason back to the agent
    except StepUpRequired as exc:
        print("needs a human:", exc.reasons)
```

The first refund goes through. The second is refused, because the $1,000
session ceiling is already spent. Neither call reached your function.

The policy is inline here so you can paste the whole thing into a file and run
it. In a real deployment it lives in its own YAML, where a security team can
review it and a pull request can gate it. `clayseal policy new > policy.yaml`
writes a commented one to start from, and `Guardrail.from_policy_file` loads it.

The wrappers keep the name, docstring and signature of your originals, so any
framework that introspects them sees the tool it saw before. That covers
LangGraph, the OpenAI Agents SDK, CrewAI and hand-written loops. Call the
wrappers the same way you called the originals, positionally or by name.

## Or put it in front of an MCP server

No code change at all. The gateway speaks MCP, so it sits between your agent and
the server:

```bash
clayseal proxy --policy policy.yaml -- npx @your-org/mcp-server
```

Or paste this into Claude Desktop's MCP config, Cursor's MCP settings, or
`.cursor/mcp.json`. The agent talks to Clay Seal; Clay Seal talks to the server:

```json
{
  "mcpServers": {
    "billing": {
      "command": "clayseal",
      "args": ["proxy", "--policy", "policy.yaml",
               "--", "npx", "@your-org/mcp-server"]
    }
  }
}
```

Tools the policy does not grant are removed from the catalogue, so the agent is
never told they exist.

## Write the policy

This is a whole policy. It lints clean.

```yaml
version: 1

goal:
  id: refund-run
  summary: Refund the invoices the customer disputed.

expires_at: 2027-12-31T00:00:00Z

tools:
  allow:    [list_open_refunds, issue_refund]
  harmless: [list_open_refunds]                 # a read spends nothing
  effects:  {list_open_refunds: read, issue_refund: transfer}

paths:
  pathless: [list_open_refunds, issue_refund]   # these act on invoices, not files

egress:
  domains: [acme.example]
  recipients: [ops@acme.example]               # a domain alone is every mailbox
  bind_recipients: true

budgets:
  value:
    ceilings: {refunds: "1000.00"}              # dollars, for the whole session
    tracked:
      issue_refund: {arg: amount, budget: refunds}
```

Run `clayseal policy lint policy.yaml` before you ship. It catches the mistake
that matters most: a tool that can spend money but debits no budget. On the file
above it reports no errors and one warning (the ceiling is per session unless
you bind a principal), which names a real decision you have not made yet.

Full reference: [docs/POLICY.md](https://github.com/clayseal/clayseal-capabilities/blob/main/docs/POLICY.md).

## See it stop the attack

From a checkout. [examples/](https://github.com/clayseal/clayseal-capabilities/blob/main/examples/) has seven, each runnable with no key and
no network:

```bash
python examples/02_the_proxy.py
```

```
tools advertised to the agent: list_open_refunds, issue_refund
  (the server offers wire_funds; the policy does not grant it, so the agent is never told it exists)

  ok   issue_refund       INV-001   paid INV-001 $900.00
  DENY issue_refund       INV-002   refused by policy: value_budget_exceeded
  ...
  DENY issue_refund       INV-011   refused by policy: value_budget_exceeded
  DENY wire_funds         ops-float refused by policy: tool 'wire_funds' is not in this session's policy

the server executed 2 call(s):
  list_open_refunds {}
  issue_refund {"amount": 900.0, "invoice": "INV-001"}

clayseal proxy: 2 allowed, 11 denied, 0 held for approval; withheld from the catalog: wire_funds
```

Read the last block. A JSON-RPC error proves the agent was told
no; the server's own ledger proves the refund did not happen, and those are
different claims. The same run on the command line, which is the deployment
shape a deployment actually uses:

```bash
clayseal proxy --policy examples/refund.yaml -- python examples/refund_server.py
```

## How it works

You give the gateway a **policy fi