Documentación

Foral da a tus agentes de IA capacidades tipadas y gobernadas sobre los sistemas en los que tu equipo ya inicia sesión — sin API pública, sin marioneta de navegador, sin código generado que se pudre. Esto es lo que obtienes y cómo usarlo.

Lo que Foral da a tus agentes

Un contrato: una descripción declarativa, versionada y con fingerprint de lo que un sistema puede hacer. Tus agentes llaman esas capacidades como herramientas tipadas por MCP — el mismo sistema que usa una persona pasa a ser algo que un agente lee y opera, con seguridad.

Lo autorizas una vez contra un sistema al que tienes acceso; desde ahí tus agentes hablan con él por el contrato, no por un script frágil de UI.

Lecturas que simplemente funcionan — sin navegador en ejecución

Las capacidades de lectura corren directo contra la API interna del propio sistema, con tu sesión autorizada — sin Chromium, sin scraping, sin clics. Devuelven filas tipadas, con identidad estable por registro, para que tu agente sincronice sin releer el mundo.

Las capacidades de un solo registro son reutilizables y parametrizadas — una herramienta sirve para cualquier registro de ese tipo, no solo el que miraste.

Escrituras que siguen aprobadas por humanos

Foral también aprende las operaciones de escritura del sistema. Toda escritura nace APAGADA: nunca se ejecuta sin que un humano apruebe la acción exacta antes. El harness de tu app decide dónde ocurre esa aprobación; Foral garantiza que la escritura no dispara sola.

Foral guarda solo la forma de la escritura — la operación y los nombres de campo — nunca los valores.

El piso es inviolable

Fail-closed por defecto: una capacidad que no valida no carga — nunca degrada en un éxito vacío y erróneo.

Tu contraseña se escribe en el formulario de tu propio sistema. Nunca toca Foral.

Foral guarda el contrato — rutas y nombres de campo — nunca los valores de tus datos.

Mínimo privilegio: el agente solo hace lo que el contrato permite explícitamente; una lectura nunca se vuelve escritura.

Un contrato que sigue vivo

Cada capacidad lleva un fingerprint de su forma. Cuando el sistema cambia, la siguiente lectura trae una alarma — antes de que entre un dato torcido. Una versión corregida se recartografía, y tú la adoptas explícitamente — nunca en silencio.

Adopta la nueva versión con foral update TU_SISTEMA --from <url> — valida el nuevo contrato antes de aplicarlo, y nunca reemplaza uno que funciona por uno roto.

Instala y corre — tres comandos

1) Instala el runner una vez: pipx install --include-deps 'foral[login]' && playwright install chromium. Solo servir, sin inicio de sesión (ej.: servidor headless): pipx install foral, o npm i -g @foral/cli.

2) Apúntalo al contrato que descargaste: foral init ~/Downloads/TU_SISTEMA.yaml. El primer uso se configura solo en ~/.foral — tenant por instalación, clave de cifrado (creada una vez, solo el dueño la lee) y las carpetas de contratos y sesiones. Nada que definir, nada que adivinar.

3) Inicia sesión una vez y sirve: foral login TU_SISTEMA abre el login de tu sistema en el navegador — la sesión queda en tu máquina, cifrada (~30 días). Luego foral serve TU_SISTEMA es el servidor MCP al que tu agente conecta. foral serve ~/Downloads/TU_SISTEMA.yaml también funciona.

Equipos y CI pueden sobreescribir cualquier default con variables de entorno — FORAL_TENANT, SESSION_ENCRYPTION_KEY, CONTRATOS_DIR, SESSION_DATA_DIR, FORAL_HOME — lo explícito siempre gana.

Configura cada agente

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

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

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

Tu propia app: conéctate al mismo servidor MCP con cualquier SDK cliente de MCP — tu agente llama entonces las capacidades del sistema como herramientas tipadas.

O entrega la configuración a tu agente

No necesitas hacer los pasos de terminal a mano — son exactamente el trabajo de un agente de código. Solo dos momentos quedan humanos, por diseño: cartografiar en el sandbox (inicias sesión en TU sistema) y escribir tu contraseña cuando foral login abre el navegador.

Tras descargar tu contrato, pega esto en Claude Code, Codex o Cursor (cambia NAME; el prompt va en inglés — es para el agente): 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.

Mantén la sesión viva

Foral lee usando la sesión capturada por foral login — nunca pide ni guarda tu contraseña. Esa sesión dura unos 30 días.

Cuando expira, las lecturas se detienen y solo corres foral login TU_SISTEMA otra vez. La sesión vive solo en tu infraestructura; nunca se envía a Foral.

Cartografía tu sistema, luego consérvalo

En el sandbox alojado, apunta Foral a tu sistema e inicia sesión. Pulsa Descubrir y mapea tu sistema solo — las lecturas por la app y la forma de las escrituras que declara (formularios y acciones). Al terminar, púlsalo otra vez: cada pasada alcanza más.

El mapa de cobertura muestra lo alcanzado y los enlaces que faltan — una ruta tras un registro específico, o una acción. Haz clic en un enlace para navegar allí tú mismo; mientras navegas y actúas, Foral captura lo que la pasada automática no alcanza sola — incluidas las escrituras, que solo se disparan por tu propia mano, nunca por la de Foral.

Cuando se vea bien, descarga el contrato, instala el runner en tu infraestructura, y tus agentes conservan las capacidades para siempre.