# FinanceSec — Complete Technical Specification & LLM Reference Manual
> Volumetric Lattice Network (VLN) Deterministic SEC EDGAR Fact Engine & Quantitative Risk API
> Model Context Protocol (MCP) Server: https://finsec.caleralabs.com/mcp
> Machine-Readable Discovery: https://finsec.caleralabs.com/.well-known/mcp.json
> OpenAPI 3.0 Specification: https://finsec.caleralabs.com/openapi.json
> Interactive Guide: https://finsec.caleralabs.com/mcp-docs
> Universal Dashboard: https://dashboard.caleralabs.com/dashboard?domain=finsec

---

## 1. ⚡ 1-Click & Fast-Track Install Instructions

### 1-Click Terminal Quick-Install (Smithery CLI)
Instantly connect Claude Desktop, Cursor, Windsurf, or your AI coding assistant with zero manual JSON configuration:

```bash
# Google Antigravity (Standard Default / Recommended)
agy mcp add finsec https://finsec.caleralabs.com/mcp

# Claude Code CLI
claude mcp add --transport http finsec https://finsec.caleralabs.com/mcp

# Claude Desktop / Cursor / VS Code (Streamable HTTP Bridge)
npx -y mcp-remote https://finsec.caleralabs.com/mcp
```

### 1-Click Web Registry & Ecosystem Hubs
- **Smithery.ai 1-Click Install:** [https://smithery.ai/servers/calera-labs/finsec](https://smithery.ai/servers/calera-labs/finsec)
- **Anthropic Claude Connectors Directory:** Slug `finsec` / `financesec-mcp` (Streamable HTTP at `https://finsec.caleralabs.com/mcp`)
- **Glama.ai MCP Hub:** [https://glama.ai/mcp/servers/Calera-Labs/finsec-mcp](https://glama.ai/mcp/servers/Calera-Labs/finsec-mcp)
- **Open MCP Registry (PulseMCP):** Canonical manifest at `https://finsec.caleralabs.com/mcp`

---

## 2. System Architecture & Epistemic Guarantees

FinanceSec is an epistemic foundation service providing deterministic access to SEC EDGAR 10-K, 10-Q, and 8-K filings across 10,000+ corporate issuers.
Unlike probabilistic LLM RAG pipelines:
1. **Zero LLM in Fact Path:** Recalled facts are evaluated directly from the Volumetric Lattice memory graph (`e.mem`) with sub-5ms latency on CPU.
2. **Cryptographic Provenance:** Every returned metric carries the SEC filing accession number, US-GAAP / IFRS XBRL taxonomy concept, fiscal period, and SHA-256 audit hash.
3. **Boundary Refusal Operator (\partial^2 = 0):** If an entity, period, or metric is missing or unverified, the system returns `SAFE_REFUSAL` with `isError=false`. The system refuses to hallucinate or interpolate missing numbers.
4. **Deterministic Algebraic Solver:** Domain 31 executes compound calculations (CAGR, ratios, margins, YoY series) in Go with IEEE 754 parity checking.

---

## 3. Authentication & Headers

Base URL: https://financesec.api.caleralabs.com
MCP Endpoint: https://finsec.caleralabs.com/mcp

Authentication Header:
```http
X-License-Key: clabs_live_YOUR_KEY
```
or Bearer Token (OAuth 2.1 CIMD):
```http
Authorization: Bearer YOUR_OAUTH_TOKEN
```

Response Headers:
- `Link: <https://finsec.caleralabs.com/.well-known/mcp.json>; rel="service-desc"; type="application/json"`
- `Link: <https://finsec.caleralabs.com/llms.txt>; rel="describedby"; type="text/plain"`
- `Link: <https://finsec.caleralabs.com/llms-full.txt>; rel="describedby"; type="text/plain"`
- `Link: <https://finsec.caleralabs.com/openapi.json>; rel="service-doc"; type="application/json"`
- `X-MCP-Server: financesec-mcp`
- `X-MCP-Version: 1.2.1`
- `X-MCP-Capabilities: tools,prompts,resources`
- `X-MCP-Endpoint: https://finsec.caleralabs.com/mcp`
- `X-MCP-Tools: query_financial_sec,valuation_inputs,query_sec_metric_exact,compute_sec_cagr,lattice_arith_evaluate,vln_capabilities_overview,query_sec_sector_peers,query_fomc_dotplot,query_macro_indicator,query_treasury_curve,stress_test_portfolio,simulate_macro_regime,verify_financial_claim,firewall_audit_trail`

---

## 4. The 14 Certified MCP Tools (Full JSON Schemas)

### Tool 1: `query_financial_sec`
**Description:** Certified SEC fact query. Returns verified values with provenance or SAFE_REFUSAL. Does not invent numbers. Treat SAFE_REFUSAL as success-of-honesty, not a tool failure. Monetary answers default to the filer's reporting currency; request FX conversion via target_currency / usd_only or natural-language 'in USD'.

**JSON Schema:**
```json
{
  "name": "query_financial_sec",
  "description": "Certified SEC fact query. Returns verified values with provenance or SAFE_REFUSAL. Does not invent numbers. Treat SAFE_REFUSAL as success-of-honesty, not a tool failure. Monetary answers default to the filer's reporting currency; request FX conversion via target_currency / usd_only or natural-language 'in USD'.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Natural language financial question. Append 'in USD' (or another supported ISO code) to convert foreign reporting currencies after verified recall."
      },
      "target_currency": {
        "type": "string",
        "description": "Optional ISO 4217 code (e.g. USD, EUR) for post-recall FX conversion using audited annual-average rates. Provenance records original_unit, fx_rate, and fx_converted."
      },
      "usd_only": {
        "type": "boolean",
        "description": "When true, forces monetary answers into USD."
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact ~38-token schema optimized for LLM context windows."
      }
    },
    "required": ["query"]
  }
}
```

**Verbose Response Example:**
```json
{
  "status": "VERIFIED_SUCCESS",
  "query": "What was Apple's total revenue in FY2023?",
  "company": "Apple Inc.",
  "ticker": "AAPL",
  "cik": "0000320193",
  "fiscal_period": "FY2023",
  "numeric_value": 383285000000,
  "unit": "USD",
  "formatted": "$383.29B",
  "provenance": {
    "source_filing": "10-K",
    "filing_date": "2023-11-03",
    "accession_number": "0000320193-23-000106",
    "xbrl_concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
    "doc_period_end": "2023-09-30",
    "audit_hash": "d9697123bf04a43b",
    "battery_sha256": "d222effd29c2c6e4f0f498abe00520954e72b3d62a4471c3ca83fd74ad3a9839"
  }
}
```

**Compact Response (`low_tokens: true`):**
```json
{
  "id": "q112",
  "st": "OK",
  "val": 383285000000,
  "cur": "USD",
  "concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
  "per": "FY2023",
  "hash": "d9697123"
}
```

---

### Tool 2: `valuation_inputs`
**Description:** Certified SEC/EDGAR valuation inputs pack (12 packs: equity_screen, ev_bridge, quality_of_earnings, segment_mix, returns_screen, leverage_screen, piotroski_f, altman_z_prime, beneish_m_score, dupont_5step, working_capital_efficiency, dcf_valuation_inputs).

**JSON Schema:**
```json
{
  "name": "valuation_inputs",
  "description": "Certified SEC/EDGAR valuation inputs pack (12 packs: equity_screen, ev_bridge, quality_of_earnings, segment_mix, returns_screen, leverage_screen, piotroski_f, altman_z_prime, beneish_m_score, dupont_5step, working_capital_efficiency, dcf_valuation_inputs).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "company": {
        "type": "string",
        "description": "Company ticker or name, e.g. AAPL, TSLA, MSFT"
      },
      "pack": {
        "type": "string",
        "description": "Certified SEC valuation pack ID (equity_screen, ev_bridge, quality_of_earnings, segment_mix, returns_screen, leverage_screen, piotroski_f, altman_z_prime, beneish_m_score, dupont_5step, working_capital_efficiency, dcf_valuation_inputs)"
      },
      "period": {
        "type": "string",
        "description": "Optional reporting period, e.g. FY2023. Defaults to FY2023."
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact schema."
      }
    },
    "required": ["company", "pack"]
  }
}
```

---

### Tool 3: `query_sec_metric_exact`
**Description:** Exact single-cell EDGAR metric recall for company + metric + period. Server-side verified fact with provenance; SAFE_REFUSAL when missing.

**JSON Schema:**
```json
{
  "name": "query_sec_metric_exact",
  "description": "Exact single-cell EDGAR metric recall for company + metric + period. Server-side verified fact with provenance; SAFE_REFUSAL when missing.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "company": {
        "type": "string",
        "description": "Company ticker or name, e.g. AAPL"
      },
      "metric": {
        "type": "string",
        "description": "EDGAR metric, e.g. net income, free cash flow, total revenue, operating cash flow"
      },
      "period": {
        "type": "string",
        "description": "Fiscal period, e.g. FY2023"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact schema."
      }
    },
    "required": ["company", "metric", "period"]
  }
}
```

---

### Tool 4: `compute_sec_cagr`
**Description:** Domain 31 lattice CAGR over verified EDGAR facts (log-walk + Go parity). Refuses non-positive or missing endpoints.

**JSON Schema:**
```json
{
  "name": "compute_sec_cagr",
  "description": "Domain 31 lattice CAGR over verified EDGAR facts (log-walk + Go parity). Refuses non-positive or missing endpoints.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "company": {
        "type": "string",
        "description": "Company ticker or name, e.g. AAPL"
      },
      "metric": {
        "type": "string",
        "description": "EDGAR metric to compound, e.g. revenue, free cash flow, net income"
      },
      "start_period": {
        "type": "string",
        "description": "Start fiscal period, e.g. FY2020"
      },
      "end_period": {
        "type": "string",
        "description": "End fiscal period, e.g. FY2023"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact schema."
      }
    },
    "required": ["company", "metric", "start_period", "end_period"]
  }
}
```

---

### Tool 5: `lattice_arith_evaluate`
**Description:** Deterministic zero-error algebraic solver (cagr, ratio, multiply, divide, yoy_series, product_chain) over verified SEC EDGAR financial metrics.

**JSON Schema:**
```json
{
  "name": "lattice_arith_evaluate",
  "description": "Deterministic zero-error algebraic solver (cagr, ratio, multiply, divide, yoy_series, product_chain) over verified SEC EDGAR financial metrics.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "op": {
        "type": "string",
        "description": "cagr | ratio | multiply | divide | yoy_series | product_chain"
      },
      "company": {
        "type": "string",
        "description": "Ticker or name when fetching EDGAR cells"
      },
      "metric": {
        "type": "string",
        "description": "EDGAR metric, e.g. free cash flow, revenue"
      },
      "start_period": {
        "type": "string",
        "description": "Start / numerator period, e.g. FY2020"
      },
      "end_period": {
        "type": "string",
        "description": "End / denominator period, e.g. FY2023"
      },
      "periods": {
        "type": "string",
        "description": "Optional comma-separated fiscal periods for yoy_series/product_chain"
      },
      "factors": {
        "type": "string",
        "description": "Optional comma-separated positive factors for product_chain"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact schema."
      }
    },
    "required": ["op"]
  }
}
```

---

### Tool 6: `vln_capabilities_overview`
**Description:** Returns a complete structured overview of all certified EDGAR valuation packs, deterministic financial arithmetic operations, SEC calculations, and product scope boundaries on finsec.caleralabs.com.

**JSON Schema:**
```json
{
  "name": "vln_capabilities_overview",
  "description": "Returns a complete structured overview of all certified EDGAR valuation packs, deterministic financial arithmetic operations, SEC calculations, and product scope boundaries on finsec.caleralabs.com.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    }
  }
}
```

---

### Tool 7: `query_sec_sector_peers`
**Description:** Returns certified SEC EDGAR XBRL metrics across an industry peer group dynamically derived from SEC filing SIC codes and 10-K business segment disclosures.

**JSON Schema:**
```json
{
  "name": "query_sec_sector_peers",
  "description": "Returns certified SEC EDGAR XBRL metrics across an industry peer group dynamically derived from SEC filing SIC codes and 10-K business segment disclosures.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "sector_or_industry": {
        "type": "string",
        "description": "Industry or sector description as declared in SEC filings, e.g. 'semiconductors', 'photonics', 'pharmaceuticals'"
      },
      "metrics": {
        "type": "string",
        "description": "Optional comma-separated SEC XBRL metrics"
      },
      "period": {
        "type": "string",
        "description": "Optional filing period, e.g. FY2025"
      },
      "limit": {
        "type": "number",
        "description": "Optional peer limit, default 5"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    },
    "required": ["sector_or_industry"]
  }
}
```

---

### Tool 8: `query_fomc_dotplot`
**Description:** Returns certified Federal Reserve FOMC Summary of Economic Projections (SEP) Dot Plot interest rate projections across projection horizons.

**JSON Schema:**
```json
{
  "name": "query_fomc_dotplot",
  "description": "Returns certified Federal Reserve FOMC Summary of Economic Projections (SEP) Dot Plot interest rate projections across projection horizons.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "year": {
        "type": "string",
        "description": "Optional projection year (e.g. '2024', '2025', '2026', 'longer_run', 'all')"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    }
  }
}
```

---

### Tool 9: `query_macro_indicator`
**Description:** Returns certified macroeconomic indicators from Federal Reserve (FRED), BLS, and BEA (e.g. DFF, CPIAUCSL, PCEPILFE, GDPC1, UNRATE, DCOILWTICO, DTWEXBGS) with cryptographic provenance.

**JSON Schema:**
```json
{
  "name": "query_macro_indicator",
  "description": "Returns certified macroeconomic indicators from Federal Reserve (FRED), BLS, and BEA with cryptographic provenance.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "series_id": {
        "type": "string",
        "description": "FRED/Macro series ID (e.g. 'DFF', 'CPIAUCSL', 'PCEPILFE', 'GDPC1', 'UNRATE', 'DCOILWTICO', 'DTWEXBGS')"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    },
    "required": ["series_id"]
  }
}
```

---

### Tool 10: `query_treasury_curve`
**Description:** Returns certified U.S. Treasury benchmark yield curves across 13 constant maturity tenors (1M to 30Y) and key spreads (10Y-2Y, 10Y-3M).

**JSON Schema:**
```json
{
  "name": "query_treasury_curve",
  "description": "Returns certified U.S. Treasury benchmark yield curves across 13 constant maturity tenors (1M to 30Y) and key spreads (10Y-2Y, 10Y-3M).",
  "inputSchema": {
    "type": "object",
    "properties": {
      "tenor": {
        "type": "string",
        "description": "Optional Treasury constant maturity tenor (e.g. '1M', '2M', '3M', '6M', '1Y', '2Y', '5Y', '10Y', '30Y', '10Y-2Y', '10Y-3M', or 'all')"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    }
  }
}
```

---

### Tool 11: `stress_test_portfolio`
**Description:** Executes deterministic multi-regime stress testing on asset portfolios against macroeconomic shock vectors (10Y yield surges, oil shocks, dollar shocks, credit spread widening).

**JSON Schema:**
```json
{
  "name": "stress_test_portfolio",
  "description": "Executes deterministic multi-regime stress testing on asset portfolios against macroeconomic shock vectors.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "positions": {
        "type": "array",
        "description": "Portfolio holdings list (array of {ticker, exposure_usd, ...})"
      },
      "macro_shock_vector": {
        "type": "object",
        "description": "Macroeconomic shock vector: {us10y_yield_delta_bps, crude_oil_delta_pct, usd_index_delta_pct, credit_spread_bps}"
      },
      "scenario_name": {
        "type": "string",
        "description": "Optional scenario name"
      },
      "covenant_threshold": {
        "type": "number",
        "description": "Optional minimum allowable ICR covenant threshold floor (default 1.50)"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    }
  }
}
```

---

### Tool 12: `simulate_macro_regime`
**Description:** Simulates deterministic corporate debt and covenant impacts under specific macroeconomic regime basins (stagflation, recession, soft landing, liquidity squeeze, yield curve inversion) across enterprise filers.

**JSON Schema:**
```json
{
  "name": "simulate_macro_regime",
  "description": "Simulates deterministic corporate debt and covenant impacts under specific macroeconomic regime basins.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "regime": {
        "type": "string",
        "description": "Macroeconomic regime ID or basin name (e.g. 'regime:basin:stagflation', 'regime:basin:recession', 'soft_landing', 'liquidity_squeeze', 'yield_curve_inversion')"
      },
      "tickers": {
        "type": "string",
        "description": "Optional comma-separated tickers (defaults to 'ORCL,BA,INTC,AAPL,MSFT')"
      },
      "custom_rate_bps": {
        "type": "number",
        "description": "Optional custom 10Y yield spike in basis points"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    },
    "required": ["regime"]
  }
}
```

---

### Tool 13: `verify_financial_claim`
**Description:** Topologically verifies numbers, dates, XBRL financial metrics, and causal statements in generated text against the frozen A4 lattice in <5ms. Generates cryptographic SHA-256 Merkle audit seals and auto-correction payloads.

**JSON Schema:**
```json
{
  "name": "verify_financial_claim",
  "description": "Topologically verifies numbers, dates, XBRL financial metrics, and causal statements in generated text against ground truth in <5ms.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "generated_text": {
        "type": "string",
        "description": "The financial text, model completion, or claim string to verify against SEC EDGAR ground truth"
      },
      "compliance_strictness": {
        "type": "string",
        "description": "Optional compliance policy: 'FAIL_CLOSED', 'AUTO_CORRECT', or 'STRICT' (defaults to 'FAIL_CLOSED')"
      },
      "tolerance_pct": {
        "type": "number",
        "description": "Optional allowable discrepancy percentage for numerical facts (default: 0.5%)"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    },
    "required": ["generated_text"]
  }
}
```

---

### Tool 14: `firewall_audit_trail`
**Description:** Returns real-time Domain 18 Hallucination Firewall telemetry, sub-5ms latency verification benchmarks, and cryptographic SHA-256 Merkle audit trail records.

**JSON Schema:**
```json
{
  "name": "firewall_audit_trail",
  "description": "Returns real-time Domain 18 Hallucination Firewall telemetry, sub-5ms latency verification benchmarks, and cryptographic SHA-256 Merkle audit trail records.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "audit_hash": {
        "type": "string",
        "description": "Optional specific SHA-256 Merkle proof seal to look up in the audit ledger"
      },
      "low_tokens": {
        "type": "boolean",
        "description": "Optional. When true, returns compact JSON schema."
      }
    }
  }
}
```

---

## 5. The 12 Valuation Packs Specification

| Pack ID | Pack Name | Required SEC XBRL Metrics | Compositions Output |
|---|---|---|---|
| `equity_screen` | Equity Screening | `revenue`, `net_income`, `diluted_eps`, `equity`, `total_assets` | Standard fundamental metrics summary |
| `ev_bridge` | EV Bridge | `cash`, `total_debt` | `net_debt_v1` = Total Debt - Cash |
| `quality_of_earnings` | Earnings Quality | `net_income`, `cfo`, `sbc`, `cogs` | `fcf_v1`, `fcf_conversion_v1`, `owner_earnings_v1` |
| `segment_mix` | Segment Revenue Mix | `total_revenue`, Item 1 disclosures | Breakdown by operating business unit |
| `returns_screen` | Return Multiples | `equity`, `total_assets`, `net_income`, `operating_income` | `roe_v1`, `roa_v1`, `roic_v1` |
| `leverage_screen` | Debt & Solvency | `operating_income`, `interest_expense`, `total_debt`, `cash` | `interest_coverage_v1`, `net_debt_to_ebitda_v1` |
| `piotroski_f` | Piotroski F-Score | `net_income`, `cfo`, `total_assets`, `equity`, `total_debt`, `current_assets`, `current_liabilities`, `diluted_shares`, `total_revenue` | `piotroski_f_v1` (Score 0–9 integer) |
| `altman_z_prime` | Altman Z'-Score | `total_assets`, `total_liabilities`, `current_assets`, `current_liabilities`, `retained_earnings`, `operating_income`, `equity`, `total_revenue` | `altman_z_prime_v1` (Distress indicator) |
| `beneish_m_score` | Beneish M-Score | `net_income`, `cfo`, `total_assets`, `total_revenue`, `current_assets`, `total_liabilities` | `beneish_m_score_v1` (Manipulation index) |
| `dupont_5step` | 5-Step DuPont ROE | `net_income`, `operating_income`, `total_revenue`, `total_assets`, `equity` | `dupont_5step_v1`, `dupont_tax_burden_v1`, `dupont_ebit_margin_v1`, `dupont_asset_turnover_v1`, `dupont_financial_leverage_v1` |
| `working_capital_efficiency` | Working Capital | `total_revenue`, `cogs`, `current_assets`, `current_liabilities` | `working_capital_efficiency_v1`, `dpo_days_v1` |
| `dcf_valuation_inputs` | DCF Historical Inputs | `cfo`, `capex`, `total_revenue`, `operating_income`, `equity` | `dcf_valuation_inputs_v1`, `fcf_margin_v1`, `reinvestment_rate_v1` |

---

## 6. Domain 31 Deterministic Lattice Arithmetic

All arithmetic operations avoid language model math and run deterministic Go float64 algorithms verified against IEEE 754 log-domain standards.

Supported operations (`op`):
- `cagr`: $(V_{\text{end}} / V_{\text{start}})^{1/N} - 1$ where $N = \text{len(periods)} - 1$.
- `ratio` or `div`: $V_A / V_B$
- `multiply` or `mul`: $V_A \times V_B$
- `add` or `sum`: $V_A + V_B$
- `sub` or `diff`: $V_A - V_B$
- `growth` or `pct_change`: $(V_{\text{new}} - V_{\text{old}}) / |V_{\text{old}}|$
- `margin`: $V_{\text{numerator}} / V_{\text{revenue}}$
- `yoy_series`: Array of $(V_{t} - V_{t-1}) / V_{t-1}$ across all consecutive periods.
- `product_chain`: Multiplicative accumulation $\prod_{i} F_i$.

---

## 7. Client Configuration Snippets

### Cursor (`.cursor/mcp.json` or `~/.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "finsec": {
      "url": "https://finsec.caleralabs.com/mcp",
      "headers": {
        "X-License-Key": "clabs_live_YOUR_KEY"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "finsec": {
      "url": "https://finsec.caleralabs.com/mcp",
      "headers": {
        "X-License-Key": "clabs_live_YOUR_KEY"
      }
    }
  }
}
```

### Windsurf / Cline (`~/.codeium/windsurf/mcp_config.json`)
```json
{
  "mcpServers": {
    "finsec": {
      "serverUrl": "https://finsec.caleralabs.com/mcp",
      "headers": {
        "X-License-Key": "clabs_live_YOUR_KEY"
      }
    }
  }
}
```

### VS Code (`settings.json` / VS Code MCP Extension)
```json
{
  "servers": {
    "finsec": {
      "url": "https://finsec.caleralabs.com/mcp",
      "headers": {
        "X-License-Key": "clabs_live_YOUR_KEY"
      }
    }
  }
}
```

### Zed Editor (`~/.config/zed/settings.json`)
```json
{
  "context_servers": {
    "finsec": {
      "endpoint": "https://finsec.caleralabs.com/mcp",
      "headers": {
        "X-License-Key": "clabs_live_YOUR_KEY"
      }
    }
  }
}
```

---

## 8. HTTP Status & Error Handling Matrix

| HTTP Code | Server Status | Meaning | LLM Agent Handling |
|---|---|---|---|
| `200 OK` | `VERIFIED_SUCCESS` | Verified fact returned with SHA-256 provenance. | Parse result; cite verified accession and period. |
| `200 OK` | `SAFE_REFUSAL` | Fact not present in audited SEC filing lattice. | **Report refusal honestly.** Inform user fact is absent. Do NOT invent numbers. |
| `200 OK` | `EVENT_ACK_PENDING_FACTS` | 8-K filing detected, certified XBRL parsing in progress. | Advise user filing is registered; facts pre-warming. |
| `400 Bad Request` | `BAD_REQUEST` | Malformed JSON or invalid parameter. | Inspect error message and correct payload syntax. |
| `401 Unauthorized` | `UNAUTHORIZED` | Missing or invalid OAuth Bearer or `X-License-Key`. | Prompt user to provide active FinanceSec license key. |
| `402 Payment Required`| `PAYMENT_REQUIRED`| License expired or quota exhausted. | Direct user to https://dashboard.caleralabs.com/dashboard?domain=finsec |
| `422 Unprocessable`| `REFUSED` | Pre-trade risk rule or validation rejected. | Abort trade route. Read `refusal_reason`. |
| `429 Too Many Requests`| `RATE_LIMITED` | Quota or RPM limit exceeded. | Stop retry loops immediately. Direct to dashboard. |
| `503 Unavailable` | `NOT_READY` | Substrate pre-warming or updating. | Backoff and poll `GET /readyz`. |

---

## 9. Direct Curl & Python Ingestion Examples

### Natural Language Fact Query
```bash
curl -sS -X POST https://financesec.api.caleralabs.com/api/query \
  -H "Content-Type: application/json" \
  -H "X-License-Key: clabs_live_YOUR_KEY" \
  -d '{"query": "What was Microsoft net income in FY2023?", "low_tokens": true}'
```

### Certified DCF Inputs Pack
```bash
curl -sS -X POST https://financesec.api.caleralabs.com/api/packs/valuation-inputs \
  -H "Content-Type: application/json" \
  -H "X-License-Key: clabs_live_YOUR_KEY" \
  -d '{"company": "NVDA", "pack": "dcf_valuation_inputs", "period": "FY2024"}'
```

### Deterministic 3-Year CAGR Evaluation
```bash
curl -sS -X POST https://financesec.api.caleralabs.com/api/arith/evaluate \
  -H "Content-Type: application/json" \
  -H "X-License-Key: clabs_live_YOUR_KEY" \
  -d '{"op": "cagr", "value_a": 274515000000, "value_b": 383285000000, "periods": ["FY2020", "FY2021", "FY2022", "FY2023"]}'
```