flatland

Financial reasoning infrastructure for AI agents - typed models, deterministic compilation, cryptographic receipts via MCP

CommunityOnlineAPI key requiredGlobalFreeRead-only

What it can do

  • Flatland Init: Initialize a Flatland session. MUST be called before any other tool. Returns skills (workflow instructions), templates, config schema, and best practices that teach the AI agent how to
  • Flatland Create Model: Create a new empty financial model.
  • Flatland Load Model: Load an existing model from disk by name.

What data it sees

Do you need an account

An API key from the service settings is required

Financial reasoning infrastructure for AI agents - typed models, deterministic compilation, cryptographic receipts via MCP

How to connect

How to connect flatland to Claude

The server address to paste into Claude settings:

https://flatland--flatlandfi.run.tools

  1. Open Claude (claude.ai or the desktop app).
  2. Go to Settings → Connectors.
  3. Click Add custom connector.
  4. Paste the server address copied below into Remote MCP server URL and click Add.
  5. In a chat, click + → Connectors and switch the new connector on.

Custom connectors are available on Free, Pro, Max, Team and Enterprise plans (Free is limited to one). On Team and Enterprise an organization Owner adds the connector first under Organization settings → Connectors.

Authorization

After you click Add, a sign-in window for the service opens. Sign in with your own account and approve access. Claude never sees your password.

How to connect flatland to ChatGPT

The server address to paste into ChatGPT settings:

https://flatland--flatlandfi.run.tools

  1. Open ChatGPT in a browser (chatgpt.com). A Plus, Pro, Business, Enterprise or Edu plan is required.
  2. Turn on developer mode once: Settings → Apps → Advanced settings → Developer mode.
  3. Open Settings → Connectors and click Create.
  4. Fill in the form: Name (anything), Description (one line about what the service does), MCP server URL (copy it below).
  5. Under Authentication choose OAuth if the service requires sign-in, otherwise None. Click Create.
  6. In a new chat open + → Apps/Connectors and enable the connector.

OpenAI has renamed this section before (Connectors → Apps/Plugins). If the label differs, search settings for "developer mode". On Business/Enterprise workspaces an admin must allow custom connectors first.

Authorization

On first use ChatGPT opens the service's sign-in window. Sign in and approve access.

How to connect flatland to Cursor

The server address to paste into Cursor settings:

https://flatland--flatlandfi.run.tools

Fastest: click Open in Cursor below and confirm the prompt.

Manually:

  1. In Cursor open Settings → Cursor Settings → MCP and click Add new global MCP server.
  2. Paste the JSON copied below into ~/.cursor/mcp.json (per project: .cursor/mcp.json in the repo root).
  3. Save the file. The server appears in the MCP list; authorize it there if asked.

Authorization

If the service needs sign-in, an authorize button appears next to the server in the MCP list.

Server tool list (32)

Raw names from tools/list. Only developers need these.

