Clay Seal

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

Working on the code? 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; most refusals come from _floor in the same file.

Start here

If you are a coding agent, skip to the deploy runbook.

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.

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 at the end for the detail.

If you are an agent

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

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.

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:

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:

{
  "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.

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.

See it stop the attack

From a checkout. examples/ has seven, each runnable with no key and no network:

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:

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

How it works