The rootstock-mcp server exposes 37 read-first tools for Rootstock/Orchard DEX data on Base and Base Sepolia, plus opt-in, policy-gated transaction simulation and execution.
Accounts: read token balances, positions, and Orchard eligibility for explicit wallets/tokens.
Analytics: inspect rankings, turnover, TVL availability, and volume/fees without fabricating USD values.
Assets: look up ERC20 metadata and ERC4626 wrapper underlying assets.
Pools: list/inspect/observe Rootstock Vault pools and pool registration events.
History/watch: query indexed Vault events, checkpoints, and poll/cursor over indexed events.
Registry: list networks/contracts, resolve deployments, verify contract code presence, and inspect reviewed ABI selectors/catalogs.
Topology: explore token-pool graphs and provisional rooted Branch/Graft/Whorl classifications.
RPC/quotes/skills: check RPC health, get routing prerequisites, and list/read bundled agent skills.
Policy: evaluate fail-closed read/write policy demonstrations.
Transactions: prepare/simulate transactions; opt-in execution supports send, approve_router, and call_router only through allowlists, caps, simulation-first checks, and kill switch.
Safety: default mode is read-only and cannot sign/broadcast; execution requires ROOTSTOCK_SIGNER_KEY and ROOTSTOCK_EXECUTE_CHAINS.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@rootstock-mcp inspect the Rootstock WETH/BAL pool on Base Sepolia"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
BASED NUT's official agent toolchain — read + guarded execution — for the ROOTSTOCK DEX and the Orchard ecosystem on Base (chain 8453) and Base Sepolia (84532).
One tested domain core, five surfaces:
CLI: rootstock (JSON in, JSON out)
MCP stdio server: rootstock-mcp (37 tools: read by default, execute opt-in)
Python SDK: rootstock_tools.Toolchain
Node/TypeScript bridge: sdk-ts/
Loopback HTTP API + OpenAPI: rootstock-api (127.0.0.1 only)
Plus 20 installable Agent Skills (rootstock skills install).
Two operating modes, structurally separated:
Default = read-only. No signer env key set = no signing code reachable. The read client cannot broadcast (method allowlist, structural).
Opt-in guarded execution. Set ROOTSTOCK_SIGNER_KEY + ROOTSTOCK_EXECUTE_CHAINS
to enable: EIP-1559 signing (key never in any output), chain allowlist,
router allowlist from the pinned registry, per-tx + daily wei caps,
mandatory simulate-first, kill switch (ROOTSTOCK_EXECUTE_KILL=1).
pip install '.[execute]' for eth-account.
python3 -m pip install . # core runtime is stdlib-only
python3 -m pip install .[tools] # + audit script deps (pyyaml, jsonschema)Related MCP server: Base Intel MCP
rootstock networks
rootstock setup registries # explicit, pinned-source download (BASEDNUT/rootstock-monorepo)
rootstock resolve --chain 8453 --name Vault
rootstock capabilities
rootstock skills listSet custom RPC endpoints via ROOTSTOCK_RPC_BASE and
ROOTSTOCK_RPC_BASE_SEPOLIA (e.g. an archive gateway for deep block ranges —
public endpoints wall archive reads).
# All 22 ROOTSTOCK mainnet pools discovered live via Vault PoolRegistered events
ROOTSTOCK_RPC_BASE=https://base.gateway.tenderly.co rootstock pools list --chain 8453 --from-block 52707735 --to-block 52707830
# Rootstock WETH/BAL Pool on Base Sepolia (block 47265032)
rootstock pools list --chain 84532 --from-block 47265020 --to-block 47265052
# Real pool state: balances, fee, token metadata — no fabricated USD
rootstock call pools.inspect --args '{"chain_id":84532,"pool":"0x1aba4e89fd64e41fe3081fabf6ce33cb613977c7"}'
# Receipt status for the pool-create transaction
rootstock call transactions.status --args '{"chain_id":84532,"hash":"0x8ac424c53e1bd26802d47f7014349c9b19315acd14d8c247ee25d16ea44df4c9"}'
# Multi-token balances (pinned to one block, cross-checked vs raw eth_call oracle)
rootstock call accounts.balances --args '{"chain_id":8453,"wallet":"0x135b208ac2480B0d876944416De16E7a3B9A1F65","tokens":["0xb8de15fb529d98c93c749de63c749d48d25a30df","0xAC130701aa31c284c36609E2489f150F419AD7AD"]}'Full live end-to-end evidence: docs/E2E_EVIDENCE_2026-10-27.md.
from rootstock_tools import Toolchain
kit = Toolchain()
print(kit.run('rpc.get_health', {'chain_id': 8453}))
print(kit.run('registry.resolve_deployment', {'chain_id': 8453, 'name': 'Vault'}))rootstock-mcp # stdio; 2025-11-25 legacy handshake + 2026-07-28 stateless eraRead mode signs nothing. Execute mode broadcasts ONLY through the policy executor: sim-first mandatory, caps structural, kill switch absolute.
eth_call and unsigned envelopes are not authorization to move funds.
Payments/x402 features are excluded by user direction; do not add them back without a new request.
The optional policy file restricts tools inside a trusted process; it is not a sandbox for arbitrary local code.
The HTTP API binds 127.0.0.1 only and must not be exposed publicly.
The pinned registry is provenance data. Resolution is not approval.
Superseded S113-fix deployments (11 addresses) are refused at load and resolve time — hardcoded blocklist + registry superseded map enforcement.
Four contracts superseded by the S113-fix redeployment remain listed
upstream and must never be used.
v0.9.0 — read + guarded-execute toolchain, live-proven on Base Sepolia:
zero-value and funded transfers, ERC20 approve, and a real swap on the
Rootstock WETH/BAL pool — all policy-gated, simulated, receipt-verified.
Over-cap and kill-switch refusals live-proven. See
docs/E2E_EVIDENCE_2026-10-27.md for the full battery.
MIT — see LICENSE.
BASED NUT — https://basednut.com — security contact in the monorepo
.well-known/security.txt.
Read up to 32 explicitly provided token balances at one pinned chain block (no automatic portfolio discovery).
Inputs: tokens (required), wallet (required), chain_id (required).
Check on-chain balances against explicitly configured Orchard root/LP rules; not an access grant.
Inputs: wallet (required), chain_id (required).
Read wallet balance of explicitly named ERC20 or LP token, not full portfolio.
Inputs: token (required), wallet (required), chain_id (required).
Rank pools by observed indexed swap count, not wallet ELO or APY.
Inputs: chain_id (required), limit.
Report turnover only with known, matching volume and TVL denominator.
Inputs: chain_id (required), pool.
Explain TVL availability based on verified price/reserve inputs; never fabricate USD estimates.
Inputs: chain_id (required), pool.
Aggregate available indexed swap input and fee amounts in raw token units; never presume complete coverage.
Inputs: chain_id (required), pool, since_timestamp.
Read explicit ERC20 contract metadata directly from chain.
Inputs: address (required), chain_id (required).
Probe ERC4626 asset() directly; unsupported wrappers remain unknown.
Inputs: address (required), chain_id (required).
List the implemented read-only capabilities and their schemas.
Inputs: no named parameters.
Query locally indexed Vault swap, pool and liquidity events.
Inputs: chain_id (required), kind, pool, limit, +1 more.
Describe event-index checkpoints and local data coverage.
Inputs: chain_id (required).
Report which indexed observations exist and which analytics are missing.
Inputs: chain_id (required).
Fail-closed policy demonstration: reads allowed, writes denied; not signer authorization.
Inputs: action (required), chain_id (required).
Read actual pool token addresses via Rootstock Vault; no guessed reserve/TVL.
Inputs: pool (required), chain_id (required).
Read Vault PoolRegistered events for an explicitly bounded inclusive block window, with block provenance.
Inputs: chain_id (required), to_block (required), from_block (required), limit.
Read pool onchain data plus local indexed registration evidence.
Inputs: pool (required), chain_id (required).
Return explicit routing prerequisites; quote unavailable without audited Rootstock SOR.
Inputs: chain_id (required), token_in (required), token_out (required), amount_raw (required), +2 more.
Return reviewed partial read-only ABI signatures and verified Vault event topics; not a full exact build ABI.
Inputs: no named parameters.
Return an exact selector for a reviewed read ABI function, not a deploy/transaction authorization.
Inputs: interface (required), signature (required).
List Rootstock registry deployments, preserving task identity and deprecated records.
Inputs: chain_id (required).
List Rootstock network identities and available local source provenance.
Inputs: no named parameters.
Resolve a Rootstock deployment against a pinned canonical local registry; ambiguous names require task.
Inputs: name (required), chain_id (required), task.
Check pinned Rootstock contract code exists on the selected chain; not a bytecode audit.
Inputs: name (required), chain_id (required), task.
Read the configured Base RPC chain ID, latest block and hash.
Inputs: chain_id (required).
List bundled Rootstock and Orchard agent skills; no third-party skill installation.
Inputs: no named parameters.
Read one bundled SKILL.md by its exact, validated skill name.
Inputs: name (required).
Construct token-pool graph from indexed pools and RPC token lists, labeling missing tokens.
Inputs: chain_id (required), limit.
Provisional rooted Branch/Graft/Whorl classification from observed pools and configured root; not canonical Orchard ranks.
Inputs: chain_id (required), limit.
ERC20 approve whose spender must be an allowlisted Rootstock router. Arbitrary spenders refused. Sim-first, policy-gated.
Inputs: token (required), router (required), chain_id (required), amount_wei (required).
Broadcast a raw contract call to an allowlisted Rootstock router only. Arbitrary targets refused. Sim-first, policy-gated.
Inputs: data (required), router (required), chain_id (required), value_wei.
Return an unsigned policy-unapproved transaction envelope, only for pinned Rootstock targets.
Inputs: chain_id (required), transaction_json (required).
Sign and broadcast an ETH value transfer through the policy-gated executor (env signer key, chain+value caps, simulation-first). Caps are structural; no bypass.
Inputs: to (required), chain_id (required), value_wei (required).
Explicit eth_call on a pinned Rootstock target; no signing or policy approval.
Inputs: chain_id (required), transaction_json (required).
Read transaction receipt and unverified finality from RPC.
Inputs: hash (required), chain_id (required).
Query indexed Vault events after a specific block and log index, preserving intra-block updates.
Inputs: chain_id (required), since_block (required), since_log_index (required), limit.
Check locally indexed events newer than a given block; caller schedules repeated polls.
Inputs: chain_id (required), since_block (required), limit.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 37 tools
Most tools are namespaced and clearly distinct, but several read/status/event tools overlap: accounts.balances vs accounts.positions, history.events vs watch.poll/watch.cursor, history.status vs observations.status, and pools.inspect/list/observe. The verbose descriptions help clarify boundaries, but an agent could still misselect among these closely related read-only tools.
The entire set follows a consistent namespace.action pattern (e.g. accounts.balances, pools.list, registry.resolve_deployment, transactions.simulate). Multiword actions consistently use snake_case after the namespace dot, with no mixed camelCase or vague verb styles.
37 tools is heavy for the apparent scope, especially since many are niche read-only observability/status/watch tools that could be consolidated. While the server spans multiple domains, the count exceeds the typical well-scoped 3-15 range by a wide margin.
The surface covers a broad lifecycle across accounts, analytics, pools, registry, transactions, policy, and indexing. However, quotes.swap is a deliberate dead end without an audited SOR, and some transaction paths are restricted to allowlisted routers rather than general ERC20 operations, leaving minor gaps.
Read-only on-chain intelligence for AI agents on Base: balances, tokens, gas, tx status.
Read-only on-chain intelligence for AI agents on Base: balances, tokens, gas, tx status.
On-chain receipts, balances, tx status and address activity, pay-per-call via x402 USDC on Base.
29 deterministic read-only audits + free discovery tools; paid per call in USDC on Base via x402.