MCP technical reference

For analysts and client developers who want the tool details, result metadata and limits. To get connected, use the three-step connection guide.

Available analysis

The interface provides eight tools. Every calculation requires preparation with an explicit objective: "dollar" or "coin". Technical validation can still disclose legacy defaults; it does not establish the Holder’s intent or authorise a calculation. One connection and token serve both objectives. The MCP preparation requirement changes neither the access-token setup nor the REST request contract.

For a Coin question, use run_scenario with objective: "coin" for one path. Read result.research.outcome.coin for the BTC IRR and its matching diagnostics, and coin_holding for the amounts. Supporting USD fields cannot replace missing BTC values. For Monte Carlo, collect raw hedge_risk_samples observations using matching assumptions, engine identity and valuation seed; combine raw samples rather than averaging batch percentiles.

Prepare an analysis

prepare_analysis takes question, analysis: {tool, arguments} and context. Context records objective, capital_basis, benchmark, defaults_policy, assumptions_note, horizon_note and, when hedges are selected, hedge_constraints.

• capital_basis: "dated_agreement_flows" describes the supported research. "fixed_wallet" is refused: reserves, recycling, borrowing limits and daily margin do not become a funded portfolio simulation merely by choosing an Agreement count.
• Benchmarks are holding_matched_btc for Coin, usd_cash_flows for Dollar, usd_discounted_hurdle for Dollar hedge_risk_samples, and unhedged_agreements for either objective.
• defaults_policy: "program_defaults" requires an explicitly accepted named preset: dollar-research-v1, coin-research-v1 or legacy-engine-bridge-v1. Their values come from the server’s shared preset catalogue. "explicit_inputs" requires complete numerical inputs. Supplied overrides and remaining defaults are disclosed separately.

The result.status is needs_clarification, unsupported or ready. Clarification returns at most three questions plus a count of questions still remaining; the assistant should ask only what has not already been answered. A ready response supplies brief, assumptions_preview, canonical_analysis, provenance and next_call. Show the material assumptions before calling next_call.tool with next_call.arguments unchanged.

All five outcome-producing tools require a preparation object beside their canonical arguments. It is signed, valid for one hour and bound to the tool, inputs, brief and engine identity. Missing, changed, expired or incompatible preparations are refused. The receipt proves server preparation, not human approval, calibration or funding feasibility, and is not an access token. An assistant must not invent answers to missing questions to obtain it.

The optional MCP prompt start_analysis takes no arguments. Resources forwardflow://guides/analyst-v1 and forwardflow://presets/research-v1 expose the shared analyst guide and preset catalogue. describe_model also returns the guide. Clients choose how to surface prompts and resources; connecting does not install a local skill or guarantee automatic guide ingestion.

Ask and inspect

For example:

Use the illustrative legacy-engine-bridge-v1 preset, with a permanent 40% Bitcoin shock starting in month six over one month, and a 60% lifetime baseline stop rate over the Agreement term. Use the Dollar objective and dated Agreement flows against contributed USD, retaining the preset’s term, origination pacing and horizon. Run 128 seeds and show USD cash-loss frequency beside USD effective annual IRR. State all other assumptions before calculating.

The assistant can first call validate_scenario with:

{
  "config": {
    "shock": {
      "start_month": 6,
      "drop_pct": 0.4,
      "duration_months": 1,
      "recover_to_pct": null
    },
    "scenario": { "BaselineCurve": { "lifetime": 0.6 } }
  },
  "runs": 128,
  "objective": "dollar"
}

This is a technical validation example, not a calculation-ready request. The assistant then sends the question, proposed run_scenario arguments and established context to prepare_analysis, names the accepted preset, explains the preview and uses its next_call. A supplied nested object replaces that entire object. Unknown fields, including misspellings within nested objects, are refused. The assistant should clarify material ambiguities such as annual versus lifetime stop rates, the time of a shock, its recovery, USD versus BTC, or nominal versus effective returns.

compare_scenarios takes baseline and alternative objects. The alternative inherits the resolved baseline and changes only its supplied top-level fields. Both sides use the same seed and a common market horizon large enough for both books; conflicting explicit horizons or seeds are refused. The canonical inputs disclose this normalization. Changing book dimensions or Buyer behavior can change the mapping of random draws to Agreements even with the same seed. Side-by-side percentiles are not a confidence interval for the difference.

