MetaVault MCP

Multi-protocol yield intelligence for AI agents — covering Spectra Finance, Pendle, and Morpho via the Model Context Protocol.

55 tools · 3 protocols · 10+ chains · read-only · open emergence architecture · calibration intelligence · on-chain Curve quoting · Pendle logit AMM modeling · ERC-4626 health checks · yield curve term structure · historical eth_getLogs · full Pendle protocol parity (15 tools) · cross-protocol position map · cross-protocol Spectra↔Pendle comparison · veSPECTRA + vePENDLE governance · Pendle historical time-series · Morpho supply-side visibility with supplier cascade modeling · Morpho user positions & historical rates · Merkl campaign APR + expiry integration · entry path awareness · prescriptive observation boundaries · curator risk monitoring · withdrawal stress testing · rollover planning · multi-vault portfolio aggregation · pool expiry monitoring · zero web3 library dependencies

What This Does

Any AI agent (Claude, GPT, open-source) that supports MCP can query Spectra, Pendle, and Morpho in a unified interface to:

• Discover the best fixed-rate yield opportunities across 10 chains simultaneously
• Analyze specific PT/YT positions with full data (APY, TVL, liquidity, prices)
• Calculate leveraged looping strategies (Spectra PT + Morpho collateral) with auto-detected borrow rates
• Compare fixed vs. variable yields to make informed decisions
• Track wallet portfolios across all Spectra positions (PT, YT, LP) with Merkl reward integration for complete PnL
• Surface external Merkl campaign APR alongside pool and market data for both Spectra and Pendle
• Monitor pool trading volume, individual transaction activity, and cross-pool address scanning
• Quote PT trades with on-chain Curve get_dy() for exact output, falling back to math estimates
• Simulate portfolio state after a hypothetical trade (BEFORE / TRADE / AFTER with deltas)
• Scan all chains for capital-aware opportunities with price impact, effective APY, and Morpho looping analysis
• Detect YT arbitrage opportunities where IBT APR diverges from YT implied rate
• Compute real veSPECTRA boost multipliers per-pool using live on-chain data from Base, and vePENDLE voting power from Ethereum mainnet (with sPENDLE transition awareness)
• Map your full cross-protocol position in one call — Spectra + Pendle + Morpho + governance (veSPECTRA + vePENDLE), with contradiction detection (unused boost, lending vs fixed rate spreads, concentration, looper detection, expiring positions across protocols)
• Assess entry path complexity — automatically flags exotic underlyings, sw-wrapper hops, and mainnet gas friction so agents know the real cost of reaching advertised yields
• Discover live MetaVaults across all chains — curator info, TVL, APY, positions, epoch history
• Model MetaVault "double loop" strategies for curators — vault compounding + Morpho leverage with curator economics, auto-populated from live API data or manual parameters
• Monitor MetaVault operational health — curator dashboard with vault allocation per position, depositor flows, fee revenue, bridge activity, and actionable alerts
• Query Morpho lending markets for PT collateral opportunities, identify who supplies the lending liquidity, and discover vault allocations across markets
• Query protocol stats, tokenomics, and governance data
• Compare Spectra vs Pendle yield opportunities side-by-side with maturity-aware matching on overlapping chains
• Scan both Spectra and Pendle for the best curator opportunities with capital-aware sizing and cross-protocol match tagging
• Browse Pendle markets across all Pendle-supported chains (including Pendle-only chains like Mantle, Berachain, HyperEVM, Corn)
• Analyze Pendle markets in full depth — market details, portfolio tracking, trade quoting, trade simulation, looping strategies, YT arbitrage, expiry monitoring, yield curves, capacity analysis, and protocol-wide stats (full parity with Spectra tools)
• Assess pool depth with multi-size capacity curves — quote PT trades at geometric capital tiers ($1K→$1M) to find the sweet spot and exhaustion point on both Spectra and Pendle
• Verify IBT health before deploying — on-chain ERC-4626 conversion rate, APR sustainability (organic vs incentive), pool balance, protocol recognition, liquidity
• Visualize yield curves (term structure) for any underlying across all chains — all maturities sorted chronologically with curve shape analysis
• Recover historical on-chain pool activity via eth_getLogs when API data has aged out — with dynamic RPC URL support for any chain
• Monitor curator Morpho position health — liquidation distance, borrow rate drift, health factors across all chains
• Stress-test MetaVault withdrawal scenarios — liquidity waterfall analysis (idle → maturing → LP removal → PT sale) with market stress simulation
• Plan position rollovers for expiring MetaVault positions — cross-protocol candidate ranking with entry impact, yield gap, and overlap windows
• Aggregate multi-vault curator portfolios — total AUM, blended APY, fee revenue projection, concentration analysis by underlying/chain
• Monitor pool expiry across all chains with readiness assessment — successor pool detection, gauge status from governance API, and operator checklist (deploy pool / submit gauge / ready for migration)
• Learn protocol mechanics on-demand via mv_get_protocol_context (PT/YT identity, Router batching, deposit paths, glossary, fees & costs, workflow routing, externalPositions registry)
• Surface protocol YT fees (Spectra 3%, Pendle 5%) and Merkl campaign eligibility (POOL vs HOLD) directly in tool output so agents apply them without external lookups

The agent doesn't need to understand PT/YT mechanics -- it just calls spectra_scan_opportunities or pendle_scan_opportunities with its capital size and gets ranked, actionable data. For cross-protocol comparison, mv_scan_curator_opportunities ranks both protocols together. If it needs to understand why something works that way, it calls mv_get_protocol_context.

