# Frankencoin MCP Server

> Real-time Frankencoin (ZCHF) protocol data exposed as Model Context Protocol (MCP) tools and a plain JSON REST API. Read-only, public, no API key or authentication required.

Frankencoin is a decentralized, over-collateralized Swiss-Franc stablecoin (ZCHF) with an FPS pool-share token. This server surfaces live supply, prices, peg health, savings rates, minting positions, liquidation challenges, governance, news/merch, and historical analytics across every supported chain.

Base URL: https://mcp.frankencoin.com

## How to use

- **MCP (Streamable HTTP)** — for AI agents, Claude Desktop, Cursor: `POST https://mcp.frankencoin.com/mcp`. Run the MCP `initialize` handshake, then `tools/list` / `tools/call`. Legacy SSE clients: `GET https://mcp.frankencoin.com/sse`.
- **REST** — no session required: `GET https://mcp.frankencoin.com/api/<tool>[?param=value]`. Example: `curl https://mcp.frankencoin.com/api/get_protocol_snapshot`.
- **Raw indexer** — `POST https://mcp.frankencoin.com/api/query_ponder` with a read-only GraphQL query.
- **Self-describing manifests** — `GET https://mcp.frankencoin.com/health` and `GET https://mcp.frankencoin.com/api`.

All responses are JSON. The API is read-only and rate limited; upstream data is cached briefly for low latency.

## Tools (16)

Each tool is callable as `GET /api/<name>` (REST) or via MCP `tools/call`.

