@seshat_oracle/kronos-mcp

MCP stdio server for Seshat Kronos Quant Signal.

Tools

Free (no wallet required)

| Tool | Description | |------|-------------| | kronos_catalog | Symbols, timeframes, model config, products, prices | | kronos_sample | Delayed real BTC model output for testing | | kronos_risk | Current operational risk state, streak, cooldown | | kronos_accuracy_preview | Aggregate hit rate and Brier score (rounded) | | kronos_conviction_signals | Top 3 non-BTC symbols by prediction strength | | kronos_composite_preview | Quant vs Crowd divergence preview | | kronos_benchmark_preview | Leaderboard preview (fixed 7-day window) | | kronos_decision | Single auditable decision record by ID |

Paid (requires x402 buyer wallet)

| Tool | Price | Description | |------|-------|-------------| | kronos_predict | $0.01/TF | Fresh on-demand forecast (cap $0.04) | | kronos_forecast_distribution | $0.01/TF | Full sample distribution with percentiles | | kronos_accuracy | $0.001 | Model accuracy with baselines | | kronos_accuracy_candles | $0.005 | Per-timeframe MAPE and MAE | | kronos_risk_history | $0.02 | Historical streak analytics | | kronos_decisions | $0.001 | Browse recent predictions | | kronos_forecast_evolution | $0.005 | How forecasts change over time | | kronos_historical_analogs | $0.01 | Past similar situations and outcomes | | kronos_regime | $0.02 | Cross-symbol market regime detection | | kronos_agent_track_record | $0.001 | Kronos as market voter — win rate, Brier | | kronos_agent_votes | $0.003 | Recent votes with market context | | kronos_agent_signals | $0.005 | Open markets with vote status | | kronos_composite | $0.01 | Quant vs Crowd divergence analysis | | kronos_confluence | $0.01 | Quant vs sentiment vs crowd tags | | kronos_benchmark | $0.02 | Full leaderboard with accuracy and Brier | | kronos_digest | $0.03 | AI cross-referenced digest (7 sources) | | kronos_market_brief | $0.05 | AI narrative with sourced news and events | | kronos_market_context | $0.03 | Cross-venue funding, OI, liquidations, IV | | kronos_similar_markets | $0.005 | Semantic similar markets by text query | | kronos_outcome_stats | $0.01 | Outcome distribution of similar markets | | kronos_behavioral_correlations | $0.01 | How similarly agents reason | | kronos_rationale_novelty | $0.01 | Detect templated vs genuine reasoning |

Run locally

npm install
npm start

Override the API for local testing:

KRONOS_API_URL=http://127.0.0.1:8787 npm start

All diagnostics must use stderr; stdout is reserved for MCP JSON-RPC traffic.

Enable buyer-side x402 payments

Free tools work without a wallet. To let paid tools sign x402 authorizations automatically, configure one or both buyer-controlled secrets in the local MCP process environment:

KRONOS_X402_EVM_PRIVATE_KEY=0x...
KRONOS_X402_SOLANA_PRIVATE_KEY=...

Use a dedicated agent wallet with only the USDC that its operator chooses to fund. Do not commit these values, add them to shared MCP configuration, send them to Kronos, or expect Kronos to create, fund, recover, or custody the wallet. The MCP has no restrictive daily spending limit; API prices and GPU rate limits remain the source of truth.

Operator spending cap

Set KRONOS_MAX_PAYMENT_USD to enforce a global per-call ceiling on every payment, independent of the per-tool caps hardcoded in the package. The effective cap for each call is min(per_tool_cap, global_cap). Set to 0 or unset to disable (default).

KRONOS_MAX_PAYMENT_USD=0.05  # reject any single payment above $0.05

This protects the operator even if a future server pricing bug or catalog change requests an unexpectedly high amount.

Configure an MCP host

Example Claude Code/Cursor-style configuration:

{
  "mcpServers": {
    "kronos": {
      "command": "npx",
      "args": ["-y", "@seshat_oracle/kronos-mcp"]
    }
  }
}

For the eventual Seshat integration, keep kronos-mcp as a focused compatibility package and compose it into a broader seshat-mcp server with namespaced tools (kronos_*, seshat_*). This avoids coupling Kronos releases to account/write capabilities while giving users one Seshat entry point when they need both.

Security — private key handling

The MCP signs x402 payments locally using a wallet private key in the process environment. This is the core security property: the key never leaves the operator's machine and is never sent to Kronos.

Inherent risk: npx -y kronos-mcp executes third-party code with access to process.env. If the npm package were ever compromised, an attacker could read the private key. This risk is inherent to any MCP that signs payments — it is not specific to kronos-mcp.

Mitigations in this package:

• No install scripts. No postinstall, preinstall, or install hooks in this package or its dependencies.
• Minimal tarball. 7 files, ~8 KB. The files allowlist in package.json ensures only src/, test/, and README.md are published — no stray files can slip in.
• Pinned versions. All dependencies are pinned to exact versions (no ^ or ~ ranges) to prevent transitive dependency substitution.
• Dynamic import. Payment dependencies (@x402/evm, @x402/svm, viem, @solana/kit, @scure/base) are loaded lazily only when a private key is configured. Free-only usage never loads them.
• No network calls except to the Kronos API. The client only connects to https://kronos.seshat.markets (hardcoded origin allowlist). No telemetry, no analytics, no phone-home. KRONOS_API_URL can override the base URL, but the origin is validated against the allowlist — any non-allowed origin is rejected before any request is made.
• Payment authorization. Before signing any payment, the MCP validates the 402 challenge: network must be Solana mainnet or Base mainnet, asset must be USDC, payTo must be a Kronos server wallet, and the resource URL origin must match the requested origin. If any check fails, payment is aborted. These allowlists are hardcoded — not configurable via env vars — so a compromised server cannot redirect payments to arbitrary recipients.
• Prompt injection defense. Every tool response is prefixed with a data framing marker that tells the consuming agent to treat the content as market intelligence data, not as instructions. This is defense-in-depth: the server already sanitizes external content (news, social sentiment) before generating AI briefs, but the MCP adds a second layer at the protocol level.

Recommendations for operators:

• Use a dedicated agent wallet with only the USDC you are willing to spend.
• Enable 2FA on your npm account if you are the package maintainer.
• Prefer npm Trusted Publishing (OIDC) from GitHub Actions over long-lived publish tokens.
• Pin the package version in your MCP config: npx -y @seshat_oracle/[email protected] instead of floating latest.
• Audit the installed package: npm view @seshat_oracle/kronos-mcp dist.tarball and inspect the tarball before trusting it with a funded wallet.