Open Emergence Architecture

The server is designed so that AI agents can discover novel strategies without being taught specific strategies. Instead of hard-coding strategy identification logic, the system teaches protocol mechanics at three layers — and lets the agent compose building blocks into its own analysis.

The Three Layers

Layer 1: Protocol Context (mv_get_protocol_context tool + resources)
  → Teaches the "physics" of the protocol: PT/YT identity, Router batching, minting
  → Available as a callable tool (on-demand) and as MCP resources
  → Static knowledge — what CAN happen, not what IS happening

Layer 2: Tool Descriptions (every tool's description string)
  → Teaches domain-specific mechanics relevant to that tool's data
  → Cross-reference nudges: "use spectra_get_portfolio to check actual holdings"
  → Uses "could be" language, not "is" — preserves ambiguity where it exists
  → Calls out hidden mechanics that could mislead (e.g., AMM_ADD_LIQUIDITY can mint YT)

Layer 3: Structured Output Hints (computed at runtime in tool output)
  → Position Shape analysis in portfolio: balance ratios (e.g., "YT/PT 4:1")
  → Portfolio Signals: concentration, maturity alerts, strategy shape across positions
  → Volume Signals: volume/liquidity ratio, buy/sell skew, trend detection
  → Morpho Market Hints: capacity warnings, utilization alerts, spread analysis, reward incentives
  → Morpho Supply-Side Analysis: supplier identification (vault/EOA/looper), concentration metrics,
    supply gap warnings — surfaces where lending liquidity comes from and whether it's sufficient
  → Competing Interpretation Branches (A/B/C) in activity analysis per-address:
    multiple explanations for the same observable pattern, presented with equal weight.
    The agent must bring external evidence to collapse branches — the tension IS the info.
  → Statistical confidence boundaries: small-N cycle repetitions (≤5) flagged as
    insufficient for extrapolation, preventing false pattern-matching
  → Flow Accounting with competing hypotheses: YT-only, PT-only, fully exited positions
    each get multiple explanations that predict different future behavior
  → Address isolation mode: cycle detection, flow accounting, contract/EOA detection,
    pool impact warnings, gas estimates, pool context
  → Capital-aware warnings: short maturity, low liquidity, negative effective APY
  → Yield Dimensions in scan output: fixed, variable, LP, looping side-by-side
  → Strategy Tension: competing PT looping vs YT accumulation on same pool
  → On-chain quote source indicators: "(on-chain Curve get_dy)" vs "(estimated)"
  → Yield composition: IBT APR breakdown (organic base vs external incentives) in scans and quotes
  → Incentive sustainability: flags when >50% of IBT APR or LP APY comes from incentives,
    shows "organic only" APY so agents can assess yield durability without incentive assumptions
  → Pool reserves: IBT/PT amounts with ratio for AMM imbalance analysis
  → Merkl campaign APR: external incentive programs (e.g., KAT rewards) shown per-pool/market
    with double-counting avoidance (skips campaigns whose reward tokens are already displayed)
  → Merkl campaign eligibility: action type (POOL/HOLD) always shown, with explicit
    "[LP only — not for YT/PT holders]" flag on POOL campaigns to prevent misattribution
  → Protocol YT fees: Spectra 3% and Pendle 5% shown in every pool/market detail output
    so agents apply them to yield calculations without needing external lookups
  → Points multipliers: external programs (Drops, InfiniFi, Firelight) with amounts
  → "Could be" / "at current rates" language: preserves ambiguity in ranked output
  → Makes key signals SALIENT without prescribing interpretation

Layer 4: Observation Coverage (quantifies blind spots in tool output)
  → Value coverage: what % of an address's position is explained by observable activity.
    Low coverage means most behavior is invisible (direct mints, transfers, cross-chain).
  → Temporal coverage: active days vs dark periods with no observable events.
    Longest gap duration surfaced so the agent can reason about invisible activity.
  → Data source coverage: which of 5 available sources were consulted vs not.
    Explicitly lists what is invisible to the current analysis.
  → Activity diversity: single-type activity flagged as highest-ambiguity pattern.
  → Boundary marker: "Position sizing should assume this analysis is incomplete,
    not comprehensive." — a structural admission of domain-of-validity limits.
  → Coverage metrics bound ALL interpretations above them. High-confidence strategy
    assessment + low observation coverage = false confidence. The coverage section
    forces the agent to size its conviction to what it actually observed.

Design Principles

• Teach mechanics, not conclusions. The server explains that AMM_ADD_LIQUIDITY could be a mint+LP batch operation — it doesn't conclude "this user is accumulating YT."
• Present competing interpretations, not single narratives. Activity analysis outputs multiple interpretation branches (A/B/C) that predict different future behavior. The agent must bring external evidence to collapse them. This friction surface prevents premature pattern-matching — the most common failure mode in wallet strategy analysis.
• Flag statistical insufficiency. Small repetition counts (≤5 cycle detections) are explicitly flagged as insufficient for extrapolation. The agent cannot treat N=3 as a confirmed pattern.
• Every tool cross-references at least one other tool. This creates analytical workflows without dictating them. The agent learns to check spectra_get_portfolio after seeing activity patterns, not because it was told to.
• Hidden mechanics are called out where they can mislead. The Spectra Router batches multiple operations atomically. A SELL_PT event might actually be YT acquisition via flash-mint. Tool descriptions teach this so agents don't draw wrong conclusions from pool data alone.
• Full addresses in output, never truncated. When addresses appear in activity data, they're shown in full so the agent can pass them directly to spectra_get_portfolio without needing a block explorer.
• Discovery tools warn about capital-awareness gaps. spectra_get_best_fixed_yields explicitly says "this ranks by raw APY — use spectra_scan_opportunities for capital-aware sizing."
• Quantify blind spots, not just interpretations. Tools now output observation coverage metrics: what percentage of behavior is visible, what data sources were consulted vs available, and how long dark periods lasted. These are not interpretations — they're structural measurements of the analysis's own incompleteness. An agent that sees 35% value coverage should size its confidence accordingly, regardless of how coherent the best-fitting interpretation looks.

Why This Matters

A cold-start agent with zero prior knowledge of the protocols can:

1. Call mv_scan_curator_opportunities — see cross-protocol (Spectra + Pendle) yield rankings with capital-aware metrics
2. Call spectra_get_pool_activity — see trading patterns with ⚠ hints about ambiguous events
3. Call spectra_get_portfolio and pendle_get_portfolio on flagged addresses — see Position Shape across both protocols
4. Read the cross-reference nudges — compose its own analytical workflow spanning all three protocols
5. Identify novel strategies the server was never explicitly programmed to detect

This was validated: a subagent spawned with zero priming correctly identified a mint-and-sell-PT loop strategy (YT accumulation via PT discount) in 3 tool calls, using only the mechanics taught in descriptions and the structured hints in output.

The competing-branch design was motivated by a real failure: an agent analyzing a multi-chain wallet collapsed all activity into "YT accumulator" despite different pools showing different patterns (spread capture, market making, LP cycling). The single-narrative failure mode — where the agent picks one interpretation and defends it — is the most dangerous because it looks like good analysis from inside.

The observation coverage layer addresses a deeper problem: even perfect interpretation of observed data is misleading when the data covers a minority of behavior. Competing branches solve the narrative problem (which story fits?). Coverage metrics solve the exposure problem (how much of the picture am I seeing?). An agent that picks the best interpretation branch but ignores 65% invisible activity is sizing conviction to coherence, not evidence.

Tools

Supported Chains

Spectra: Ethereum (mainnet), Base, Arbitrum, Optimism, Avalanche, Katana, Sonic, Flare, BSC, Monad, Hemi, HyperEVM, SEI

Pendle: Ethereum, Optimism, BSC, Sonic, Base, Arbitrum, Mantle, Berachain, HyperEVM, Corn

Morpho PT markets: Ethereum, Base, Arbitrum, Katana

Chain list maintenance (manual)

All three lists are hardcoded in src/config.ts and must be updated by hand when a protocol deploys on a new chain:

• Spectra — edit SUPPORTED_CHAINS_INTERNAL (+ CHAIN_RPC_URLS, CHAIN_RPC_FALLBACKS, CHAIN_BLOCK_TIMES, CHAIN_GAS_ESTIMATES per-chain tables). Every Spectra-native tool (metavault list, pool list, expiring pools, protocol pulse, curator dashboard, etc.) reads from this list — so one edit propagates everywhere.
• Pendle — edit PENDLE_CHAIN_IDS + PENDLE_CHAIN_NAMES. Source of truth: GET https://api-v2.pendle.finance/core/v1/chains.
• Morpho — edit MORPHO_CHAIN_IDS. Source of truth: Morpho GraphQL morphoBlue queries per chain.

There is no automated canary. The CONFIG_VERIFIED_DATES map in config.ts emits a stderr warning at startup when a list is >120 days old, but that's a calendar alarm, not a "new chain appeared" alarm. Practical cadence: check monthly, or when a protocol team announces a new deployment.

Known drift to eventually reconcile: the comment in MORPHO_CHAIN_IDS mentions Morpho markets on hyperliquid(999) — which is the same chain as our newly-added hyperevm. If Morpho ships PT markets on HyperEVM and we want them scanned, add hyperevm: 999 to the Morpho map.

veSPECTRA Boost

The server reads live veSPECTRA total supply directly from the Base chain via raw eth_call (no ethers/viem dependency) and computes per-pool boost multipliers using the real Spectra formula:

B = min(2.5, 1.5 * (v/V) * (D/d) + 1)

v = your veSPECTRA balance
V = total veSPECTRA supply (read live from Base)
D = pool TVL
d = your deposit size

Full 2.5x boost when your share of total veSPECTRA >= your share of pool TVL.

Tools that accept ve_spectra_balance (spectra_scan_opportunities, spectra_scan_yt_arbitrage, spectra_compare_yield, spectra_get_ve_info) compute per-pool boost automatically. The veSPECTRA contract is an NFT-based voting escrow (veNFT) at 0x6a89228055c7c28430692e342f149f37462b478b on Base, sourced from spectra-core.

MetaVault Discovery & Strategy Modeling

MetaVaults are ERC-7540 curated vaults that automate LP rollover and compound YT yield back into LP positions. Two tools work together:

spectra_list_metavaults — Discovery tool. Fetches live MetaVault data from the API (/v1/{network}/metavaults), scanning a single chain or all chains in parallel. Returns curator info, TVL, live APY, share price, active positions with PT/pool details, and epoch rate history.

spectra_model_metavault — Strategy modeler with two modes:

• Live mode: Provide chain + metavault_address to auto-fetch the vault's live APY as base_apy. All other parameters (borrow rate, LTV, curator fee) can still be overridden.
• Manual mode: Provide base_apy directly for hypothetical or pre-launch modeling.

The "double loop" economics:

Layer 1 (inside vault):  Deposit → PT/LP allocation → YT yield → more LP (compounding)
Layer 2 (on top):        MV shares → Morpho collateral → borrow → deposit back (leverage)

The key insight: YT compounding raises the vault's base APY, and leverage multiplies that higher base. This creates a "double-loop premium" over raw PT looping that scales with leverage.

Curator economics are built in — the tool models fee revenue on external deposits, additional TVL created by looping, and effective ROI on the curator's own capital.

Setup

Install from npm (recommended)

npm install -g metavault-mcp

Or run directly without installing:

npx metavault-mcp

Install from source

git clone https://github.com/Finanzgoblin/metavault-mcp.git
cd metavault-mcp
npm install
npm run build

Connect to Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "metavault-mcp": {
      "command": "npx",
      "args": ["metavault-mcp"]
    }
  }
}

