Server data from the Official MCP Registry
Token and pool data, swap quotes, and unsigned transaction plans for Ekubo and other DeFi protocols.
About
Token and pool data, swap quotes, and unsigned transaction plans for Ekubo and other DeFi protocols.
Remote endpoints: streamable-http: https://mcp.ekubo.org/mcp
Security Report
The Ekubo MCP server is a Cloudflare Workers-hosted, public, stateless server that prepares unsigned DeFi transaction calldata across Ekubo, Uniswap, Aave, Morpho, Lido, and other protocols, with no signing keys evident in the reviewed code. The reviewed portions (catalog compaction, schema definitions, input validation via zod) show careful input validation and no shell execution, hardcoded secrets, or exfiltration; the truncated files prevent a full review of network calls and dependencies. Public unauthenticated access is by design for read tools, but write-capable tools only return unsigned calldata, so the main residual risk is the unreviewed remainder of the codebase.
4 files analyzed · 4 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
Permissions Found in Source Code
Found by scanning the linked source code. This listing connects to a hosted endpoint, so none of this runs on your machine: it describes what the server software does where it is hosted.
How to Connect
Remote Plugin
No local installation needed. Your AI client connects to the remote endpoint directly.
Add this to your MCP configuration to connect:
{
"mcpServers": {
"io-github-ekuboprotocol-ekubo": {
"url": "https://mcp.ekubo.org/mcp"
}
}
}Documentation
View on GitHubFrom the project's GitHub README.
Ekubo MCP server
The official agent interface for Ekubo Protocol transactions. This repository deploys a stateless, public MCP server on Cloudflare Workers. It discovers tokens, compares Ekubo and 0x liquidity for same-chain EVM swaps, prepares and tracks Across, LayerZero, and LI.FI any-to-any bridges, and constructs unsigned VeToken calls for ve(3,3) vote and fee workflows. It also publishes provider-neutral STONX allocation recommendations resolved to initialized Robinhood Ve33 pools, enumerates indexed LP positions by owner, reproduces the interface's indexed/API/USD/RPC position-data pipeline, discovers pair-level position candidates, prepares unsigned LP deposits, withdrawals, and earnings claims, and exposes exact pool state and liquidity data. It prepares interface-equivalent TokenDataFetcher reads across each chain's canonical token list for wallet balances and selected contract allowances. It also publishes the same ranked boosted-fee, incentive, and ve(3,3)-emission liquidity opportunities shown by the interface. It additionally exposes fixed, locally maintained Aave V3, Morpho Vault V2, Sky Savings, Lido, Merkl, and Aerodrome deployments with signer-neutral action plans, prepares proof-verified Merkl reward claims for campaigns on any protocol, and prepares Aerodrome v2 liquidity, gauge, veAERO lock, vote, and reward-claim actions on Base alongside the Sugar lens reads that feed them. Agents discover live protocol data from official public APIs or the user's wallet/RPC directly for those protocols. Uniswap V2/V3/V4 support additionally fetches indexed pool discovery, price/volume charts, and liquidity-depth ticks from the official Uniswap interface API, and prepares pool/position reads and liquidity transactions on six EVM chains. See Uniswap coverage.
The MCP server owns agent-facing transaction construction. prod-api remains
a data API and the quoter remains a route-data service.
Public endpoints
POST/GET /mcp— MCP Streamable HTTP endpoint serving bundled protocols (excludes Safe)POST/GET /mcp/{ekubo,aave,aerodrome,lido,merkl,morpho,sky,uniswap}— the same MCP contract narrowed to one protocolPOST/GET /mcp/ekubo-advanced— Ekubo's operator tools, kept off/mcp/ekubo(see below)POST/GET /mcp?protocols=<slug>+<slug>— one connection serving the named protocols (any of the above except Safe); see belowPOST/GET /mcp/safe— dedicated Safe signer preparation; see Safe coverageGET /— service metadata, per-protocol endpoints, and canonical documentation linksGET /tools— deterministic tool catalog for non-MCP discovery, filterable with?protocol=<slug>or?protocols=<slug>+<slug>;catalog_digestchanges whenever that endpoint's tools or instructions do (not its resources)GET /openapi.json— OpenAPI 3.1 discovery contractGET /llms.txt— concise agent workflowGET /skills/{use-morpho,use-sky,use-lido,use-merkl,use-aerodrome}/SKILL.md— reusable direct-data agent instructions, with each skill's discovery reference beneathreferences/discovery.md
One endpoint per protocol
src/protocols.ts partitions the catalog: every tool belongs to exactly one
protocol, /mcp/<slug> registers that protocol's tools and its own skill
resources, and /mcp registers the bundled protocols only. Safe is explicitly
excluded from that bundle. The partition is checked against
hostedToolCatalog in test/protocols.test.ts, so a tool added to the catalog
without a protocol fails the build rather than quietly appearing on no
per-protocol endpoint.
/mcp remains the endpoint for the bundled catalog. Safe clients must add /mcp/safe.
Ekubo itself is split in two. /mcp/ekubo carries the core tools most
sessions use: tokens, quotes and swaps, pools, LP positions and deposits,
withdrawals and claims, liquidity opportunities, transfers, wrap/unwrap,
rewards, and ve(3,3)/STONX. /mcp/ekubo-advanced carries the rarely used
operator tools: auctions, TWAMM orders, pool initialization and price fixes,
oracle capacity, manual boosts, revenue buybacks, approval revocations, and
pool-key enumeration and derivation. Each one's
instructions name the other, so an agent that needs a tool from the other half
tells the user which server to add. /mcp serves both halves.
/tools?protocol=safe publishes the Safe catalog; unfiltered /tools describes /mcp.
Combined endpoints
/mcp?protocols=ekubo+ekubo-advanced serves the union of the named protocols'
tools and resources on one connection. The shared paragraphs (catalog revision,
scope, jurisdiction notice, handoff) are stated once rather than once per
connection, and an endpoint-scope paragraph names the protocols served. Slugs
may be separated by +, , or repeated parameters and appear in any order, but
facetMcpUrl() writes them in PROTOCOL_SLUGS order: a client or MCP gateway
treats every distinct URL as a separate server with its own cached catalog, so
one selection should have one URL. A facet naming every bundled protocol is
/mcp, and one naming a single protocol is /mcp/<slug>. An unknown slug, an
empty list or safe gets HTTP 400 before any MCP handling; Safe stays
standalone.
Filtering happens at the two registration choke points in createEkuboServer
rather than at the call sites, and the instructions are composed from
protocol-scoped paragraphs, so a single-protocol server never tells an agent to
call a tool it does not serve.
/ and /llms.txt link the two public documentation pages:
the server and
protocol coverage and the wallet producer contract.
The latter is where a third party building its own wallet-compatible MCP server
is sent, so keep it in sync when the protocol list or the handoff contract
mirrored in src/wallet-compatibility.ts changes.
MCP-native discovery remains authoritative: clients use tools/list and
resources/list/resources/templates/list. The HTTP discovery endpoints are
additive and help crawlers, OpenAPI clients, and humans find the same
capabilities. GET /tools is deliberately uncached and includes both the
server version and a tool-catalog revision so integrations can detect stale
schemas after a Git-triggered deployment.
MCP 2026-07-28 clients can use server/discover and standalone requests
without an initialization handshake. Browser preflights allow Mcp-Method
and Mcp-Name alongside the protocol-version header. Discovery and catalogs
carry a five-minute public cache hint; bundled documentation and ABI resource
reads carry a one-hour hint. Cache entries belong to the exact endpoint and
resource URI (the protocol-specific endpoints have different catalogs). The
externally fetched API OpenAPI document remains uncached. HTTP RPC envelopes
remain no-store: clients cache MCP result payloads, not another request's ID.
Legacy clients retain their existing result shapes. All tools publish output
schemas; informational schemas describe stable envelopes while preserving
additional upstream fields.
Tools
list_tokens— list the canonical token list, ordered by descendingvisibility_priority, with optional symbolsearch,chain_id,min_visibility_priority,page_size, andafter_tokenfiltersexport_tokens— hand a wallet the canonical list without reading it: returns only atoken_list_referenceenvelope and a count, never entries. Scoped bychain_id, capped bymax_tokens(default 1,000, the wallet's per-import limit), fixed at the interface's visibility threshold, and stored with only the five fields a wallet acts onget_token— fetch token metadata by chain and addressget_tokens— fetch metadata for 1–1,000 exact token identifiers, across chains, through oneprod-apibatch requestget_quotes_with_plans— compare Ekubo and 0x for same-chain exact-input or exact-output swaps, or compare Across, LayerZero, and LI.FI whendestination_chain_iddiffers, and return each option's firm unsigned approval and execution calldata alongside its quote; an Ekubo or 0x failure marks the comparison incomplete and tells the user to retryget_value_transfer_status— track an executed LayerZero or LI.FI cross-chain transfer from origin submission to destination delivery, by theprovider_quote_idits quote carried for LayerZero and by the origin transaction hash for LI.FI; a bridge is the one plan whose successful origin receipt does not mean the user has their fundsprepare_ve33_vote— compile one active NFT's vote changes and deterministic splits into one multicall that always claims its current pool first; prefer the portfolio workflow below for complete state validationprepare_ve33_extend— extend an unvoted token directly, or provide its active pool key to claim pending voter fees atomically before extensionprepare_ve33_stake— create a new VeToken with an exact token approval; max duration is the default when no duration is suppliedprepare_ve33_split— construct a split and predict the child token IDprepare_ve33_claim_fees— claim one or many VeToken voter-fee balancesprepare_ve33_reinvest— automatically discover and claim all active fees, construct one exact-input swap per claimed non-stake token, and increase one VeToken or every existing active allocationprepare_ve33_claim_all_fees— discover every active vote owned by a sender and prepare one native VeToken claim multicall, includingownerOfandvoteStatevalidation calldataprepare_ve33_clear_vote— remove the active vote from one or more VeTokens, claiming each stake's current pool immediately before itsclearVotein one atomic batch.current_pool_keyis required per stake: Ve33 discards pending voter fees when a stake's weight goes to zero, and a key that is not that stake's active pool reverts the batch before anything clears. The stake, its lock end, and its ownership are unchanged; the pool loses that weight, and a pool with no vote weight charges a zero extension feeget_ve33_allocations— handle “show all my Ekubo STONX allocations” with only the connected wallet address because the production Ve33 deployment is the STONX voting system; defaults to Robinhood Chain4663and its canonical VeToken, then returns the complete portfolio andonchain_validationrequest, explicitly markednot_executeduntil itseth_callis run. An explicit chain and VeToken pair remains available for another deployment such as testnet.get_stonx_allocation_recommendation— return the current provider-neutral recommendation plus an exact 10,000-bps executable target list capped at 25 initialized canonical Ve33 pools. Snapshots older than one day trigger a refresh that is awaited for up to 20 seconds; stale, failed, or timed-out refreshes fail closed instead of returning an executable plan. Each recommendation reports anemissions_efficiencyKPI: emissions per dollar of voter fees the pool still generates one epoch (7 days) later, plus the rate-freeemission_share_per_retained_fee_share; pools above the threshold (default 3) or with votes but no retained fees are prune candidates, andprune_low_efficiency=truewithholds them. Passingvoter(vote weight and LP share per pool) with the locally decodedve33_emission_statereturns voter-optimaltargetsthat also value the emissions redirected to the voter's own pools (Mazett 2024), with the neutral plan kept asprovider_targets. The 25-target, 10,000-bps contract is unchangedprepare_ve33_reallocation— resolve targetpool_key_idvalues and compile up to 25 basis-point targets into one fee-preserving atomic VeToken multicall.preserve_existing_locksapportions each expiry cohort across every target;compact_max_lockconsolidates and extends stake before creating exactly one voting NFT per target.get_positions_by_owner— enumerate indexed position NFTs with their pool keys, bounds, liquidity, current pool state, rewards, pagination, canonical token USD metadata, and exact pending position-stateeth_callget_position— hydrate one owner position with NFT metadata, history, campaigns, earned rewards, token USD prices, and an atomic Multicall3 query for current principal, fees or Ve33 rewards, and ownershipget_position_pool_candidates— list existing pools for a pair with verified exact PoolKeys, v2/v3 Core generation, extension classification, token prices, pool statistics, and the correct position managerget_liquidity_opportunities— rank the interface's current boosted-fee, active-incentive, and projected STONX-emission opportunities; returns canonical tokens, exact actionable pools or a pair-level candidate lookup, APR components and denominators, freshness, and risk context. The Ve33 emission input is read and decoded by the user's wallet, then passed back for the final interface-equivalent ranking. Starknet incentives remain visible but are marked discovery-only because the current pool-candidate and deposit preparation tools are EVM-specific.prepare_lp_position_deposit— prepare a new v3 position mint or add liquidity, including exact PoolKey derivation andmaybeInitializePoolfor a new pool atomically before the deployedmintAndDepositcall in one multicall, shared-SDK liquidity math, a nonzero slippage floor, exact approvals/refunds/cleanup, decoded intent, wallet-policy requirements, and a signer-neutral execution plan; no Cast encoding is requiredprepare_pool_initialization— prepare a standalone, idempotentmaybeInitializePooltransaction for an exact v3 PoolKey and initial tick when initialization should not be bundled with the first position mintprepare_lp_position_earnings_claim— resolve an owned position and prepare collection of standard LP fees or Ve33 LP rewards without removing liquidity or touching the NFT, including pending ownership/earnings reads, decoded calldata, wallet-policy requirements, and a wallet execution planprepare_lp_position_withdraw— prepare a partial or full position withdrawal from an exact liquidity amount, or pass up to 100 withdrawals for one atomic wallet-batch-capable plan; each withdrawal automatically collects ordinary fees or Ve33 rewards and includes its own pending validationget_pool— resolve an exact chain/core/pool ID to a verified PoolKey, decoded config, the latest indexed state snapshot, and acurrent_state_queryread bundle whoseread_calls_referencethe wallet executes for fresh on-chain sqrtRatio, tick, and liquidityget_pool_liquidity— return tick-level net liquidity deltas for one exact poollist_pool_keys— enumerate a Core deployment's initialized pools with keyset pagination (after_pool_id, ascending pool_id) and token/pair/extension filters; every pool_id is re-derived locally from its PoolKey before it is reportedderive_pool_id— pack a PoolKey and derive its exact Keccak pool IDdecode_pool_config— decode the extension, exact uint64 Q64 fee, v3 discriminator, and concentrated, stableswap or full-range parameters. Returns{ "decoded_config": { ... } }, matchingderive_pool_id'sdecoded_config;feeis a decimal string andfee_hexis exact uint64 hex.
Aave V3
get_aave_v3_markets— return a local, versioned catalog of fixed Aave V3 Pools and major reserves on Ethereum, Base, Arbitrum, Optimism, Polygon, and Avalancheprepare_aave_v3_supply,prepare_aave_v3_withdraw,prepare_aave_v3_borrow, andprepare_aave_v3_repay— prepare complete signer-neutral Pool calls, including temporary exact ERC-20 approvals and allowance cleanup where neededprepare_aave_v3_collateralandprepare_aave_v3_emode— prepare collateral-toggle and eMode-category calls against a fixed Pool
The agent—not this MCP—queries Aave's public GraphQL endpoint at
https://api.v3.aave.com/graphql for live market/user data. API results select
explicit fixed identifiers for the preparation tools; wallet simulation
remains authoritative.
Morpho Vault V2
get_morpho_vaultsreturns a local, pinned catalog and direct-discovery guidance.prepare_morpho_vault_deposituses the official Morpho SDK's guarded VaultBundlesV1 route with a caller-supplied freshmax_share_price_ray, exact asset approval, and atomic cleanup. Shares are minted to the sender only.prepare_morpho_vault_withdrawandprepare_morpho_vault_redeemconstruct direct fixed-vault exits.
Read ekubo://skills/use-morpho. The agent queries
https://api.morpho.org/graphql itself, then uses fresh wallet/RPC state and
the official SDK to derive the share-price bound. The server never proxies the
API or RPC.
Sky Savings
get_sky_savings_deploymentreturns fixed Ethereum USDS/sUSDS addresses.prepare_sky_savings_deposit,prepare_sky_savings_withdraw, andprepare_sky_savings_redeemconstruct canonical ERC-4626 calls.
Read ekubo://skills/use-sky. Current previews, conversions, limits, balances,
and allowances come directly from the user's wallet/RPC. The direct ERC-4626
methods have no deadline or minimum-output argument, so fresh preview and exact
wallet simulation are required.
Lido
get_lido_deploymentreturns fixed Ethereum stETH, wstETH, and withdrawal queue addresses.prepare_lido_stake,prepare_lido_wrap, andprepare_lido_unwrapbuild liquid-staking and token-conversion plans.prepare_lido_withdrawal_requestcreates bounded asynchronous unstETH NFT requests;prepare_lido_withdrawal_claimclaims one finalized request.
Read ekubo://skills/use-lido. Pause/limit, conversion, balance, ownership,
queue, and finalization state is read directly through the user's wallet/RPC.
Withdrawal requests are irreversible, stop rewards while queued, and may
settle below 1:1 after extraordinary protocol losses.
Merkl
get_merkl_deploymentreturns the reward Distributor address and the chains it was verified on.prepare_merkl_claimbuilds oneclaim()covering every reward token the sender holds on a chain.
Read ekubo://skills/use-merkl. Amounts and Merkle proofs come from
https://api.merkl.xyz/v4/users/{address}/rewards/summary, which the agent
queries directly — it is public and needs no key.
This is the one preparation whose inputs arrive from an outside API and still need not be trusted. Every proof is folded here into the root it implies, a batch spanning two roots is refused, and the returned read bundle asks the wallet for the root the chain is enforcing. A mismatch means the tree rotated or is inside its dispute period, so the plan simply fails simulation instead of being signed. The Distributor is pinned per chain rather than assumed: ZKsync Era has no code at the address the other chains share.
Merkl's amount is cumulative and the contract transfers it minus what was
already claimed, so the claimable figure is amount - claimed; its pending
field is not claimable at all. prepare_merkl_claim covers Merkl campaigns on
any protocol, while prepare_rewards_claim covers Ekubo's own incentive drops.
Aerodrome
get_aerodrome_deploymentreturns the Base contracts and the protocol behaviour that decides what an action can do.prepare_aerodrome_sugar_readsbuilds the eth_call bundle for one Sugar dataset: pools, an account's positions, veNFTs, epochs, or a veNFT's claimable rewards.prepare_aerodrome_liquidity_deposit/_withdraw— v2 add and remove through the Router, with per-side approvals and allowance cleanup.prepare_aerodrome_gauge_deposit/_withdraw/_claim— stake, unstake, and collect AERO emissions.prepare_aerodrome_lock— create, add to, extend, permanently lock, unlock, or withdraw a veAERO position.prepare_aerodrome_vote— cast or reset one veNFT's gauge vote.prepare_aerodrome_incentive_claim— a voter's fees, bribes, and rebase.
Read ekubo://skills/use-aerodrome. Aerodrome is Base-only and publishes no
data API: the Sugar lens contracts are its data pipeline and answer
eth_call, so discovery is a read against the user's own RPC and the no-proxy
boundary costs nothing. Each prepared read ships a decode plan matching the
deployed struct layout.
Every address was derived on chain from the Voter outward rather than copied
from Velodrome's SDKs, which is not pedantry: sdk.js publishes Optimism
addresses, and its Position struct has drifted from the deployed Base lens by
two fields, so decoding a live response with it silently misreads everything
after sqrt_ratio_upper instead of failing.
The fee and bribe contracts a claim needs are per pool and come only from a
Sugar rewards read; a claim naming the wrong one succeeds and transfers
nothing, so a green simulation is not by itself evidence the inputs were right.
Swaps are deliberately absent — get_quotes_with_plans remains the single swap
path — and Slipstream positions are readable but not yet mintable here.
The remaining EVM interface transaction paths also have first-class tools:
prepare_transfers— prepare 1–4,096 ordered native, ERC-20, ERC-721, and ERC-1155 transfers on one chain; kinds may be mixed in one atomic batch;- wrap/unwrap and LP NFT transfer;
- standalone pool initialization and phased pool price correction, including exact reads, quote, approval, and execution route;
- TWAMM/DCA creation, collection, stop, and virtual-order execution;
- auction creation, completion/graduation initialization, and creator proceeds;
- manual boosts, oracle capacity, and ERC-20 revocations;
- incentive rewards, Recovery Fund claims, and revenue buyback maintenance;
- VeToken increase-stake, fee-safe merge, and expired withdrawal.
Each prepare_* result supplies the exact ordered transaction list. The
wallet validates, signs, and submits it; it does not encode calls, select
overloads, build multicalls, append approvals, or determine ordering.
Resources
ekubo://skills/use-morpho,ekubo://skills/use-sky,ekubo://skills/use-lido,ekubo://skills/use-merkl, andekubo://skills/use-aerodrome— reusable no-proxy protocol workflows, with areferences/discovery.mdchild resource for official endpoints and readsekubo://docs/lp-position-workflow— interface-equivalent indexed/API/USD/ RPC joins, atomic TWAMM/Ve33 read semantics, decoding, and APR inputsekubo://contracts/evm— supported chain IDs and contract-resource linksekubo://contracts/evm/{chain_id}— address-to-contract map for one chainekubo://contracts/evm/{chain_id}/{address}— the exact deployment metadata and, when present in the current contracts checkout, ABI for one contract
Contract resources provide provenance and read-only ABI context. Transaction
calldata and complete transaction lists come from first-class preparation
tools, not from a wallet, agent, or ad hoc cast encoding. The client must
still verify deployed code and
permissions and simulate the exact calldata before requesting a signature.
VeToken address resources include function-level warnings for operations that
fully clear a vote, the fee-preserving compound alternatives, and the
stake-orphaning risk of burn. Ownership handovers, ERC721 approvals and
transfers, safe transfers, and burns are explicitly outside every safe MCP
workflow even though the complete ABI resource describes them.
The checked-in snapshot merges the latest ../evm-contracts GitHub release
deployment tables with all non-dry-run Foundry broadcasts and current
artifacts. Contracts deployed without a Foundry broadcast, by replaying the
CREATE2 input of an existing broadcast, are listed with their transaction in
script/evm-contracts-direct-deployments.json. Every contract resource includes the source release, source commit,
nearest tag, snapshot worktree state, and per-ABI hash. A release or broadcast
address remains discoverable when a legacy contract no longer has an artifact
in the current checkout; its address resource explicitly marks the ABI as
unavailable. The Yul router address and public quote ABI come from
@ekubo/yul-router-sdk, so the MCP server follows the SDK version it ships.
Refresh the contract snapshot after contract deployments or ABI changes with
bun run contracts:generate from this repository.
get_quotes_with_plans has no provider-selection input and does not
select a quote. Same-chain requests return every Ekubo and 0x option in
quotes with its source URL and normalized amounts, so the agent or user can
choose. Supply sender and slippage_bps together and each option also
carries the execution_plan_reference that executes it, so a chosen plan goes
straight to a wallet with no second round trip and the compared quote is the
executed one. Unless the user specifies a tolerance, choose slippage_bps so
the maximum value exposed to slippage is approximately one estimated gas fee
(10_000 * gas cost / swap notional, with both values in the same currency),
not a generic 50 bps/0.5%. Prefer re-quoting and preparing new calldata after
a slippage failure to widening that bound; never resubmit reverted calldata
unchanged. Omit both for an indicative comparison, and set include_raw_quotes to
add the untouched provider responses, which are otherwise left out as the
largest and least useful part of a response.
If a configured provider fails, the response reports it in
unavailable_sources without invalidating successful quote options, and an
option that could not be made executable reports its own
execution_unavailable while the rest stand.
Cross-chain requests are quoted by Across, by LayerZero's Value Transfer API,
and by LI.FI, each included where its credentials are configured, and are
compared the same way as same-chain options. LayerZero prices an exact source
amount only, so an exact-output bridge request reports unsupported_quote_type
for it and is served by Across and LI.FI. After executing a LayerZero or LI.FI
option, poll get_value_transfer_status with that option's source until
settled is true — LayerZero by the quote's provider_quote_id, LI.FI by the
origin transaction hash. Token
arguments accept raw EVM addresses or
eip155:<chain_id>:<address> identifiers. The output token's EIP-155 chain
must match destination_chain_id.
Some integrations do not cover every chain Ekubo is deployed on, and
src/chain-support.ts records the known gaps so a tool states them instead of
relaying a provider error. On Elysium (99901) the core protocol, API,
quoter and Yul swap router are live, so Ekubo quotes there carry swap plans.
Across does not support Elysium and reports unsupported_chain without an upstream
call. 0x does cover Elysium, so a same-chain quote there asks both the Ekubo
quoter and 0x. Cloud Wallet does not support it: a result whose plans or read
bundles target Elysium carries a root wallet_support notice, and the
references themselves stay valid for any other wallet that implements the same
handoff. An Ekubo insufficient_liquidity answer is definitive and is reported
with retry_recommended: false. So is a 0x INPUT_INVALID rejection, which is
reported as invalid_request with 0x's field reason; for example, 0x refuses
any taker at or below 0x000000000000000000000000000000000000ffff, such as
0x…dEaD, on every chain.
The catalog explicitly contains read tools and unsigned preparation tools. All server operations are non-custodial and idempotent: the Worker has no wallet, key material, signing function, or broadcast function. Preparation tools return an exact unsigned transaction plan for the agent to pass to the user's wallet. The agent does not ask for a separate confirmation first: wallet tooling is responsible for current-state simulation, presenting the simulated result, collecting authorization or signature, signing, and submission.
Prepared execution plan bodies, read-call bundles — exact
wallet_batch_eth_call argument objects, validated against the wallet
boundary before storage — and token lists exported by export_tokens are
stored in R2 — strongly consistent, so a fresh reference never 404s from replication lag — and served at
/artifact/<id> so wallets fetch them by reference. All three travel as
artifact_reference envelopes (under execution_plan_reference,
read_calls_reference, and token_list_reference) whose integrity.value
keccak256 and bytes count
bind the exact stored bytes; the agent passes the envelope unchanged as the
wallet tool's reference argument — as a value carried in a variable from the
producer result (const ref = r.current_state_reads[0].read_calls_reference),
in the same code block when the harness runs tool calls as code, never retyped
from url/bytes/integrity shown in an earlier turn, which is the observed
way smaller models end up with a parse, digest or 404 failure. A read bundle's
call ids (state_call_id on a position) come back as results[].id from the
wallet, which is the join key from result to row. No other tool
result is stored or replayed, and /mcp responses use
Cache-Control: no-store. No fixed request quota is guaranteed; clients must
honor HTTP 429 and the Retry-After header it carries. Owner positions use upstream no-cache
semantics. Indexed pool-state snapshots may be cached upstream for 180 seconds,
while PoolKeys and tick-liquidity data may be cached for 1,800 seconds. Polling
more frequently than those freshness windows does not produce fresher pool
data.
The token-list reference exists because a list is the largest thing an agent
is ever asked to carry between two servers, and the cost is not in fetching it
but in re-emitting it. The canonical list is 483 KB: about 146,000 tokens of
context to read, and roughly 49,000 output tokens — minutes of generation — to
write back out as a wallet's propose_tokens arguments.
export_tokens is the tool for that trip, and it is a separate tool
rather than a flag on list_tokens because it does a different job.
Listing answers a question the model reasons about — which address is the USDC
the user meant — so it returns entries and offers search, paging, and full
metadata to serve that. Exporting answers no question: it hands a wallet a
list to hold. So it returns a token_list_reference and a count and nothing
else, its stored body carries only the five fields a wallet acts on, and its
whole input surface is which chain and how many at most.
Scope an export by chain, but do not assume that fits it under a consumer's
limit. At the interface visibility threshold Ethereum carries roughly 5,600
tokens, BNB Chain 3,600, Base 2,600, and Arbitrum and Polygon about 1,000
each, against the 1,000 entries a wallet accepts in a single import. An export
past the importer's limit is refused whole rather than truncated, so a larger
max_tokens is not a safer one.
Every export therefore reports complete. False means more tokens exist at
that visibility than max_tokens allowed, and the stored list is a prefix
rather than the chain's list — a distinction nothing downstream could
otherwise draw, because the agent never sees an entry to miss.
Position-state plans use one Multicall3 eth_call at pending. TWAMM virtual
orders or Ve33 reward accumulation, when required, are simulated immediately
before the position read in that same call. Splitting them into separate calls
would discard the simulated state; the aggregate payload is read-only workflow
data and must never be broadcast. Each query carries a complete declarative
Multicall3 and child-result decode plan for local wallet execution. The wallet
returns raw bytes by default, decodes them on the user's device, and never
installs or executes codec code named by the remote plan.
Decode plans distinguish Solidity ABI decoding from protocol semantics.
Standard results use function_result; atomic position queries use
multicall3 with an ABI and required child-result specification, or
function_result_bytes_array for a function returning nested bytes[]. A semantic
codec attached to an ABI output preserves the ABI-decoded value and adds the
interpreted value. A custom payload with no ABI envelope may instead use
semantic_value, which consumes the raw return bytes while the wallet retains
those bytes in the result. Codec IDs are
platform-neutral. Implementations explicitly identify their ecosystem; for
example, Ekubo's compact SqrtRatio codec names the pinned npm package URL,
export, version, and integrity for @ekubo/sdk. Wallets must run only a locally
installed, allowlisted implementation and must never fetch or execute code from
a decode plan.
For a new LP position, start with get_position_pool_candidates; do not
browse prod-api or infer a manager from an ABI resource. Its default
min_tvl_usd=0 keeps initialized pools with negligible liquidity visible.
After the user selects an existing v3 pool, range, token maxima, and slippage,
call prepare_lp_position_deposit. Pass its exact
execution_plan_reference (URL plus digest) to the wallet MCP for policy
checking and exact-plan simulation. The wallet—not this
server—controls target, spender, selector, native-value, signing, and submission
authorization.
Important: See docs/lp-position-bounds.md for
how to calculate correct tick bounds. Ticks encode prices that must account for
token decimal differences. For example, an ETH/USDC pair with ETH at 18 decimals
and USDC at 6 decimals requires adjusting the price ratio by a factor of 10^(6-18)
before converting to ticks, resulting in tick values around -20M, not +76K. Incorrect
tick calculations cause deposits to fail or create positions at unintended prices.
If one side must be acquired first, prepare and execute that swap as a separate wallet plan. Wait for its successful receipt, measure the actual token balance, reserve native gas, and only then size and prepare the LP deposit. Never use an unconfirmed quote output as though it were a settled wallet balance.
Finish every swap before minting, and re-read the pool tick with
current_state_query afterwards — a position's token ratio follows the range
and the current price, not the amounts deposited, so a swap made after the mint
moves the tick and re-skews the position it was meant to balance.
For an existing position, call prepare_lp_position_earnings_claim with
the connected owner, chain, manager, and token ID from the owner-position list.
It automatically selects standard fee collection or Ve33 reward claiming. Run
its pending current-state query with the supplied local decode plan, verify the
decoded owner against expected_owner, and include the current claim with its
unchanged execution plan in the wallet MCP handoff. The prepared call does not
remove liquidity, burn the NFT, or transfer it.
For partial or full withdrawals, execute and decode every position's pending
current-state query and choose an exact positive liquidity amount no greater
than its decoded liquidity. Call prepare_lp_position_withdraw with the
legacy single-position fields or a withdrawals array of up to 100 positions.
It resolves every PoolKey, bounds, manager overload, recipient, and fee/reward
behavior. A multi-position request returns one atomic wallet plan; the wallet
may batch these unrelated position calls into one EIP-7702 transaction. Wallet
tooling must not construct or alter calls. Each position NFT is preserved.
Every chain input accepts a JSON integer, decimal string, or hexadecimal string. Responses use canonical decimal chain-ID strings. Pool fees are uint64 Q64 values and must always be passed and consumed as decimal or hexadecimal strings, never JSON numbers.
Every executable preparation also includes a signer-neutral
execution_plan_reference handoff: an artifact_reference envelope naming
where the plan body is stored and an integrity block (keccak256 plus byte
count) over its exact bytes. The envelope describes none of the plan's
contents; the integrity-verified body is the only source of truth. The agent
relays only the envelope, unchanged; the
wallet fetches the body itself, recomputes the digest, refuses a mismatch, and
validates the plan as if it had been supplied inline. No timestamps travel in
the envelope: plan validity is enforced by the wallet's simulation against
current chain state, and storage expiry surfaces as a fetch 404. The stored
body's ordered_steps place approvals before the main execution and any
exact-output allowance cleanup after it, each as a decimal transaction object.
The plan_id commits to the chain, sender, destination, calldata, and native
value of every approval, execution, and cleanup transaction in the sequence.
Bind the actual wallet address as sender before preparation. Prefer the
connected account and call/simulate/submit abstractions exposed by wallet
tooling; the wallet refuses a fetched plan whose chain or sender disagrees
with its connected chain and account. Pass the whole envelope unchanged as the
wallet MCP's reference argument for it to fetch, verify, and execute in
order. The
wallet executes multi-step plans as one atomic batch; a plan that lists a
capability in required_capabilities the wallet does not implement must be
rejected, not adapted. Use Cast only when the
user selected it or no compatible wallet abstraction is available; the
execution-plan resource retains its exact fallback syntax without making Cast
the default.
execution_plan_ready means the quote, bounds, and unsigned calldata are
complete enough to hand to the wallet. agent_confirmation_required is false:
the wallet presents its simulated result and owns authorization. ERC20 plans
include the required unsigned approval
transaction(s) in addition to the unsigned swap or bridge transaction.
Exact-output Ekubo and 0x plans that create an allowance also include a
post-execution allowance reset.
The client should check current allowance before handing any still-required
approval step to the wallet.
wallet_validation_required remains true for every prepared plan.
The boundary mirrors the Ekubo interface: the public services provide token
data and route quotes, transaction construction applies the user's slippage,
and the user's connected wallet or provider handles balances, allowances,
current-state validation, gas estimation, signing, submission, and receipts.
The Recovery Fund's initial EIP-712 agreement is the one explicit exception to
the Ekubo wallet MCP handoff: that wallet intentionally exposes no arbitrary
typed-data signing tool. Its preparation result marks the incompatibility and
requires a separately selected connected wallet with eth_signTypedData_v4;
the resulting execution plan remains compatible with the Ekubo wallet MCP.
For STONX allocation requests, clients should call
get_ve33_allocations with only the connected EVM wallet address as
owner. The public server is unauthenticated and cannot infer what “my” means.
If the client does not expose a connected address, ask the user for it; do not
substitute a local keystore, repository account, or machine environment value.
VeToken splitting follows the deployed contract invariants: the source token must retain a nonzero stake, its active vote remains with reduced weight, and the child token starts unvoted. Vote compilation claims pending fees unconditionally before a vote is replaced or cleared, including when the claimable amounts are zero. The extension tool exposes only compound claim-and-extend methods because extension clears its vote.
Documentation truncated — see the full README on GitHub.
Reviews
No reviews yet
Be the first to review this server!
More Developer Tools MCP Servers
Rea
Freeby Morluto · Developer Tools
Reverse engineer anything from your terminal or agent with one CLI and MCP server.
Paperclip
Freeby Paperclipai · Developer Tools
Trending hip-hop artist momentum scores across four cultural dimensions.
Scrapling
Freeby D4Vinci · Developer Tools
Web scraping with stealth HTTP, real browsers, and Cloudflare bypass. CSS selectors supported.
Git
Freeby Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
Toleno
Freeby Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
MCP Marketplace
Freeby mcp-marketplace · Developer Tools
Search and install MCP servers from inside your AI client.