Read the result

Each successful answer contains:

• result: the existing engine outputs, or model/validation metadata. Single simulations retain conservation status and currency-specific scalar output flags. Coin runs also include the complete research outcome, Coin root diagnostics and conversion/benchmark conventions. Monte Carlo retains cash-loss frequency, missing-IRR counts, ambiguity counts and the engine’s explanatory note. Hedge outputs retain surface warnings and conventions.
• warnings and defaulted_fields: interpretation cautions and which assumptions were filled in.
• engine: model specification, API version, source build and historical-data digest.
• analysis_brief: on calculations, the verified prepared brief and its assumptions/provenance. Its caller statements are not independently verified human consent.
• replay: the tool name, complete resolved arguments and engine identity.
• run_id: SHA-256 of the canonical replay object; result_sha256: SHA-256 of the returned result object. Canonical JSON uses recursively sorted object keys, no extra whitespace, and the Rust serializer’s numeric representation.

Save replay, analysis_brief and the result in the client. Replay contains the complete numerical arguments without the expiring preparation. Send those saved arguments and the original brief through prepare_analysis, then execute the new next_call. The same complete numerical inputs, engine build, data and runtime reproduce the numerical result. Check the original identity before interpreting a replay: another build or data set is a new comparison. run_id is a content identifier, not a secret, saved-run URL, or lookup token. There is no get_run store. Preparation and default-disclosure metadata can differ; the numerical result and its digest remain the same.

Set include_series: true on scenario/validation/comparison tools to request monthly exhibits when running. Otherwise the response omits the ordinary price/cash series and USD Monte Carlo histograms; the Coin research outcome retains its reconciliation data and conventions. Raw postings and individual Agreement rows are never sent through these MCP tools. The API remains available for those exhibits.

Rates are fractions: 0.12 is 12%. Decimal money-related inputs such as purchase_pct_of_strike are strings: "0.95" is 95% of strike. haircut is a log discount, not a percentage subtraction. Null IRRs remain unavailable, and ambiguous IRRs retain their flags. Model outcomes and stylised option surfaces are not live quotes or forecasts; MCP access does not itself establish the model’s suitability for an investment decision.

Capacity and lifecycle

backend/src/mcp.rs enforces these bounds in addition to the existing engine validation and shared capacity limits:

Each named key has 120 requests per rolling minute and four concurrent slots for MCP, including protocol calls. A party’s REST and MCP requests share its allowance. These counters and the compute/memory budgets are per server process; multiple machines do not share a distributed quota. Explicit open mode counts anonymous MCP callers by IP in a separate rate state; a shared AI gateway IP may group several people. All MCP calculations use the existing global gate of three active heavy computations and at most eight queued requests. Every executed request reserves memory from the same process budget as the API. Calculations for comparison sides run sequentially. A cached Monte Carlo answer requires no new computation.

Rate/concurrency refusals use HTTP 429 and Retry-After. Engine capacity refusals inside a tool return MCP isError: true with a structured error including status 503 and the engine’s actual retry_after_secs (5 for memory pressure, 10 for a full compute queue). Invalid assumptions return a tool error with status 400. Authentication and transport failures use HTTP statuses. Retrying a completed request is safe because these tools have no persistent side effects, though retries may repeat computation.

The official Rust MCP SDK provides Streamable HTTP, protocol negotiation, discovery and JSON tool responses. Legacy protocol sessions are disabled; there is no per-connection session store to grow. A disconnect or deadline drops the API future and requests cooperative cancellation. A running seed or single simulation finishes its current engine unit before compute resources are released. A single simulation retains its memory reservation while the typed result is converted for MCP; this is not a reservation for the complete subsequent MCP envelope or its transport lifetime. No asynchronous job polling, saved scenarios, OAuth accounts, external data feeds, or trade execution are implemented here.

ChatGPT

Client documentation checked 14 September 2026. ChatGPT desktop supports ForwardFlow’s access-token connection. Set Authorization to Bearer YOUR_ACCESS_TOKEN under Headers, using your own token. See the desktop connection guide or the Codex CLI and IDE option.

