Paper trading with local MCP tools

From a proposal to verifiable paper evidence

1. Supply the scenario. State equity, current positions, prices, lot sizes, risk budget and limits. Supply any spreads, liquidity and fee schedule used by the checks. The server fetches no market data for this workflow.
2. Size the proposed position. Call size_position with your budget and caps. Read the binding cap, resulting orders and any stated drawdown state. Sizing does not submit an order or run the kill-switch check.
3. Check every proposed order. Call check_orders with your market state and limits. Inspect every rejection and checks_skipped, as well as costs that could not be modelled. Your client must stop a rejected or incomplete scenario; the tool does not automatically govern later calls.
4. Record only supplied statements. Explicitly enable local journal writes, initialize a signed account with its opening cash and positions, then append supported decisions, checks, paper fills and complete valuations. Fills, prices and fees come from your scenario. A refused proposal creates no fabricated fill.
5. Verify and recompute. Use journal with verify to check the full signed chain. Export a supported account/window to recompute returns, turnover, costs and drawdown. Missing fees, incomplete valuations or unresolved reconciliation refuse export.
6. Bind the evidence to its source. Start the repository validation stdio server with CANLI_LOCAL=1. Send the complete export bundle via record_file and the original journal_file to validate_paper_evidence. Inspect bindings.checked and all_match. A valid shape without the journal leaves source facts unchecked.

The signed account and export profile defines the required payloads, explicit fees, supported events and sequence-window semantics. The paper evidence standard describes what a record must disclose.

Prepare a local MCP session

Use the reviewed repository checkout and its locked execution dependencies. Launch mcp-execution/src/server.mjs through your stdio MCP client. Configure an existing, owned 0700 home on a supported local POSIX filesystem. Writes additionally need an owned, regular, non-symlink 0600 Ed25519 PEM file named journal.key, with no extra hard link. Read the storage setup before preparing that key.

{
  "command": "node",
  "args": [
    "/absolute/canlicapital/mcp-execution/src/server.mjs"
  ],
  "env": {
    "CANLI_HOME": "/absolute/private-paper-home"
  }
}

Replace both absolute paths with your local checkout and prepared home. These are client launch settings. Send tool arguments through MCP. Keep signing material out of tool arguments.

Default mode offers head, verify and export; an export may create a private artifact. To enable initialize and append on the existing journal tool, explicitly add CANLI_EXEC_JOURNAL_WRITE=1 to the client launch environment. Read the local setup and recovery contract before enabling writes. The execution package remains private and Unreleased.

Run the bounded synthetic example

From the pinned repository root, install the execution package's locked development dependencies and run the delivered example against a fresh, prepared home:

npm ci --prefix mcp-execution
node mcp-execution/examples/paper-journal.mjs --home /absolute/private/example-home

This default makes only sizing and order-check calls. When they pass, it returns writes_disabled; it needs no key and creates no journal. After preparing the private signing key, explicitly add --write to the example command to record the supplied scenario.

The fixture opens a flat USD10,000 account, proposes ten SYNTH units from a stated 10% budget at USD100, and supplies a fill at USD100.25, an explicit USD1 fee and a USD101 mark. Those are synthetic statements, not market observations. Your limits or kill switch can cause the example to stop.

A successful write run makes at most 11 tool calls. Its nominal stdio window is 30 seconds, reserving five seconds for one close attempt; timers and trusted synchronous work are cooperative. It prints one bounded receipt with the original requests, acknowledged prefix and any pending operation. A process interruption can prevent receipt output, so preserve the local journal and any pending lock for manual review. A normal rerun stops on an existing journal; this example does not automatically recover or resubmit.

Read the complete example and stopping contract, inspect the pinned runner, or review the finite fault and roundtrip cases before extending the scenario.

The four local tools and their inputs

The hosted backtest validation server, SEC fundamentals server and research server have separate release pins. The local source validation step above is not added to their hosted or npm contracts by this guide.

Validate the complete export against its journal

Install the repository validation package's locked dependencies with npm ci --prefix mcp, then configure a separate local stdio session:

{
  "command": "node",
  "args": [
    "/absolute/canlicapital/mcp/src/server.mjs"
  ],
  "env": {
    "CANLI_LOCAL": "1"
  }
}

Keep a private JSON file containing the full export bundle, including its record, signature and financial companions. Send these placeholder paths to validate_paper_evidence, replacing them with that file and the original source journal:

{
  "record_file": "/absolute/private/export-bundle.json",
  "journal_file": "/absolute/private-paper-home/journal.jsonl"
}

CANLI_LOCAL=1 is required for files and signatures; they stay on your machine. record_file preserves full-bundle companion checks, while journal_file enables signed-source reconstruction. Inspect conformance_valid, bindings.checked, bindings.all_match and the final valid result. Without the source journal, structural conformance leaves source facts and signatures unchecked.

The local verifier and tool input schema define these repository-only arguments. This source workflow provides no hosted file upload.

Read the receipt and stop on uncertainty

A successful local write returns operation, request, entry and journal-prefix bindings. Keep its operation_id, request_sha256, entry_head, entry_seq, journal_prefix_sha256 and journal_prefix_bytes. A prefix binds the journal through that operation; later appends can change the current head.

JOURNAL_STORE_BUSY, JOURNAL_STORE_REFUSED and JOURNAL_STORE_UNCERTAIN are errors with no success receipt. Stop the client workflow and preserve the original request and files for manual review. Do not delete a pending lock based on its age or PID, and do not automatically resubmit. An uncertain write may have left partial or complete files.

An exact retry preserves the original operation ID, timestamp, kind, payload and expected head, including after later appends. Changed contents or a changed expected head conflict. The storage API has no automatic recovery command. head alone does not verify signatures; use verify for integrity.

What this workflow can establish

Signatures and replay bind the statements supplied by the key holder. They do not authenticate broker fills, prove an independent timestamp, exclude another journal, establish profitability or qualify capital deployment. The local filesystem contract observes replacements and requests persistence; software checks do not establish power-loss safety or exclude every change between checks by the same OS user.

Market inputs, fees, complete valuations and declared trial counts remain the caller's evidence. Unknown values stay unknown. A statistical or accounting check is not investment advice or a venue quote. Fresh token and latency measurements and the substantial execution release gates remain open.

Source pin: commit 00cab512f910. The machine-readable source record binds the documented schemas, storage contract and local validation surface. These are reviewed source links, not deployment or indexing evidence.

• Developer setup and repository entry
• Execution-assumptions cost calculator
• Execution and market-structure research
• Released finance MCP servers