Restart Claude Desktop. You'll see all 55 tools (Spectra, Pendle, Morpho, cross-protocol) available.

Connect to Claude Code

claude mcp add metavault-mcp -- npx metavault-mcp

Deep Analysis Prompts

The more context you give upfront, the deeper the agent can go. Each input unlocks a different tool chain:

The ideal prompt combines all of these. Here are examples that trigger 8-10 tool chains:

• Yield hunter: "I have $50K USDC and 10,000 veSPECTRA. Find me the best risk-adjusted fixed yield for 60-180 days. Check IBT health, quote my exact entry, and show who else is in the pool."
• Curator: "I'm building a USDC MetaVault on Base with $500K own capital, expecting $2M external. Model the double-loop economics and compare Spectra vs Pendle LP allocation."
• Investigator: "Wallet 0xABC... is active on Spectra mainnet. Show me everything — portfolio, activity across all pools, sequence analysis, and what strategy they're running."
• Term structure: "Show me the ETH yield curve across all chains. Where are the term premium anomalies? Quote pool capacity at $200K for the top 3 mispricings."

The cross-referencing between tools is where the real depth happens — no single tool tells the full story. The agent calls mv_get_protocol_context(topic="workflow_routing") to learn these compositions at runtime.

Example Queries

Once connected, you can ask Claude things like:

