pip install -e ".[dev]"
python examples/end_to_end.py

1. Call starts. Host gives auth the caller ID; the model is not involved.
   token issued: level 1 for customer c_asha
2. Model tries to pay.
   model sees: {"status": "denied", "code": "verification_required", "next_tool": "request_verification"}
3. Model calls request_verification (no arguments).
   model sees: pending - An approval link was sent by SMS to the customer's registered number...
4. Customer opens the link and taps Approve.
   session is now level 2
5. Next turn: host attaches the new token, model retries.
   model sees: ok - Payment link sent for ORD-42.

POST /mcp
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzaWQiOiJjYWxsLTEyMyIsInN1YiI6ImNfYXNoYSIsImxldmVsIjoxfQ.CjGAKu5i...

{"jsonrpc": "2.0", "id": 7, "method": "tools/call",
 "params": {"name": "request_verification", "arguments": {}}}

{ "sid": "call-123", "sub": "c_asha", "level": 1,
  "scopes": ["customer:register", "verification:request"],
  "iat": 1794481143, "exp": 1794484743, "session_exp": 1794484743, "jti": "..." }

from mcp_secure_tools.core.gate import ContractViolation, Gate
from mcp_secure_tools.core.tokens import build_verifier

gate = Gate(build_verifier(settings, db))

@mcp.tool(name="create_payment")
def create_payment(order_ref: str, ctx: Context):
    try:
        claims = gate.require(ctx, min_level=Level.VERIFIED, scopes={"payment:create"})
    except ContractViolation as v:
        return v.response()   # tells the model: call request_verification, then retry
    ...                       # claims.sub is the verified customer id

export TL_SECRET_KEY=$(python -c "import secrets; print(secrets.token_urlsafe(48))")
python -m mcp_secure_tools.tools.verification      # :8100

src/mcp_secure_tools/
  core/                  shared by every tool
    tokens.py            issue / verify / revoke signed tokens
    gate.py              the check every tool runs first: token → level → scopes
    policy.py            which level grants which scopes
    sessions.py          host side: start a session from caller ID, current token each turn
    customers/           read customers from the business DB (+ registry for sign-ups)
    contracts/           Pydantic models shared across tools
  providers/sms/         msg91, twilio, console
  tools/
    verification/        request_verification, register_customer, approval page
examples/                end_to_end.py
tests/                   core/ and tools/<name>/