Documentation

Foral gives your AI agents typed, governed capabilities over the systems your team already logs into — no public API required, no browser puppeteering, no generated code that rots. Here is what you get and how to use it.

What Foral gives your agents

A contract: a declarative, versioned, fingerprinted description of what a system can do. Your agents call those capabilities as typed tools over MCP — the same system a human uses becomes something an agent can read and act on, safely.

You authorize it once against a system you can access; from then on your agents speak to it through the contract, not through a fragile UI script.

Reads that just work — no browser at run time

Read capabilities run directly against the system's own internal API using your authorized session — no Chromium, no scraping, no clicking. They return typed rows, with a stable identity per record so your agent can sync without re-reading the world.

Capabilities that address a single record are reusable and parameterized — one tool serves every record of that kind, not just the one you looked at.

Writes that stay human-approved

Foral also learns the write operations a system supports. Every write is born OFF: it never executes without a human approving the exact action first. Your app's harness decides where that approval happens; Foral guarantees the write can't fire silently.

Foral keeps only the shape of a write — the operation and its field names — never the values.

The floor is inviolable

Fail-closed by default: a capability that can't be validated doesn't load — it never degrades into a silent, wrong success.

Your password is typed into your own system's form. It never touches Foral.

Foral keeps the contract — routes and field names — never your data values.

Least privilege: an agent can only do what the contract explicitly allows; reads can never become writes.

A contract that stays alive

Each capability carries a fingerprint of its shape. When the system changes, the next read carries an alarm — before wrong data can flow. A corrected version is re-charted, and you adopt it explicitly — never silently.

Adopt a new version with foral update YOUR_SYSTEM --from <url> — it validates the new contract before applying it, and never replaces a working one with a broken one.

Install & run — three commands

1) Install the runner once: pipx install --include-deps 'foral[login]' && playwright install chromium. Serving only, no sign-in (e.g. a headless server): pipx install foral, or npm i -g @foral/cli.

2) Point it at the contract you downloaded: foral init ~/Downloads/YOUR_SYSTEM.yaml. First use configures everything by itself in ~/.foral — a per-install tenant, an encryption key (created once, owner-only) and the contract and session folders. Nothing to set, nothing to guess.

3) Sign in once, then serve: foral login YOUR_SYSTEM opens your system's login in a browser — the session stays on your machine, encrypted (~30 days). Then foral serve YOUR_SYSTEM is the MCP server your agent connects to. foral serve ~/Downloads/YOUR_SYSTEM.yaml works too.

Teams and CI can override any default with environment variables — FORAL_TENANT, SESSION_ENCRYPTION_KEY, CONTRATOS_DIR, SESSION_DATA_DIR, FORAL_HOME — explicit always wins.

Set up each agent

Claude Code: claude mcp add foral -- foral serve YOUR_SYSTEM

Cursor (~/.cursor/mcp.json): {"mcpServers":{"foral":{"command":"foral","args":["serve","YOUR_SYSTEM"]}}}

Codex (~/.codex/config.toml): [mcp_servers.foral] command = "foral" args = ["serve","YOUR_SYSTEM"]

Your own app: connect to the same MCP server with any MCP client SDK — your agent then calls the system's capabilities as typed tools.

Or hand the setup to your agent

You don't have to do the terminal steps yourself — they are exactly what coding agents are for. Only two moments stay human, by design: charting in the sandbox (you sign in to your own system) and typing your password when foral login opens the browser.

After you download your contract, paste this to Claude Code, Codex or Cursor (replace NAME): Set up Foral (docs: https://foral.dev/docs) on this machine for the system NAME: install the runner (pipx install --include-deps 'foral[login]' && playwright install chromium; install pipx first if missing); run foral init ~/Downloads/NAME.yaml; run foral login NAME — a browser opens and I sign in MYSELF, wait for me; register the foral MCP server in your own MCP config with command foral and args [serve, NAME] — no environment variables needed; tell me when to restart you; then list the foral tools and run one test read, showing me the typed rows.

Keep the session alive

Foral reads using the session captured by foral login — it never asks for or stores your password. That session lasts about 30 days.

When it expires, reads stop and you simply run foral login YOUR_SYSTEM again. The session lives only on your infrastructure; it is never sent to Foral.

Chart your system, then keep it

In the hosted sandbox, point Foral at your system and sign in. Press Discover and it maps your system automatically — the reads across the app, and the shape of the writes it declares (forms and actions). When it finishes, press it again: each pass reaches more.

The coverage map shows what was reached and the links still left — a route behind a specific record, or an action. Click a link to navigate there yourself; as you navigate and act, Foral captures what the automatic pass can't reach on its own — including writes, which only ever fire from your own hand, never Foral's.

When it looks right, download the contract, install the runner on your own infrastructure, and your agents keep the capabilities for good.