• "What's the best fixed yield on USDC right now?"
• "Show me all Spectra pools on Base with >$50k TVL"
• "Calculate a 3x looping strategy for PT-USDC on Base using Morpho"
• "Is the fixed rate on stETH better than the variable rate?"
• "What Morpho markets accept Spectra PTs as collateral?"
• "What's the borrow rate on that Morpho PT-USDC market?"
• "What are the current SPECTRA emissions and lock rate?"
• "Show me the portfolio for 0xABC...DEF across all chains — include any unclaimed Merkl rewards"
• "What's the recent trading activity on this pool?"
• "Scan all pools on mainnet for activity from address 0xABC...DEF"
• "Check if address 0xABC...DEF is a contract or EOA and show their trading patterns"
• "Quote buying 10,000 USDC worth of PT on this pool"
• "What would my portfolio look like if I bought 50k of this PT?"
• "I have $100K to deploy -- scan all chains for the best risk-adjusted yield"
• "Scan for USDC opportunities sized for $500K with max 2% entry impact"
• "Find YT arbitrage opportunities where the market is mispricing yield"
• "I have 100K veSPECTRA -- what boost do I get on this pool with a $10K deposit?"
• "Show veSPECTRA total supply and how much I need for max boost"
• "What MetaVaults are live right now? Show me all of them across all chains"
• "Show me the MetaVaults on Base -- what are the APYs and who are the curators?"
• "Model a strategy for this MetaVault on Base" (auto-fetches live APY)
• "Model a MetaVault with 12% base APY and 3% YT compounding, 10% curator fee -- what does looping look like?"
• "Compare MetaVault looping vs raw PT looping at 12% base APY"
• "I'm curating a vault with $100K own capital and $1M external deposits -- what's my effective ROI?"
• "Compare Spectra vs Pendle yields on Base -- which protocol offers better rates for USDC?"
• "I'm curating a MetaVault with $500K -- scan both Spectra and Pendle for the best opportunities"
• "Show me all active Pendle markets on Arbitrum sorted by TVL"
• "How much capital can I put into this pool before the price impact kills my yield?"
• "Is the IBT behind this PT healthy? Check the conversion rate and APR composition"
• "Show me the USDC yield curve -- what rates are available at each maturity?"
• "Compare the 30-day vs 90-day vs 180-day rates for ETH across all chains"
• "This address traded on Katana weeks ago but spectra_get_pool_activity shows nothing -- pull on-chain logs for the last 7 days"
• "Fetch historical activity for this pool using my RPC URL: https://rpc.katana.network"
• "Monitor my Morpho positions for liquidation risk -- show me the distance to liquidation for each"
• "Stress test my MetaVault on Base -- what happens if 30% of depositors redeem in one epoch?"
• "I have a position expiring in 14 days on my MetaVault -- plan the rollover and show me the best candidates"
• "Aggregate my curator portfolio across all chains -- show me total AUM, blended APY, and concentration"

Architecture

Agent (Claude/GPT/etc)
  | MCP Protocol (stdio)