The Bearer token env var field expects an environment-variable name, not the token value. The Headers from environment variables fields also read their values from the environment. Leave both empty when using the static Authorization header above. The desktop app, Codex CLI and IDE extension share MCP configuration on the same Codex host. See OpenAI’s MCP documentation.

ChatGPT web uses a separate connection setup. It does not read the desktop app’s local MCP configuration. Hosted ChatGPT Work chats can use tools supplied by installed plugins. The separate developer-mode guide describes OAuth, no authentication and mixed OAuth/no-auth connections. ForwardFlow requires a static access key and does not implement OAuth, so that developer-mode flow is not a documented direct connection for this service. Choosing no authentication will not bypass the key requirement. Saving the desktop connection does not enable it on the web.

GPT Actions supports API-key authentication over REST as another web integration. A custom GPT must use selected operations from the hosted OpenAPI schema, with the party’s key saved in the Action’s authentication settings. There is no curated, tested Actions or hosted-plugin package in this release. Availability depends on the ChatGPT account and workspace. The documented direct setups are local ChatGPT desktop/Codex clients and Claude Code.

Connection help

Opening the MCP URL in a browser is not a connection test: the browser does not supply your access token or perform MCP discovery. Use the client’s status panel and the first question in the connection guide. The public engine health page reports the running build; it does not validate your key.

For key issuance and deployment, see MCP service operations.

hedge_risk_samples

Paired research observations for 0–8 strategies and 1–32 seeds per call (at most 8 with include_monthly: true). Supports config, structures, surface, option_rate, put_skew_points, exec_cost_bps, discount_rate_annual, valuation_seed, and objective (dollar or coin). Defaults are disclosed in the reply. Every seed reuses one Agreement book across its overlays. The result includes dollar/coin economic outcomes, NPV, cash requirements and paper exposure peaks; exact request and engine identity accompany the result. structures: [] requests only the unhedged book. Cross-book collars are excluded.

Join raw observations from non-overlapping batches only when assumptions and engine/data identity match. Use the same seed ranges for strategy/stress comparisons, and different ranges for a separate sampling check. Report tail sample size and uncertainty; cash allowance exceedance is a monthly screen without daily collateral or forced closure. Definitions and workflow.

Choose the objective before comparing strategies. For example, “Use the Coin objective. Compare these hedges with the unhedged Agreements and holding the same dated BTC contributions. Show BTC shortfall, sampling uncertainty and the separate USD cash requirement.” MCP calculations require an explicit prepared objective. An unresolved objective returns clarification before a calculation is issued. A single connection and access token serves both objectives.

coin_holding and versioned conventions identify the same benchmark as the browser. BTC shortfall is max(0, -net_gain_coins); average the worst 5% of nonnegative shortfall sample mass for tail loss. Pair strategies with unhedged on each identical seed using BTC surplus differences for Coin, or USD NPV differences for Dollar. Never discount BTC with the supplied USD rate. Contributions are strategy-specific net monthly economic outlays, including modeled hedge costs and horizon marks; reserves and borrowed capital are excluded. Economic recovery is not a realized wallet balance. The cash-retained USD screen and BTC conversion are separate readings, without jointly funded wallet/margin feasibility. Benchmark definitions.

BTC amounts and return language

BTC cash-flow IRR is a useful annual return on dated investment flows after the included costs. A single 100 BTC contribution and 110 BTC recovery means 10% total return; it is not necessarily 10% annualized IRR. State the dates and intermediate flows. Ratios are ×, amounts are BTC equivalents, and annualized rates are %. A missing Coin IRR keeps its own reason and must not hide a known BTC loss.

Gross Agreement purchases differ from net monthly contributions, and economic recovery can include unpaid horizon value. Show realized-cash contribution/recovery separately from signed derivative marks. Holder receipts already reflect their contractual deductions; do not deduct those fees again. Additional conversion costs, reserves and omitted collateral are not silently included. Reporting in BTC does not claim BTC settlement or a funded wallet. Research holding retains each strategy’s matching dated contributions; legacy one-coin shelf references are not equal-budget rankings.