flatland_initInitialize a Flatland session. MUST be called before any other tool. Returns skills (workflow instructions), templates, config schema, and best practices that teach the AI agent how to use the engine effectively.
flatland_create_modelCreate a new empty financial model.
flatland_load_modelLoad an existing model from disk by name.
flatland_save_modelPersist the current in-memory model to disk as JSON in the store directory (~/.flatland/models/). Pass `name` to save under an alternate file stem (e.g. `name="scenario_v2"` writes `scenario_v2.json`); omit to save under the model's own name. After first save, model auto-saves on every mutation to prevent data loss. `name` is restricted to alphanumeric/underscore/hyphen to prevent filesystem-path injection. The save location is always inside the validated store directory — filesystem paths are not accepted.
flatland_list_modelsList all saved models.
flatland_delete_modelDelete a saved model from disk.
flatland_add_driverAdd an assumption driver to the active model. Assertions must be objects with 'condition' (e.g. '> 0', '>= 0.10', '< 1.0') and 'label' (description) keys. NDO-DOGFOOD pre-flight #1 (2026-05-06): ``namespace`` is the dotted-path ownership tag for multi-agent models (e.g. ``"ndo.rd"``). When set, the canonical key must be ``f"{namespace}.{local}"``. ``namespace=None`` keeps legacy un-namespaced behavior (default).
flatland_add_computedAdd a computed driver to the active model. The formula is parsed and dependency edges are extracted. Assertions must be objects with 'condition' (e.g. '>= 0', '< 1000000') and 'label' (description) keys. NDO-DOGFOOD pre-flight #1 (2026-05-06): ``namespace`` is the dotted-path ownership tag. When set, the canonical key must be ``f"{namespace}.{local}"``. Within-namespace bare formula refs resolve through ``_rebuild_edges`` (see NAMESPACE-001 / NAMESPACE-001.5).
flatland_add_aliasAdd an alias driver — a named pointer to another driver (NAMESPACE-002). Aliases enable cross-namespace composition. An alias has no value and no formula; it resolves at compile time to its target's computed value. Use cases: - A namespace (e.g. `ndo.finance`) needs to reference drivers owned by another namespace (e.g. `ndo.rd.headcount`). Declare an alias in the consuming namespace; use the bare alias name in local formulas. - Create a stable external name for an internal implementation driver. The alias's depends_on is one-hop (the target), not transitive. Chains of aliases (alias → alias → concrete) resolve flat via the toposort.
flatland_add_cumulativeDeclare a cumulative / running line ONCE and let Flatland lower it. This is the single authoring surface for cumulative math (running cash, retained earnings, runway). The author states *what* (a running total of a flow); Flatland generates the verbose per-period scalar chain. Never hand-roll period-suffixed drivers — declare the line here. Two kinds (engine-agnostic authoring tokens, NOT runtime functions): - ``kind="cumsum"`` — a running balance: ``name = cumsum(flow)``. Build the per-period flow as the reserved family ``{flow}__p1 … {flow}__pN`` first, then declare the line. Optional ``opening=`` adds an opening balance into period 1. Optional ``flow_sign`` ("positive"/"negative") auto-attaches an advisory sign assertion on the terminal cumulative. The declared ``name`` resolves to the ending balance (terminal period). - ``kind="runway"`` — first period a cumulative goes below zero: ``name = first_period_below_zero(over)``. ``over`` is the declared name of an existing cumsum line. A companion boolean ``{name}__exceeds_horizon`` (1 = never ran out, 0 = ran out) is generated so you can distinguish "out at month N" from "never out". The generated interior drivers (``{name}__p{k}``) are engine internals — never reference them in your own formulas (the macro rejects it). Reference only the declared ``name``. This black-box property is what lets a future native period-axis ``cumsum`` replace the lowering with zero rework. Never feed a stock (a cumsum output) into another ``cumsum`` — that double-accumulates a balance and is refused at ingestion.
flatland_update_driverUpdate an existing driver's value, formula, assertions, or metadata. NDO-DOGFOOD pre-flight #1 (2026-05-06): ``namespace`` is an optional disambiguator. When set, ``name`` may be the bare local id (``"velocity"``) and the tool resolves the canonical key (``"ndo.rd.velocity"``) for lookup. Passing the canonical key directly also works. Updating the namespace itself is NOT supported — that would change the canonical key and break references; remove + re-add instead. Formula updates resolve bare refs within the existing driver's namespace, mirroring add_computed.
flatland_remove_driverRemove a driver. By default fails if other drivers reference it. Set cascade=True to also remove all downstream dependents.
flatland_disable_driverDisable a driver by setting its value to 0 (assumptions) or marking it. Downstream formulas still reference it but it contributes nothing. Useful when you want to neutralize a driver without breaking the graph.
flatland_bulk_addAdd multiple drivers (assumptions and computed) atomically. If any fail validation, none are added. Each driver dict needs: name, category ('assumption' or 'computed'), type. Assumptions need 'value'. Computed need 'formula'. Optional: label, assertions (list of {condition, label}), tags, description, namespace. NDO-DOGFOOD pre-flight #1 (2026-05-06): Each spec may carry an optional ``namespace`` (dotted-path ownership tag). When set, the spec's canonical key must be ``f"{namespace}.{local}"``. Bare formula refs resolve to ``f"{namespace}.{ref}"`` if the qualified key exists in the batch or the existing model — same tie-break as ``add_computed``.
flatland_compileCompile the model under a scenario. Returns all values, assertions, and warnings.
flatland_list_driversList all drivers in the active model with their types, categories, values/formulas. Lightweight inspection without compiling.
flatland_get_driverGet a single driver's full spec including upstream/downstream.
flatland_get_graphReturn the full dependency structure as an adjacency list with node metadata.
flatland_trace_upstreamWalk the graph backward and return all ancestors (full causal chain).
flatland_trace_downstreamWalk the graph forward and return all descendants.
flatland_validateRun type checks and assertions without full recomputation. Quick health check.
flatland_seam_lint_single_writerSeam linter: flag namespaces written by more than one owner (read-only). ``ownership`` optionally maps namespace -> owner-id. When omitted (single tenant / no manifest) every namespace is its own writer and no violations are reported; the writer inventory is still returned. With a manifest, a namespace whose writer-drivers resolve to >1 owner — or to an owner the manifest never declared — is a violation. Never mutates; never compiles.
flatland_seam_lint_dangling_importsSeam linter: flag alias 'imports' whose target driver is missing (read-only). An alias driver is a cross-namespace pointer (the model's import); a target that does not exist in the model is a dangling import that would surface as ``unresolved_alias`` at compile. Never mutates; never compiles.
flatland_seam_lint_cross_namespace_writesSeam linter: flag drivers writing into a namespace they do not own (read-only). Always checks the structural invariant that a driver's declared ``namespace`` matches its canonical key (a corrupt-IR tripwire). When ``ownership`` (namespace -> owner-id) is supplied, also flags writer-drivers landing in a namespace the manifest never declared an owner for. Never mutates; never compiles.
flatland_create_scenarioCreate a named scenario with driver value overrides.
flatland_compile_scenarioCompile a specific scenario. Apply overlay, recompute, return full output.
flatland_list_scenariosList all scenarios with their override counts.
flatland_delete_scenarioDelete a named scenario.
flatland_sensitivityPerturb each assumption ±N%, recompute, measure impact on target. Returns ranked list with elasticity.
flatland_diff_scenariosCompare two scenarios. Returns changed assumptions, output deltas, and optional attribution.
flatland_export_excelExport the active model as an institutional-grade ``.xlsx`` file. Note: ``flatland_export`` (HTML) is the recommended export for sharing with investors, boards, or team members — it works in any browser without Excel. Use ``flatland_export_excel`` when you specifically need live Excel formulas for manual iteration in a spreadsheet application. The exporter is a deterministic compiler: it walks the IR DAG and emits one Excel cell per IR driver, with computed drivers rendered as live Excel formulas (not values) that reference workbook-scope defined names. The resulting file recalculates correctly in Excel/Numbers/Google Sheets/LibreOffice with no manual rewiring. The file follows institutional conventions: blue font + light-blue fill for inputs, black font + light-gray fill for formulas, currency formatted as ``$#,##0`` with parens for negatives and dash for zero, percentages as ``0.0%``, all assertions surfaced as PASS/FAIL rows in a dedicated sheet, and a Checks sheet that verifies compilation, assertions, and formula transpilation succeeded. Every export is auto-scored against Flatland's frozen v1 institutional rubric (see experiments/excel-export-skill/rubric.md). The ``rubric_score`` field in the response is a 0-100 integer; an institutional-grade output scores 90+.
flatland_exportExport the active model as a self-contained HTML report. The HTML file is investor-ready, works offline in any browser, and requires no Excel license. It includes: - Key financial outputs (terminal computed drivers) - Assertion health (pass/fail guardrails) - Sensitivity tornado (top drivers by impact on the primary KPI) - Scenario comparison (if scenarios exist) - Key assumptions (ranked by sensitivity) - Full driver table (collapsible) - Embedded IR JSON for machine consumption The sensitivity analysis is run automatically (unbilled — this is a final-mile deliverable). The target KPI is auto-detected from standard financial driver names (ebitda, net_income, mrr, runway, etc.).