@panoptic-eng/mcp

A local Model Context Protocol server that exposes the Panoptic SDK to AI agents as read-only analytics tools. It runs as a stdio process against your own RPC endpoint — zero infra, zero auth, no private keys. The server only reads on-chain state; it never signs or sends transactions. Build/simulate tools that return unsigned transaction envelopes are planned for a future release (see the spec).

See packages/sdk/mcp-spec.md for the full specification and roadmap.

Quickstart

Every MCP client accepts the same command / args / env shape; only the config file location differs (Claude Code/Desktop use .mcp.json, Cursor uses its MCP settings, etc.).

{
  "mcpServers": {
    "panoptic": {
      "command": "npx",
      "args": ["-y", "@panoptic-eng/mcp"],
      "env": {
        "PANOPTIC_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/<key>",
        "PANOPTIC_CHAIN_ID": "1",
        // optional — enables enhanced analytics tools
        "PANOPTIC_SUBGRAPH_URL": ""
      }
    }
  }
}

Configuration may also be passed as CLI flags, which override the env vars:

npx @panoptic-eng/mcp --rpc-url https://eth-mainnet.g.alchemy.com/v2/<key> --chain-id 1

Supported chains: Ethereum mainnet (1), Sepolia (11155111).

v0 tools (read-only)

All tools are read-only (they never build or send transactions). The one exception to statelessness is configure_session, which mutates in-process session preferences rather than reading the chain.

| Tool | What it does | | --- | --- | | configure_session | Local session state — not an RPC read. Set/read this session's preferences — notably the preferred delta reporting frame (assetIndex) — so delta tools don't re-ask which token to denominate net delta in. State lives in the server process for the session only. | | list_pools | Known pool deployment + live pool state (tokens, tick, trackers, health). | | explain_position | Decode a TokenId into readable legs + a strategy label (no RPC). | | identify_address | Map an address to its role in a Panoptic deployment. | | get_portfolio | An account's open positions, collateral, and net greeks. | | account_health | Buying power, margin buffer, and liquidation status. | | liquidity_map | Tick liquidity distribution around the current tick. | | chunk_spread | Per-chunk spread multiplier (via scanChunks): ~1.0x chunks are cheapest to BUY (lowest IV), high-multiplier chunks are most profitable to SELL. Width defaults to a standard timescale (STANDARD_TICK_WIDTHS). | | suggest_delta_hedge | Net delta (positions + collateral) and a width=0 loan/credit leg sized to neutralize it. | | advise_position | Live facts + management advice for a position (ITM/OTM, streamia, closeable-now, liquidation risk). | | preview_position | Pre-trade quote (dry-run eth_call): collateral required, post-mint balances, solvency, for a given tokenId + size. | | position_scenario | Payoff / NLV curve — net liquidation value across a band of hypothetical prices. | | hedge_params | SDK-native delta-hedge parameters (getDeltaHedgeParams) to reach a target delta; whole-portfolio or single-position. | | trade_history | Chronological mints/burns from on-chain events (event-level only — no realized P&L). | | list_vaults | Known HypoVault deployments: vaults, managers, accountant, underlying token, pool, trackers, and strategy labels. | | vault_summary | Live HypoVault state: supply, manager/accountant, fees, epochs, reserved withdrawal assets, and current epoch totals. | | vault_account | A user's HypoVault share balance, basis, queued deposit/withdrawal, redeposit flag, and executable epoch hints. | | vault_exposure | Treat a HypoVault as the Panoptic account and return positions, collateral, greeks, and margin health. |

get_portfolio, account_health, suggest_delta_hedge, advise_position, preview_position, position_scenario, and hedge_params discover positions via an on-chain event scan (the SDK's syncPositions) — no subgraph required. Pass fromBlock to bound the scan on chains with a distant deployment block. These account tools need an RPC that permits eth_getLogs; many free public endpoints throttle or block large log scans, so a private RPC is recommended.

An account's aggregate net delta is a single figure and must be denominated in one token's units (its "reporting frame"). There is no canonical pool asset — each position leg carries its own — so suggest_delta_hedge and hedge_params (portfolio mode) resolve the frame as: explicit assetIndex argument → session preference → ask the user. When neither is set they return a needs_asset_preference prompt rather than silently guessing; call configure_session with assetIndex to record the choice for the session.

HypoVault NAV/share-price reads are intentionally not exposed in v0 because totalAssets(bytes) and convertToAssets(uint256,bytes) require managerInput-aware accounting; use vault_summary for raw vault state.

Build + simulate tools (build_position, build_strategy, simulate_tx, …) that return unsigned transaction envelopes are planned for a future release and are not shipped yet. All numeric on-chain quantities are serialized as decimal strings.

Development

pnpm --filter @panoptic-eng/mcp build       # tsdown → dist/
pnpm --filter @panoptic-eng/mcp test        # vitest
pnpm --filter @panoptic-eng/mcp typecheck   # tsc --noEmit
pnpm --filter @panoptic-eng/mcp lint

# Inspect locally against a real RPC:
PANOPTIC_RPC_URL=https://eth-mainnet.g.alchemy.com/v2/<key> PANOPTIC_CHAIN_ID=1 \
  npx @modelcontextprotocol/inspector node dist/cli.js

The server depends on @panoptic-eng/sdk; the SDK never depends on it.