- **get_protocol_snapshot** — Full live state of the Frankencoin (ZCHF) protocol in one call. Returns: total supply + per-chain breakdown, TVL, FPS price/supply/market cap/reserve/earnings (earnings are cumulative all-time), savings lead rate + base rate + pending proposals, and active challenge count. Every monetary figure is a { chf, usd } pair (USD derived at the current CHF/USD rate, exposed in the top-level `fx` block). Best starting point for any protocol question.
- **get_market_data** — Live market data: ZCHF peg health (price vs CHF, deviation, status), FPS price, all ecosystem token prices (collateral + ZCHF + FPS), CHF stablecoin comparison (ZCHF vs VCHF vs CHFAU — peg, market cap, volume, supply), macro context (BTC, ETH prices + 24h changes), and accepted collateral token prices with 24h changes. Every price/market-cap/volume is a { chf, usd } pair (the side a source omits is derived at the current CHF/USD rate; see the `fx` block). One call for everything price/market related.
- **get_savings** — Complete savings picture: current approved rates per chain/module, any pending rate proposals, plus per-module stats (total deposited, interest paid, withdrawals, event counts). Monetary figures are { chf, usd } pairs (USD derived at the current CHF/USD rate; see the `fx` block). Combines rate governance state with TVL/flow data in one call.
- **get_governance** — Governance activity: rate proposals (pending/past), minter applications (pending/denied/all), FPS equity trades (buy/sell), and FPS/ZCHF holder stats from Dune. Use 'type' to select what governance data to return. _Params: `type`, `status`, `limit`._
- **get_positions** — ZCHF minting positions. By default returns address list + count (lightweight). Set detail=true for full on-chain data: collateral type/balance, minted amount, available capacity, liquidation price, collateral ratio, risk premium, expiry, cooldown, and live market prices. _Params: `detail`, `limit`, `active_only`, `collateral`._
- **get_challenges** — Liquidation challenges against collateral positions. Returns challenge status, size, bids, timing, collateral details, liquidation price, and position context. _Params: `limit`, `active_only`._
- **get_collaterals** — List all accepted collateral types in the Frankencoin protocol — token names, symbols, addresses, decimals, and which chain they're on.
- **get_analytics** — Historical protocol analytics. Use 'type' to select: 'time_series' (daily supply, equity, savings, FPS price, rates, earnings — default), 'trades' (FPS equity buy/sell trades), 'minters' (minter application history), 'rate_history' (governance rate change timeline). Historical monetary values are in CHF only — no historical USD is provided (applying today's rate to past rows would be inaccurate); the current CHF/USD rate is exposed in the `fx` block for approximate conversion. _Params: `type`, `days`, `limit`._
- **get_knowledge** — All explanatory and reference content about Frankencoin. Use 'topic' to select: 'overview' (default — what is Frankencoin), 'faq', 'savings' (savings guide), 'governance', 'minting' (minting guide), 'opening_positions', 'auctions', 'risks', 'reserve', 'pool_shares' (FPS explanation), 'api' (API docs), 'compliance' (Swiss/EU legal classifications, papers, audits), 'frontends' (independent third-party dapps/interfaces for the protocol), 'token_addresses' (contract addresses all chains), 'links' (all key URLs + exchanges), 'what_is' (same as overview). _Params: `topic`._
- **get_news** — Frankencoin media coverage: press articles (titles, sources, dates, URLs), videos, real-world use cases, and ecosystem partners. Sourced live from the Frankencoin website repository.
- **get_insurance_products** — ZCHF-related third-party insurance products exposed as a dedicated ecosystem feature. Returns live/curated insurance products, including provider, category/type (e.g. depeg cover), covered risk, URL, pricing, capacity, purchase flow, and Frankencoin Association role disclaimer. Use this for OpenCover ZCHF depeg cover and future ZCHF insurance integrations — not get_news.
- **get_merch** — Frankencoin merch store (merch.frankencoin.com). Returns a product snapshot (titles, prices, variants, images, URLs) PLUS `directAccess`: the store's native Shopify MCP endpoints so an agent can interact with the store DIRECTLY — live catalog search, cart, and checkout — instead of through this read-only server. Use directAccess for anything transactional; the product list is a convenience snapshot.
- **get_compliance** — Frankencoin (ZCHF) legal & regulatory compliance — every relevant paper and link in one call. Returns: Swiss FINMA classification (payment token, LEXR legal assessment + PDF), EU MiCA classification (no identifiable issuer, LEXR legal opinion + PDF), the ZCHF MiCA white paper and ESMA Interim MiCA Register entry, all third-party security audit reports (Code4rena, Decurity, ChainSecurity, BlockBite), the Compass Security bug-bounty programme, the compliance contact, and the legal disclaimer. Informational only — not legal advice.
- **get_risk** — Independent third-party risk ratings for Frankencoin (ZCHF) — the same ratings shown on frankencoin.com. 'pharos' returns the Pharos stablecoin-safety report card: an overall grade + 0–100 score plus five scored dimensions (peg stability, liquidity/exit capacity, resilience, decentralization, dependency risk). 'xerberus' returns Xerberus composite on-chain risk scores (0–100) for the Frankencoin protocol, DAO, and Ethereum savings vault. Ratings are produced by external protocols, NOT the Frankencoin DAO. Use 'source' to select (default 'all'). _Params: `source`._
- **get_dune_stats** — On-chain analytics from Dune Analytics — ZCHF holder count, FPS holder count, historical minting volume, and savings TVL over time. Data may be slightly delayed vs real-time.
- **query_ponder** — Execute a raw GraphQL query against the Frankencoin on-chain indexer at ponder.frankencoin.com. Read-only queries only. Available entities: mintingHubV2PositionV2s, mintingHubV1PositionV1s, mintingHubV2ChallengeV2s, mintingHubV1ChallengeV1s, equityTrades, analyticDailyLogs, savingsActivity, savingsMappings, frankencoinMinters, eRC20Balances, eRC20TotalSupplys, leadrateRateChangeds, frankencoinProfitLosss, equityTradeCharts. _Params: `query*`._

Parameters marked `*` are required. Full parameter details live in each tool's MCP inputSchema (`tools/list`) and in `GET /api`.

## Notes

- No authentication — public, read-only protocol data.
- Some fields depend on server-side API keys (CoinGecko, Dune); when absent, the affected tool returns partial data plus a `note` instead of failing.
- Token amounts are decoded to human-readable numbers; rates are percentages.
- Source, docs, and issues: https://github.com/Frankencoin-ZCHF/frankencoin-mcp