flatland-client

flatland-client — your model is a file you own.

The durable client for the hosted Flatland engine, and a local MCP bridge for Claude Code / Cursor.

Your model lives at ~/.flatland/models/<name>.flatland.json on your machine — versioned in your own git, diffable, re-runnable anywhere. The hosted server is a pure function (/api/v2/*): the client ships the model IR in, the server computes/transforms and returns, and retains nothing at rest.

The MCP bridge (Claude Code / Cursor)

flatland-client mcp runs a local MCP stdio server. It holds the model IR on your machine (durable across sessions) and routes compute to the hosted engine (metered). The usual way to wire it is:

npx flatland-setup fl_live_YOUR_KEY    # configures `flatland-client mcp` by default

Or by hand, in your MCP client config:

{ "mcpServers": { "flatland": { "command": "npx", "args": ["-y", "flatland-client", "mcp"] } } }

The key is read from ~/.flatland/config.json (written by flatland-setup) or the FLATLAND_API_KEY env var — it is never embedded in the MCP config.

As a library

import { create, load, httpTransport } from "flatland-client";

const t = httpTransport({ apiKey: "fl_live_..." });
const h = await create("acme_plan", t);             // writes ~/.flatland/models/acme_plan.flatland.json
await h.bulkAdd([
  { name: "revenue", type: "Currency", value: 1000 },
  { name: "cost", type: "Currency", value: 400 },
  { name: "profit", type: "Currency", formula: "revenue - cost" },
]);
console.log((await h.compile()).values.profit.value);  // metered compute, nothing stored server-side

// new session / a machine that has the file:
const h2 = await load("acme_plan", t);                 // durable across restart

CLI

flatland-client mcp              # run the local MCP stdio server
flatland-client list            # list durable models on this machine
flatland-client create <name>   # create a model, persisted locally
flatland-client compile <name>  # compile a local model via the hosted engine

Durability + safety contract

• Atomic writes (tmp + rename) — a crash never leaves a half-written model.
• Fail-loud (F2) — a failed mutation (5xx, or a rejected 4xx) raises and leaves the local file untouched; a failure is never a silent stale-file "success".
• No server fallback — load() of a missing file raises; the server never held your model.
• Envelope versioning — { "flatland_ir_version": 1, "ir": {...} }; a too-new envelope is refused before it is persisted.
• Path-traversal-safe model names; the API key goes only in the X-API-Key header — never logged.

Get a key at https://flatlandfi.com/install.

License

MIT. Covers the client only — the Flatland engine and API are a separate, proprietary service accessed with a paid API key.