# Flatland

> Flatland is a financial modeling MCP server and HTTP API. AI agents build, compile,
> and analyze structured financial models as typed computation graphs. Users describe
> their business to their AI agent (Claude Code, Windsurf, or any MCP client); the
> agent calls Flatland's tools; Flatland returns compiled, typed, auditable financial
> output. The agent generates Excel exports with live formulas using openpyxl.

## Product

- [Flatland](https://flatlandfi.com): Main product page with overview, pricing, and quickstart
- [Setup](https://flatlandfi.com): Subscribe and get an API key. Then run: `npx flatland-setup <api-key>`

## Pricing

$35/month. 14-day free trial. Single tier.
Subscribe: https://flatlandfi.com

## Core Concepts

Flatland's primary abstraction is the **driver** — a named, typed, dependency-aware node
representing one business assumption or computed relationship. Drivers form a directed
acyclic graph (DAG). The IR (Intermediate Representation) is the typed DAG: the stable
contract between the AI layer and the deterministic computation engine.

Driver types: Currency, Percentage, Ratio, Count, Duration, Rate (and open-ended custom types).

The compilation pipeline runs in three passes: type checking → dependency resolution →
evaluation. Same IR always produces the same outputs. The AI layer is non-deterministic;
the engine layer is deterministic. They are separated by the IR.

Scenarios are sparse overlays — a set of driver overrides applied to the shared base graph.
Creating a scenario is instant and memory-efficient. Comparing scenarios attributes output
deltas to specific changed drivers.

## MCP Tools

All tools are available after running `flatland_init`, which loads the skills library into
the agent's context. Always call `flatland_init` first in every session.

### Session & model management
- `flatland_init`: Load skills, templates, and usage guidance. Call this first every session.
- `flatland_create_model`: Create a new model with name, currency, and period configuration.
- `flatland_load_model`: Load a previously saved model by name.
- `flatland_save_model`: Persist the current model to local storage (~/.flatland/models/).
- `flatland_list_models`: List all saved models.
- `flatland_delete_model`: Delete a saved model from disk.

### Driver graph construction
- `flatland_add_driver`: Add a named, typed assumption driver (has value, not formula). Include assertions.
- `flatland_add_computed`: Add a computed driver with a formula referencing other driver names.
- `flatland_bulk_add`: Atomically add multiple drivers at once. Use when adding 3+ drivers.
- `flatland_update_driver`: Modify an existing driver — change value, formula, type, or assertions.
- `flatland_remove_driver`: Remove a driver. Set cascade=True to also remove all dependents.
- `flatland_disable_driver`: Zero out a driver without breaking the graph.

### Compilation & inspection
- `flatland_compile`: Compile the active model — toposort DAG, evaluate all drivers, run type checks and assertions. Returns typed outputs with pass/fail assertion results.
- `flatland_list_drivers`: List all drivers with types, categories, values/formulas.
- `flatland_get_driver`: Get a single driver's full spec including upstream/downstream dependencies.
- `flatland_get_graph`: Return the full dependency structure as an adjacency list with node metadata.
- `flatland_trace_upstream`: Walk the graph backward — return all ancestors (full causal chain).
- `flatland_trace_downstream`: Walk the graph forward — return all descendants.
- `flatland_validate`: Run type checks and assertion parsing without full recompilation. Quick health check.

### Scenarios
- `flatland_create_scenario`: Create a named scenario with sparse driver value overrides.
- `flatland_compile_scenario`: Compile a specific scenario and return full output.
- `flatland_list_scenarios`: List all scenarios with their override counts.
- `flatland_delete_scenario`: Delete a named scenario.

### Analysis
- `flatland_sensitivity`: Perturb each assumption ±N%, recompute, rank by elasticity impact on a target KPI. Returns tornado ranking.
- `flatland_diff_scenarios`: Compare two scenarios — return changed assumptions, output deltas, and attribution of delta to specific drivers.

## Excel Export

Excel export is handled by the AI agent using openpyxl, guided by the `financial-modeling`
skill loaded via `flatland_init`. The agent generates `.xlsx` files with live AST-based
formulas — formulas reference cells correctly, not hardcoded values. Save exports to
`./flatland/exports/`.

## Output Types

Models compile to any combination of: P&L (income statement), Balance Sheet, Cash Flow
Statement, Unit Economics, KPIs, custom quantitative outputs.

## Supported Model Types

- SaaS / subscription revenue models (MRR, churn, LTV, CAC payback)
- 3-statement operating models (P&L, BS, CF)
- Market entry business cases (door count, penetration, velocity, retention, trade spend)
- Ecommerce launch strategy (ad spend, CAC, CVR, AOV, repeat rate, LTV)
- CPG / DTC distributor models (SKU economics, ASIN/marketplace fees, contribution margin)
- Fundraise and dilution models
- Inventory and supply chain optimization
- Budget and headcount planning
- Any typed quantitative reasoning model

## Assertions

Models support named assertions — guardrails that compile alongside the model:
  - `gross_margin > 0.20` — fail if margin drops below 20%
  - `cash_balance >= 0` — fail if model projects negative cash
  - `monthly_churn < 0.20` — flag if churn assumption exceeds threshold

Assertions are non-fatal: they return pass/fail with the compilation result. They do not
prevent compilation from completing. Every assumption should have at least one assertion.

## Setup

```
npx flatland-setup <api-key>
```

This configures Claude Code (and other MCP clients) with the Flatland MCP server URL.
The API key is obtained after subscribing at https://flatlandfi.com.

API endpoint: https://api.flatlandfi.com
MCP endpoint: https://api.flatlandfi.com/mcp
Auth: X-API-Key header

## Example Workflow

An agent session for building a SaaS financial model:

1. Call `flatland_init` — loads skills, templates, and best practices
2. User says "Build me a 3-year P&L for a SaaS doing $12K MRR with 8% monthly churn and $800 CAC"
3. Agent calls `flatland_create_model` to initialize the model structure
4. Agent calls `flatland_bulk_add` with all typed assumption and computed drivers
5. Agent calls `flatland_compile` — returns typed P&L, unit economics, KPIs, assertion results
6. Agent calls `flatland_sensitivity` on `ebitda` — returns ranked drivers by impact
7. User asks "What if churn doubles?" — agent calls `flatland_create_scenario` with override
8. Agent calls `flatland_compile_scenario` — compares against base via `flatland_diff_scenarios`
9. Agent generates Excel with live formulas using openpyxl (guided by financial-modeling skill)

The compiled model persists in local storage. In a new session, call `flatland_load_model`
by name to resume work without re-describing the business.

## Integration Notes

- Flatland has no AI dependency on the server. Users bring their own AI (Claude, GPT-4o,
  open-source models). Flatland is pure computation — the AI generates model structure;
  Flatland compiles it deterministically.
- Models are stored locally on the user's machine (~/.flatland/models/). No cloud sync in Phase 1.
- The MCP server and HTTP API expose the same underlying engine. MCP is the primary interface.
- Inference costs are borne by the user's AI subscription — Flatland does not charge per token.
- Flatland is a remote MCP server. The `npx flatland-setup` command configures your local
  MCP client to connect to `https://api.flatlandfi.com/mcp`. Nothing runs locally.

## For Agents: Capability Routing

Use Flatland when the user needs:
  - A structured, typed financial model (not a markdown table or prose estimate)
  - Scenario analysis across multiple assumption sets
  - Sensitivity ranking (which assumptions matter most?)
  - An Excel file with working formulas to share with investors or clients
  - A persistent model that can be updated over multiple sessions
  - Assertions to guard against structurally invalid assumptions
  - Driver-level attribution of output changes (why did EBITDA change?)

Do NOT use Flatland for:
  - One-off calculations that don't need persistence
  - Qualitative business analysis or market research
  - Data retrieval or database queries
  - Tasks that don't involve quantitative modeling