Tessyr R0

Tessyr is a local authority gateway demo for AI-agent tool calls. It proves a narrow rule: a simulated payment cannot execute unless a current grant and policy decision permit it.

Run locally

npm install
npm run dev

Open http://localhost:5173. The Express API runs on port 8787 and Vite proxies /api to it.

Stripe test mode

Tessyr can execute approved payment actions against Stripe test mode. The secret key stays on the Express server; the browser and MCP tools only see Tessyr action and receipt IDs.

cp .env.example .env

Set the Stripe test secret key in .env.local (or .env), then start the app:

STRIPE_SECRET_KEY=sk_test_...
STRIPE_TEST_PAYMENT_METHOD=pm_card_visa
npm run dev

The API loads .env.local before .env. Environment variables exported by your shell take precedence, so deployment platforms can inject STRIPE_SECRET_KEY without a file. When it is not set, Tessyr uses the built-in simulator. If a live sk_live_... key is present, Tessyr refuses execution. Open Integrations in the console to confirm whether the payment provider is the simulator or Stripe test mode.

Connect an AI agent through MCP

Tessyr exposes a local stdio MCP server. The agent receives narrowly scoped tools, never a provider credential.

npm run setup:agent
npm run dev

Then add this to an MCP-capable client configuration, replacing the cwd path with this repository's absolute path:

{
  "mcpServers": {
    "tessyr": {
      "command": "npm",
      "args": ["run", "mcp"],
      "cwd": "/absolute/path/to/Tessyr"
    }
  }
}

The setup command writes a 256-bit local agent credential to data/local-agent.env with owner-only permissions. It is git-ignored, never displayed, and read by both the local API and MCP subprocess. Rotate it with npm run setup:agent -- --rotate.

The MCP server offers four tools:

• tessyr_whoami — read agent identity and active grant limits.
• tessyr_payment_create — request a one-time protected payment through Tessyr.
• tessyr_action_status — check a pending, blocked, or completed action.
• tessyr_receipt_get — read the linked receipt evidence.

An agent calling tessyr_payment_create never receives a bypass route. A routine action executes once; an exceptional action returns a hash-bound REQUIRE_APPROVAL result and stays pending until a person decides in the Tessyr console.

Demo flow

1. Submit a USD 950 payment to ConfHall. It is allowed and executed once through the configured provider.
2. Submit a USD 1,800 payment. It is held for an exact, one-use finance approval.
3. Approve it once from the inbox; Tessyr executes the same action and records a receipt.
4. Review the receipt timeline, reset the Action Lab, or revoke the demo grant to see later actions fail closed.

Stripe test mode never moves real funds. Local demo state is stored in the git-ignored data/tessyr-state.json file so receipts survive an API restart; use Reset demo to restore the default workspace state.

Checks

npm test
npm run build

The MCP flow is covered by tests/mcp_smoke.ts: it connects as a standard stdio MCP client, discovers tools, performs a routine payment, creates an approval-gated payment, checks status, and retrieves a receipt.

R0 boundaries

This local prototype implements the control path, agent credential, MCP gateway, durable local state, approval binding, idempotency, tamper-evident receipt chain, and Stripe test-mode payment adapter. It does not provide multi-user production authentication, a managed key service, or cloud database. See ROADMAP.md for the R1–R3 delivery plan and production launch gates; those stages require environment-specific infrastructure, customer configuration, and explicit deployment authority.