MetaVault MCP (this)
  | HTTP (15s timeout, 1 retry on 5xx/network errors)
  |
  +-- api.spectra.finance/v1/{chain}/pools
  +-- api.spectra.finance/v1/{chain}/pt/{address}
  +-- api.spectra.finance/v1/{chain}/portfolio/{wallet}
  +-- api.spectra.finance/v1/{chain}/pools/{pool}/volume
  +-- api.spectra.finance/v1/{chain}/pools/{pool}/activity
  +-- api.spectra.finance/v1/{chain}/metavaults
  +-- app.spectra.finance/api/v1/spectra/*
  +-- api.merkl.xyz/v3/userRewards (unclaimed Merkl rewards per wallet)
  +-- api.merkl.xyz/v4/opportunities (Merkl campaign APR per chain)
  +-- api.morpho.org/graphql (PT collateral markets, borrow rates)
  +-- api-v2.pendle.finance/core/* (Pendle market data for cross-protocol comparison)
  +-- mainnet.base.org (veSPECTRA on-chain reads via raw eth_call)
  +-- Chain RPCs: eth_call for Curve get_dy() quotes, eth_getCode for contract detection
  |   (mainnet, base, arbitrum, optimism, avalanche, sonic, bsc, flare)
  +-- Chain RPCs: eth_getLogs for historical pool activity (any chain via dynamic rpc_url)

Modular TypeScript server. Read-only — queries Spectra's existing API, Morpho's GraphQL API, chain RPCs for on-chain Curve get_dy() quotes and contract detection, and Base RPC for veSPECTRA data. No wallet, no transactions, no keys, no web3 libraries needed.

src/
  index.ts          Entry point, tool registration, Layer 1 resources (spectra-overview,
                      curator-strategy-guide), main(), graceful shutdown
  config.ts         Constants, chain config, Zod schemas, protocol parameters, veSPECTRA constants,
                      block time constants per chain, RPC URL resolution (hardcoded + dynamic override)
  types.ts          TypeScript interfaces (SpectraPt, MorphoMarket, ScanOpportunity, MerklTokenReward, MerklChainRewards, MerklCampaign, etc.)
  api.ts            Fetch helpers with retry, GraphQL sanitization, Morpho batch lookup,
                      veSPECTRA RPC with Promise-based dedup cache, 30s TTL pool data cache,
                      Curve get_dy() on-chain quoting, ERC-4626 convertToAssets() health check,
                      eth_getCode contract detection,
                      MetaVault multi-chain scanning, API response validation at system boundary,
                      chunked eth_getLogs with retry for historical event log fetching,
                      Merkl reward fetching and parsing (pool address extraction from reason keys,
                      BigInt wei→human conversion, matched/unmatched reward categorization),
                      Merkl v4 campaign APR fetching (60s TTL cache, inflight dedup, address-based lookup)
  primitives.ts     Format primitives (formatUsd, formatPct, formatDate, daysToMaturity,
                      estimatePriceImpact, chainIdToName) — HOME. Re-exported from formatters.ts
                      for backward compat with 42 consumer files.
  protocols/        externalPositions registry (plugin-style extension for Spectra's whitelisted
                      ERC-4626 modules). types.ts (SourcedValue/InterpretedValue/ProtocolMeta + zod),
                      metadata.ts (avant + pendle + _unknown), cost-models.ts (zero, lp_exit_samechain,
                      lp_exit_crosschain_cctp, liquidation), engine.ts (renderExternalPosition,
                      classifyForStress, generateActionItems, DriftCollector), registry.ts (getMeta +
                      freshness warnings), index.ts (barrel). Spec: docs/protocols-metadata-spec.md.
  formatters.ts     Formatting, BigInt LLTV parsing, closed-form leverage math,
                      price impact, fractional-day maturity, boost computation,
                      slim envelope helpers, token amount formatting (BigInt → human-readable),
                      cross-protocol maturity matching (normalizeUnderlyingSymbol, matchByAssetAndMaturity),
                      Layer 3 output hints (Position Shape, LP APY breakdown,
                      volume signals, Morpho market hints, portfolio signals,
                      competing interpretation branches, statistical confidence boundaries,
                      flow accounting with competing hypotheses),
                      Layer 4 observation coverage (value coverage, temporal gaps,
                      data source coverage, activity diversity, boundary markers),
                      Merkl reward display (per-position matched rewards, unmatched/exited rewards),
                      Merkl campaign APR display (formatMerklCampaignLines with double-counting avoidance)
  tools/            Layer 2: each tool description teaches domain-specific mechanics
    context.ts      mv_get_protocol_context (Layer 1 protocol mechanics, deposit paths, glossary, callable on-demand)
    pt.ts           spectra_get_pt_details, spectra_list_pools, spectra_get_best_fixed_yields, spectra_compare_yield
    looping.ts      spectra_get_looping_strategy
    portfolio.ts    spectra_get_portfolio (balance ratio strategy signals, portfolio-level hints, cross-ref nudges,
                      Merkl rewards integration — parallel fetch, per-position matching, unmatched rewards)
    pool.ts         spectra_get_pool_volume (with volume/liquidity hints), spectra_get_pool_activity (PT address resolution, Router batching,
                      address isolation w/ cycle detection, flow accounting, contract detection,
                      gas estimates, pool impact warnings, observation coverage metrics),
                      spectra_get_address_activity (cross-pool scanner with coverage boundary markers)
    morpho.ts       morpho_list_markets (with capacity/utilization hints), morpho_get_rate (with PT spread analysis)
    protocol.ts     spectra_get_protocol_stats, spectra_list_chains
    quote.ts        spectra_quote_trade (on-chain Curve get_dy() with math fallback)
    simulate.ts     spectra_simulate_trade (also uses on-chain quoting)
    strategy.ts     spectra_scan_opportunities (capital-aware, batch Morpho, negative-APY filtering, strategy tension)
    yt_arb.ts       spectra_scan_yt_arbitrage (YT execution mechanics, flash-mint/flash-redeem)
    ve.ts           spectra_get_ve_info
    metavault.ts    spectra_list_metavaults, spectra_model_metavault (live API + computational modeling),
                      spectra_get_curator_dashboard (vault allocation disambiguation, cross-chain position awareness)
    pendle.ts       pendle_list_markets, mv_compare_yield (maturity-aware cross-protocol yield comparison)
    curator_scan.ts mv_scan_curator_opportunities (cross-protocol capital-aware scanner for MetaVault curators)
    onchain.ts      spectra_get_onchain_activity (historical eth_getLogs, Curve pool + PT vault event decoding, dynamic RPC)
    capacity.ts     spectra_get_pool_capacity (multi-size quote ladder, sweet spot / exhaustion detection)
    ibt_health.ts   mv_check_ibt_health (ERC-4626 conversion rate, APR composition, pool balance, verdict)
    yield_curve.ts  spectra_get_yield_curve (term structure for a given underlying across all chains)
    risk_monitor.ts morpho_monitor_risk (liquidation distance, health factor, borrow rate drift, alert levels)
    stress_test.ts  spectra_stress_test_vault (withdrawal liquidity waterfall, market stress simulation)
    rollover.ts     mv_plan_rollover (expiring position rollover planner with cross-protocol candidates)
    curator_portfolio.ts mv_get_curator_portfolio (multi-vault aggregation, AUM, blended APY, concentration)
    expiry_monitor.ts spectra_list_expiring_pools (pool maturity monitoring, urgency grouping, successor cross-reference, gauge status, readiness assessment)
    gauge_votes.ts  spectra_get_gauge_votes (veSPECTRA governance: vote distribution, voting APRs, bribes, emissions)
    pendle_history.ts pendle_get_market_history (historical APY, TVL, volume, PT/YT prices time-series)
    position_map.ts mv_get_position_map (cross-protocol wallet view: Spectra + Pendle + Morpho + governance, contradiction detection)
test.cjs              Integration test suite (405 tests, McpTestClient over stdio)
test-agent.cjs        Agent reasoning test suite (82 assertions, McpTestClient over stdio)
AGENT-TESTS.md        38-question subjective test suite with grading rubrics (incl. open emergence, coverage, newcomer comprehension tiers)
EMERGENCE-AUDIT.md    Open Emergence audit — competing branches, observation coverage, anomaly detection gaps
CODE-REVIEW.md        Full codebase review (bugs, security, code quality, test coverage)
SECURITY-REVIEW.md    Security-focused review (SSRF, GraphQL injection, dependency vulnerabilities)
docs/
  recursive-meta-process.md    Open Emergence metaframework specification
  dissolution-conditions.md    Dissolution conditions for every structural decision
  architecture-review-agentic-accessibility.md    Agentic accessibility review with feature proposals

Each tool file exports a register(server) function. To add a new tool: create src/tools/newtool.ts, export register(), import and call it in index.ts.

All address parameters are validated (0x + 40 hex chars). All API calls have a 15-second timeout with automatic retry on transient failures (5xx, ETIMEDOUT, ENETUNREACH, ENOTFOUND). Cross-chain scans use Promise.allSettled so one chain failing doesn't block results from others. GraphQL inputs are sanitized to prevent injection. All error returns use MCP's isError: true flag for proper error signaling to agents.

Type Safety

• API return types: fetchSpectra() and fetchMorpho() return Promise<unknown> (not Promise<any>), forcing explicit type assertions at every call site
• Nullish coalescing: All decimal/balance fallbacks use ?? (not ||) to correctly handle 0-decimal tokens
• Morpho state fields: Typed as number | null to match actual API behavior — prevents silent NaN propagation
• JSON parsing: Body read as text first, then JSON.parse() — avoids stream double-consumption that masked error diagnostics
• BigInt precision: veSPECTRA total supply parsed with 10n ** BigInt(18) to avoid float intermediate overflow. Trade quoting uses amountToBigInt() (string arithmetic) to avoid precision loss when amount * 10^decimals exceeds MAX_SAFE_INTEGER
• Input validation: Zod schemas enforce .min() / .max() bounds on all numeric inputs to prevent invalid GraphQL queries

Technical Details

Precision & Correctness

• Morpho LLTV: Parsed with BigInt arithmetic to avoid floating-point precision loss on 18-decimal raw values (e.g., 860000000000000000 → 0.86 exactly)
• Leverage math: Closed-form geometric series (1 - ltv^(n+1)) / (1 - ltv) replaces iterative loop accumulation — numerically exact and O(1)
• YT arbitrage: Uses fractional days-to-maturity for implied rate calculation, avoiding off-by-one annualization errors near expiry
• Price impact: Zero-liquidity pools return 100% impact (not 0%), preventing false positives in opportunity scanners. Impact clamped to 99% max to prevent negative output in trade quotes
• Negative-APY filtering: Opportunities where entry cost exceeds yield are filtered out before ranking, not sorted to the bottom

Resilience

• Retry logic: Covers ECONNRESET, ETIMEDOUT, ENETUNREACH, ENOTFOUND, EPIPE, EHOSTUNREACH, EAI_AGAIN, and UND_ERR_SOCKET errors
• Pool data cache: 30-second TTL per-chain with inflight request deduplication — repeated scans within 30s serve cached data
• API validation: validatePtEntries() filters malformed API responses at system boundary (validates address, maturity, name fields)
• veSPECTRA cache: Promise-based deduplication prevents duplicate RPC calls when multiple tools run concurrently (5-minute TTL)
• Morpho batch limit: first parameter capped at min(addresses * 3, 500) to avoid GraphQL response limits
• On-chain quoting: Curve get_dy() via raw eth_call on 8 chains with automatic fallback to math estimate on RPC failure
• IBT health checks: ERC-4626 convertToAssets() via raw eth_call — graceful degradation when RPC unavailable (other health checks still run)
• Historical event logs: Chunked eth_getLogs (2000 blocks/chunk) with per-chunk retry — failed chunks are skipped so partial results are still returned. Dynamic rpc_url parameter enables any chain without hardcoded RPCs
• Contract detection cache: Permanent Map cache for eth_getCode results (contract code doesn't change)
• Merkl rewards: Best-effort parallel fetch from Merkl API — failure does not block portfolio display. Pool address matching via regex extraction from reason keys. BigInt parseWei() conversion for safe 18-decimal arithmetic
• Merkl campaigns: Best-effort v4 campaign APR fetch per chain (60s TTL cache with inflight dedup). Failure returns empty map — tool output is unchanged. Double-counting avoidance skips campaigns whose reward tokens are already displayed via native API data
• MCP error signaling: All error catch blocks return isError: true so agents can distinguish errors from empty results
• PT address resolution: Pool tools (spectra_get_pool_volume, spectra_get_pool_activity) accept either pool address or PT address and resolve automatically
• Error logging: Catch blocks in Morpho lookups log to stderr instead of silently swallowing failures
• Graceful shutdown: server.close() called before process.exit() on SIGTERM/SIGINT

Testing

From a source checkout:

# Full integration suite (405 tests, requires network)
npm test

# Schema/registration only (98 tests, no network)
npm run test:offline

# Unit tests (242 tests, no network)
npm run test:unit

# Agent reasoning tests (82 assertions, requires network)
npm run test:agent

Unit Tests (api.test.ts, formatters.test.ts, config.test.ts)

242 tests covering pure-function logic: GraphQL sanitization, Morpho field constants, Merkl reward parsing (pool address extraction from reason keys, wei-to-human conversion, matched/unmatched categorization), Merkl reward formatting, balance formatting, cross-protocol maturity matching (normalizeUnderlyingSymbol, matchByAssetAndMaturity), Pendle logit AMM price impact model (estimatePendlePriceImpact), Pendle date/maturity helpers (pendleDaysToMaturity), Pendle market formatters (compact + summary), and configuration validation. No network required.

Integration Tests (test.cjs)

405 tests covering tool registration, schema validation, API responses, on-chain Curve get_dy() quoting, cross-pool address scanning, address isolation mode, cross-protocol curator scanning, and malformed-address negative tests. Dynamically discovers pool and PT addresses from the live API, so tests won't go stale when pools mature.

Agent Reasoning Tests (test-agent.cjs)

82 assertions across multi-tool workflow tests that verify the "reasoning surface" — can an agent using these tools detect anomalies, cross-reference data, and avoid protocol-mechanic traps? Tests include:

• Protocol context completeness — all topics present, Router batching ambiguities explained, cross-reference guidance included
• Anomaly detection — raw APY vs capital-aware rankings produce different results (intentional divergence)
• Cross-tool data consistency — APYs match between spectra_list_pools → spectra_get_pt_details → spectra_compare_yield
• Router mechanics — mint-and-sell loop detection via pool activity → portfolio cross-reference
• Router limitation — API resolves Router txns that eth_getLogs address filtering misses
• MetaVault data integrity — curator info, TVL, APY, vault flows, expired position flagging
• Expired pool discovery — spectra_list_pools returns only active pools; MetaVaults surface expired positions
• veSPECTRA boost math — max boost (1M veSPECTRA + $1K) vs min boost (100 veSPECTRA + $1M)
• Morpho looping fallback — graceful handling when no Morpho market exists for a PT
• Morpho market classification — Spectra vs Pendle/Other labels, unsupported chain handling
• MetaVault scan inclusion — include_metavaults flag correctly shows/hides MetaVault section
• Pendle comparison — head-to-head matched pairs with delta, Pendle-only markets, aggregates
• Surfaced API fields — maturityValue, multipliers (points programs), tags, pool reserves with ratio, IBT APR composition, baseIbt for wrapper tokens
• Merkl rewards in portfolio — SPECTRA gauge emissions appear in portfolio output, graceful handling for empty wallets

Subjective Test Suite (AGENT-TESTS.md)

38 copy-pasteable questions across 11 tiers (basic tool usage → open emergence → newcomer comprehension) with grading rubrics for evaluating LLM agent quality when using the MCP tools. Tier 8 tests "open emergence" — the ability to hold competing interpretations without collapsing to a single narrative. Tier 11 tests newcomer comprehension — can the agent explain deposit paths, recognize conservative impact estimates, and route to the right scanner? These are designed to be run by spawning subagents and scoring responses manually or with LLM-as-judge.

API Reference

This server wraps these endpoints:

Note: {chain} uses the slug mainnet for Ethereum (the alias ethereum is accepted by the server and mapped automatically).

Pendle Protocol Integration

13 Pendle tools provide full feature parity with the Spectra toolset, plus 2 cross-protocol tools for unified analysis:

Pendle-Native Tools (13)

Cross-Protocol Tools (2)

mv_compare_yield — Side-by-side comparison on overlapping chains with maturity-aware matching. Normalizes underlying symbols (wstETH↔stETH, USDC.e↔USDC) and matches by nearest maturity within configurable tolerance (exact ≤7d, close ≤30d, loose ≤90d). Shows match quality and maturity gap per pair.

mv_scan_curator_opportunities — Cross-protocol capital-aware scanner for MetaVault curators. Scans both Spectra and Pendle in parallel, computes price impact at your capital size, effective APY after entry cost, Morpho looping availability (both Spectra and Pendle PTs), and tags cross-protocol matches.

Pendle-Supported Chains

Overlapping with Spectra: Ethereum, Base, Arbitrum, Optimism, Sonic, BSC Pendle-only: Mantle, Berachain, HyperEVM, Corn

Key Differences from Spectra

• AMM model: Pendle uses a time-decay logit AMM (not Curve StableSwap). The capacity and quote tools use a conservative scalarRoot=50 estimate.
• YT trading: Pendle YT trades directly on the AMM (SY↔YT). Spectra YT trades indirectly via Router flash-mint/redeem.
• Incentives: Pendle uses PENDLE token emissions + vePENDLE boosting (separate from Spectra's SPECTRA/veSPECTRA system).
• Token wrapping: Pendle uses SY (Standardized Yield) tokens as the pool asset, not IBT (Interest-Bearing Token) like Spectra.

On-Chain Historical Activity

The Spectra REST API (/v1/{network}/pools/{pool}/activity) only retains a limited time window of recent transactions. When investigating addresses or pools with older activity, spectra_get_onchain_activity reads historical event logs directly from the blockchain via eth_getLogs.

Supports two contract types:

• Curve pool (pool_address): TokenExchange, AddLiquidity, RemoveLiquidity, RemoveLiquidityOne
• Spectra PT vault (pt_address): Mint (deposit IBT → PT+YT), Redeem (burn PT → IBT), YieldClaimed

Both can be provided simultaneously — events are fetched in parallel, merged, and sorted by block number.

Key features:

• Dynamic RPC URL: Agent can pass any rpc_url parameter — works for chains without hardcoded RPCs (Katana, Monad)
• Chunked fetching: 2000 blocks per chunk with per-chunk retry, best-effort (partial results on RPC issues)
• Dual-contract decoding: Curve StableSwap-NG pool events AND Spectra PrincipalToken vault events
• Block range control: Explicit from_block/to_block or lookback_hours (default 24h, max 720h/30 days)
• Address filtering: Filter events by a specific address
• No USD values: On-chain logs don't carry prices — token amounts are shown in human-readable form. Cross-reference with spectra_get_pt_details for price context

Composability with existing tools:

Agent flow: spectra_get_pool_activity → empty? → spectra_get_onchain_activity(pool_address=...) → pool events
Agent flow: portfolio shows PT but no pool trades → spectra_get_onchain_activity(pt_address=...) → vault events (mint/redeem)

Extending

Following the Open Emergence Pattern

When adding new tools, follow the three-layer architecture:

1. Description (Layer 2): Teach any protocol mechanics that affect interpretation of the tool's data. Use "could be" language for ambiguous signals. Add cross-reference nudges to at least one related tool.
2. Output (Layer 3): If the data contains signals that require domain knowledge to notice (e.g., a ratio that implies a strategy, an event that could mean different things), compute a structured hint and include it in the output. Make it salient but not prescriptive. When an observable pattern has multiple valid interpretations, present them as competing branches with equal weight — do not pick one. Flag small sample sizes as statistically insufficient.
3. Coverage (Layer 4): If the tool's output covers only a subset of the address's or pool's full behavior, quantify the blind spots. Report value coverage (observable activity vs position size), temporal gaps, and which data sources were used vs available. End with a boundary marker: "Position sizing should assume this analysis is incomplete, not comprehensive." Coverage metrics bound ALL interpretation branches — high-confidence assessment + low coverage = false confidence.
4. Resource (Layer 1): If the new tool introduces fundamental protocol concepts not covered by existing resources, update spectra-overview in index.ts.
5. Dissolution condition: Document when the new structure would no longer serve, in docs/dissolution-conditions.md. Every Layer 3 hint, architectural pattern, and generative friction point carries a dissolution condition — a prompt for re-evaluation when circumstances change.

The goal: a cold-start agent reading only the tool descriptions and output hints should be able to use the tool correctly and compose it with other tools into novel analytical workflows.

Adding write capabilities (future)

To enable agents to actually execute strategies, you'd add tools that construct unsigned transactions via Spectra's Router contract. The agent would return the transaction calldata for the user to sign -- never holding keys.

Adding gauge/bribe data

Query the spectra-governance subgraph for current epoch votes, bribe amounts, and voter rewards. This is valuable for agents optimizing veSPECTRA voting strategies.

Not yet wired (API endpoints available)

These Spectra API endpoints are ready to be integrated. Create a new file in src/tools/, export register(), and import it in src/index.ts:

• GET /v1/vision/{network}?tokens=... -- APR data for specific tokens
• GET /v1/watch-tower/{network}/transactions -- Conditional order data
• GET /v1/{network}/metavaults/bridge/transactions -- MetaVault cross-chain bridge transaction data (bridged volume, in-flight amounts)

License

MIT