convez.ai
MCP ServerFinanceiroAvançado
monolythium

Lyth MCP – Servidor para Blockchain Monolythium

monolythium/lyth_mcp

IA segura no blockchain: leitura, carteiras encriptadas e runbooks de transações

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que conecta assistentes de IA à testnet Monolythium para leitura de estado da chain, gerenciamento seguro de carteiras locais criptografadas e preparação de transações. Implementa modelo de segurança cauteloso: sem chaves privadas em texto plano, assinatura por passphrase ou modo low-value aprovado, e nenhuma execução automática de gastos.

Instalação

$npx convez-ai monolythium/lyth_mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 3 meses
Versão
—
Issues abertas
2
Contribuidores
1

Casos de uso

  • Assistentes de IA interagindo com blockchain Monolythium de forma segura
  • Gerenciamento de carteiras de agentes criptografadas localmente
  • Preparação e validação de transações com limite de gasto e políticas aprovadas
  • Leitura de estado da chain e descoberta de mercados/vendors

Veredito

Ferramenta especializada para integração de IA com blockchain, com modelo de segurança bem pensado (sem execução automática, criptografia local, passphrases). Nichos muito específico (testnet Monolythium) e ainda MVP; adequado para times que desenvolvem agentes financeiros descentralizados.

README

A tradução para o português deste README ainda está na fila.

Lyth MCP

Monolythium MCP server for live-chain reads and AI runbooks.

lyth-mcp lets an AI assistant safely interact with the current live Monolythium testnet surface. It can read chain state, inspect accounts, look up transactions, list markets, discover local vendors, draft agent-commerce runbooks, validate spending policies, create a local encrypted agent wallet, and build native LYTH transfer transactions.

It does not silently spend funds. By default it drafts wallet approval payloads and stores no plaintext secrets. If the user creates an MCP wallet, the mnemonic is encrypted locally. Signing requires a passphrase unless the wallet is a local-machine protected agent wallet with capped low-value mode enabled.

The first useful product shape is:

Mono provides the rails, wallet handoff, discovery, runbooks, settlement, and verification. Users and vendors build the services agents can call.

Status

This is an MVP MCP server for the live Monolythium testnet.

Default network:

FieldValue
Networktestnet-69420
Chain ID69420
RPC sourceMonolythium chain-registry official testnet endpoints
Transaction signingSupported for local MCP wallets by passphrase or opt-in low-value mode
Transaction broadcastDisabled by default
Wallet storageOptional encrypted local store at ~/.lyth_mcp/wallets.json
Low-value no-passphrase modeOptional per-wallet cap and daily cap for test/agent wallets; default for passphrase-less funding wallets
Native payment preparationpay_vendor with native LYTH
Token payment preparationDraft-only until MRC/token routes are wired
Escrow/trade/policy writesDraft-only until the live write builders are wired

Why This Exists

An AI assistant should eventually be able to say:

"Send me 50 USDC to complete this task. Here is my agent wallet address."

That does not mean the assistant gets unlimited spending power. It means the user can give the assistant a wallet, a budget, and a policy. The assistant can request funds, receive approval, spend within limits, open escrow, pay a vendor, or verify a receipt.

This MCP is the first tool layer for that workflow.

Safety Model

The server is intentionally wallet-cautious:

  • no plaintext private keys or mnemonics;
  • local wallets are encrypted with AES-256-GCM and a scrypt-derived passphrase key;
  • passphrase signing is the default for passphrase-protected wallets;
  • local-machine protected wallets are allowed for capped agent/testnet funding flows;
  • low-value mode is opt-in and should only be used for capped agent wallets;
  • no hidden approvals;
  • no default broadcasting;
  • every economic runbook requires human approval or a previously configured low-value policy;
  • wallet payloads are prepared for review, not executed automatically;
  • signed transaction submission requires LYTH_MCP_ENABLE_SUBMIT=1.

The intended production architecture is:

AI assistant
  -> lyth-mcp
    -> draft/validate runbook
      -> prepare wallet request or build transfer
        -> user approves policy / cap
          -> wallet signs by passphrase or capped low-value mode
            -> signed encrypted envelope is optionally submitted

The MCP is allowed to help. The user controls funding, policy, passphrases, and broadcast permission.

Install

Global install from GitHub:

npm install -g https://github.com/monolythium/lyth_mcp/archive/refs/heads/main.tar.gz

If you specifically want npm's git resolver, use --install-links=true with npm 10:

npm install -g --install-links=true git+https://github.com/monolythium/lyth_mcp.git

From this repository:

cd repos/monolythium/lyth_mcp
npm install
npm run build

@monolythium/core-sdk is installed from the public GitHub repo monolythium/mono-core-sdk through a pinned HTTPS tarball, so this MCP can be installed outside the local monorepo without a nested git build.

Run the server over stdio:

npm start

For development:

npm run dev

Claude Desktop Example

After building, add an MCP server entry like this:

{
  "mcpServers": {
    "lyth-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/monolythium/lyth_mcp/dist/index.js"],
      "env": {
        "LYTH_NETWORK": "testnet-69420",
        "LYTH_CHAIN_ID": "69420",
        "LYTH_MCP_ENABLE_SUBMIT": "0",
        "LYTH_MCP_WALLET_STORE": "/absolute/path/to/.lyth_mcp/wallets.json",
        "LYTH_MCP_HOT_KEY": "/absolute/path/to/.lyth_mcp/hot.key",
        "LYTH_MCP_LOCAL_KEY": "/absolute/path/to/.lyth_mcp/local.key",
        "LYTH_MCP_ADDRESSBOOK": "/absolute/path/to/.lyth_mcp/addressbook.json",
        "LYTH_MCP_VENDOR_REGISTRY": "/absolute/path/to/monolythium/lyth_mcp/vendors.example.json"
      }
    }
  }
}

There is also a template at:

examples/claude_desktop_config.json

Configuration

Environment variableDefaultPurpose
LYTH_NETWORKtestnet-69420Human-readable network label
LYTH_CHAIN_ID69420Expected chain ID
LYTH_RPC_URLunsetSingle RPC override
LYTH_RPC_URLSofficial testnet RPCsComma-separated RPC endpoint override
LYTH_MCP_TIMEOUT_MS10000Per-request timeout
LYTH_MCP_MAX_OUTPUT16000MCP response truncation limit
LYTH_MCP_VENDOR_REGISTRYbundled vendors.example.jsonOptional path override for local vendor registry JSON
LYTH_MCP_ASSET_REGISTRYbundled asset_registry.example.jsonOptional path override for local asset/risk metadata
LYTH_MCP_BRIDGE_ROUTE_REGISTRYbundled bridge_routes.example.jsonOptional path override for local bridge/liquidity route metadata
LYTH_MCP_CLUSTER_REGISTRYbundled clusters.example.jsonOptional path override for local cluster/operator/service-tier metadata
LYTH_MCP_NODE_REGISTRYbundled nodes.example.jsonOptional path override for local node/TPM/PCR metadata
LYTH_MCP_ENABLE_SUBMIT0Set to 1 to allow broadcasting already-signed payloads
LYTH_MCP_WALLET_STORE~/.lyth_mcp/wallets.jsonLocal encrypted wallet store path
LYTH_MCP_HOT_KEY~/.lyth_mcp/hot.keyLocal key file used only for opt-in low-value mode
LYTH_MCP_LOCAL_KEY~/.lyth_mcp/local.keyLocal machine key used for passphrase-less agent wallets
LYTH_MCP_ADDRESSBOOK~/.lyth_mcp/addressbook.jsonLocal contact/addressbook store path
LYTH_MCP_OUTBOX~/.lyth_mcp/outbox.jsonLocal signed-payload outbox for retrying without rebuilding/re-signing
LYTH_MCP_RECEIPTS~/.lyth_mcp/receipts.jsonLocal receipt store for drafted/signed/submitted/failed operations
LYTH_MCP_CONNECTOR_STORE~/.lyth_mcp/connectors.jsonLocal webhook connector store
LYTH_MCP_CONNECTOR_KEY~/.lyth_mcp/connector.keyLocal key used to encrypt connector API keys/webhook secrets
LYTH_MCP_ORDER_STORE~/.lyth_mcp/orders.jsonLocal demo order lifecycle store
LYTH_MCP_BOOKING_STORE~/.lyth_mcp/bookings.jsonLocal service-booking lifecycle store
LYTH_MCP_INVOICE_STORE~/.lyth_mcp/invoices.jsonLocal invoice and funding-request store
LYTH_MCP_MERCHANT_POLICY_STORE~/.lyth_mcp/merchant_policies.jsonLocal per-vendor allow/deny/cap/risk policy store
LYTH_MCP_RUNBOOK_REGISTRYbundled runbooks/Local canonical runbook registry path
LYTH_MCP_WALLET_PASSPHRASEunsetOptional env passphrase for unattended passphrase signing; safer to pass per call
LYTH_MCP_DEFAULT_LOW_VALUE_MAX10Default LYTH per-transaction cap for passphrase-less wallets
LYTH_MCP_DEFAULT_LOW_VALUE_DAILY_LIMIT50Default LYTH daily cap for passphrase-less wallets
LYTH_MCP_OUTBOX_EXPIRY_HOURS24Local signed-payload reservation expiry window

Use LYTH_RPC_URLS when you want the MCP to probe your own RPC fleet:

LYTH_RPC_URLS="http://node1:8545,http://node2:8545" npm start

Tools

Live Chain Tools

ToolPurpose
chain_statusProbe RPC endpoints and return chain, round, mempool, indexer, and sync status
rpc_healthScore configured RPC endpoints for read/write readiness
mcp_self_checkCheck install/config/store/RPC health
security_statusShow MCP-local threat posture across RPC, bridge, wallet, outbox, and TODO(mainnet) security gates
emergency_state_watchWatch emergency signals such as no write-ready RPC, paused bridge routes, stale signed payloads, and failure spikes
bridge_blast_radiusSummarize affected bridge routes, local bridge/swap receipts, signed bridge payloads, and freeze recommendations
recovery_statusShow recovery posture and available recovery runbooks for local agent wallets
recovery_runbook_draftDraft pause, drain, delete, stale-outbox release, or future emergency-key recovery steps
audit_gate_dashboardTrack local audit/research gates for zkML, RISC-V VM, MRC, FRI/STARK, Ferveo, oracle, and DAG sync
readiness_checkShow mainnet-readiness gates for no-EVM, MRC, commerce, bridge, wallet, runbooks, security, docs, and tests
account_overviewGet balance, nonce, label, profile, and flow for an address
recent_transactionsRead recent transactions from lyth_txFeed
tx_lookupLook up status, receipt, transaction, and decoded view by tx hash
tx_error_explainExplain failed sends, RPC errors, policy failures, bridge refusals, and reverts
ask_chainRoute natural-language chain questions to typed MCP paths with cited sources
tx_status_summarySummarize status by tx hash or outbox id
tx_watchPoll a tx hash or outbox id until confirmed, failed, or attempts are exhausted
search_chainSearch addresses, hashes, blocks, clusters, and labels
marketsList live CLOB markets or inspect one market with optional book/trades
api_getLow-level read-only helper for /api/v1
mcp_dashboardRender a compact Markdown dashboard for Claude Code/text clients

AI Runbook Tools

ToolPurpose
list_runbooksShow supported runbooks and live-readiness status
runbook_listList canonical runbook files with stable content hashes
runbook_getLoad one canonical runbook by name or id
runbook_verifyVerify a runbook content hash
runbook_diff_versionsDiff two runbook versions
draft_runbookCreate a typed runbook intent
validate_runbookCheck a runbook against spending policy and safety rules
prepare_wallet_requestPrepare a wallet approval payload where supported
vendor_searchSearch a local vendor registry JSON
commerce_safety_checkCheck vendor/service/search text against local commerce safety policy
risk_explainRender a plain-English risk summary from MCP policy/preflight inputs
asset_registry_infoShow local asset registry metadata and content hash
asset_searchSearch asset metadata and risk labels
asset_getGet one asset, risk labels, warnings, and bridge routes
asset_risk_labelRender wallet-readable labels for an asset/use case
asset_route_labelsJoin local asset labels with bridge route labels
privacy_policy_checkRefuse blocked private-denomination use cases
private_denomination_warningExplain public/private LYTH separation and compliance warnings
contract_path_guidanceExplain no-EVM/Solidity guidance and Rust/RISC-V path
bridge_routesList bridge/liquidity routes with status, cooldown, and trust metadata
bridge_route_getGet one bridge route's risk/cooldown/circuit-breaker metadata
bridge_quotePreflight a bridge amount against route status, fees, caps, cooldown, and risk
bridge_cooldown_matrixShow configured cooldowns by route
bridge_status_summarySummarize route health, drain caps, and attention flags
bridge_circuit_breaker_watchAlert on paused/non-active routes, trusted-route risk, missing audits, and low drain caps
liquidity_onboardingExplain how to bring an asset into Mono through configured routes
cluster_registry_infoShow local cluster/operator registry metadata and hashes
cluster_searchSearch clusters by region, service, status, foundation control, GPU, and open seats
cluster_getGet one cluster with reputation, foundation, sunset, service, and operator detail
cluster_reputationExplain cluster reputation, uptime, slashing, services, and decentralization risk
cluster_foundation_flagExplain foundation-control implications for delegation
cluster_sunset_statusExplain whether a cluster is active, sunsetting, or retired
operator_searchSearch local operators by region, cluster, foundation control, and open-seat interest
operator_getGet one operator's clusters, reputation, open seats, and attestation status
operator_open_seatsList clusters/operators with open operator seats
monarch_operator_assistantExplain cluster health, quorum, resource pressure, open seats, and service ROI
delegation_cap_explainExplain phase caps, diversification, over-cap grace, and tapered rewards
stake_statusSummarize local staking positions against caps and cluster risk
delegate_draftDraft a local delegation plan for one cluster
rebalance_draftDraft a local rebalance plan across clusters
undelegate_draftDraft a local undelegation plan for one cluster
autovote_simulateSimulate cluster ranking for staking autovote modes
node_registry_infoShow local node registry metadata and hashes
node_searchSearch nodes by cluster, operator, role, status, hosting, attestation, GPU, and TPM
node_attestation_getGet local TPM/attestation metadata and PCR comparison for one node
node_pcr_explainExplain one node's PCR values and measured-boot meaning
node_diversity_scoreScore node diversity by ASN, provider, country, hosting class, operator, and cluster
node_hosting_classExplain one node's hosting class and correlated-failure risk
rpc_service_searchSearch local RPC service tiers
archive_service_searchSearch local archive service tiers
prover_service_searchSearch local GPU prover service tiers
gpu_proof_market_assistantRoute bridge/zkML/generic proof requests to local GPU prover service tiers
oracle_service_searchSearch local oracle service tiers
charter_readRead a cluster's live active + pending economics charter (Law §6.8): member shares, delegator share, effective epoch
update_charter_draftBuild + validate an offline updateCharter draft (Σ member = 10000 bps, delegator ≥ 2000 bps floor) and return the consent digest to sign
service_score_per_clusterRead the live per-cluster ServiceScore (Component A, Law §7) plus the base/diversity/service term reads — the "rewards = proved service" view
vendor_registry_infoShow registry hashes, issuer, expiry, signature status, and categories
vendor_getGet one vendor by id
provider_onboarding_draftDraft vendor registry, merchant policy, availability, and connector metadata
demo_connector_templatesList TODO/demo connector templates for Stripe, Coinsbee, travel, food, service providers, ACP, and UCP
demo_connector_getInspect one TODO/demo connector template
demo_connector_draftCreate a disabled connector_set draft from a TODO/demo connector template
connector_setCreate or update an encrypted local webhook connector
connector_getGet one connector without revealing its secret
connector_listList local connectors without revealing secrets
connector_removeRemove one connector and its encrypted secret
connector_test_webhookPreview or send a test webhook payload
merchant_policy_setCreate or update local merchant risk controls
merchant_policy_getGet one vendor's local merchant policy and risk view
merchant_policy_listList local merchant policies
merchant_policy_removeRemove one local merchant policy
merchant_risk_checkEvaluate a vendor/amount/asset before creating an order
order_quoteQuote a demo vendor catalog item
order_createCreate a local demo order
order_payPrepare a pay_vendor runbook and optional wallet request for an order
order_mark_paidMark a local order paid after supplying a tx hash
order_statusGet one local order
order_listList local orders
order_receiptExport a local order receipt
order_cancelCancel a local order before dry-run fulfillment
order_fulfill_dry_runMark a local demo order fulfilled without contacting a real vendor
order_fulfill_manualMark a local order fulfilled from manual vendor evidence
order_fulfill_webhookSend an order to a configured vendor webhook connector
booking_request_createCreate a local service-booking request and book_service runbook draft
booking_accept_demoMark a booking accepted by a demo provider
booking_send_webhookSend a booking request to a configured vendor webhook connector
booking_prepare_escrowPrepare an open_escrow runbook draft for a booking
booking_mark_paidMark a booking paid with an observed tx hash
booking_complete_dry_runMark a booking completed by dry-run fulfillment
booking_dispute_demoOpen a local demo dispute for a booking
booking_statusGet one local booking
booking_listList local bookings
booking_cancelCancel a local booking before completion
invoice_createCreate a local invoice requesting payment
funding_request_createCreate a local agent funding request
invoice_statusGet a local invoice/funding request
invoice_listList invoices and funding requests
invoice_mark_paidMark an invoice/funding request paid with a tx hash
invoice_cancelCancel an open invoice/funding request
submit_signed_transactionBroadcast an already-signed payload, disabled unless explicitly enabled; can update an outbox id
tx_outbox_listList local signed payloads that can be retried
tx_outbox_getInspect one local signed payload
tx_outbox_retryRetry a signed payload without rebuilding/re-signing
tx_outbox_forgetRemove a local outbox entry without invalidating the signed payload
tx_outbox_releaseRelease a local low-value allowance reservation for one signed/not-submitted payload
tx_outbox_expire_staleList or release locally expired low-value outbox reservations
receipt_listList local MCP operation receipts
receipt_getInspect one local MCP receipt
receipt_exportExport one receipt as JSON

Local Wallet Tools

ToolPurpose
wallet_funding_addressCreate or return a local testnet agent wallet funding address
wallet_setupCreate a local encrypted PQM-1/ML-DSA-65 agent wallet
wallet_importImport an existing PQM-1 mnemonic into the encrypted store
wallet_listList local wallets and low-value policy status
wallet_low_value_accountingShow reserved/submitted/confirmed/failed/expired low-value buckets
wallet_preflight_transferCheck chain id, balance, nonce, RPC health, encryption key, and policy before signing
wallet_approval_summaryRender the human-readable approval text for a planned transfer
wallet_safety_profileExplain key protection, hot-wallet caps, pending signed payloads, recovery path, and missing production signals
hot_wallet_policy_simulateSimulate whether a proposed small spend passes the local agent hot-wallet policy
wallet_threshold_explainExplain hot-wallet, passkey/wallet-handoff, and full-key/hardware approval thresholds
agent_wallet_createCreate an explicit low-value agent operating wallet with purpose and caps
agent_wallet_fund_requestDraft a funding request for an agent wallet
agent_wallet_limitsUpdate an agent wallet's local caps and metadata
agent_wallet_pauseDisable low-value signing and mark the agent wallet paused
agent_wallet_drainPrepare/sign a drain transfer back to a principal or recovery address
agent_wallet_deleteDelete a local agent wallet record after explicit confirmation
wallet_configure_low_valueEnable or disable capped no-passphrase signing
wallet_export_mnemonicReveal a mnemonic after passphrase confirmation
wallet_deleteDelete a local wallet from the store
wallet_build_transferBuild a native LYTH transfer and optionally sign an encrypted envelope
addressbook_addAdd or update a named local contact
addressbook_lookupList or search local contacts
addressbook_removeRemove a named local contact

Supported Runbooks

RunbookStatusMeaning
request_fundsDraft-onlyAsk a principal to fund an agent wallet
pay_vendorLive-preparablePrepare native LYTH payment for wallet approval
book_serviceDraft-onlyBook an external service under policy
open_escrowDraft-onlyDraft escrow terms for future live escrow support
place_tradeDraft-onlyDraft a spot-market order intent
set_spending_policyDraft-onlyDraft an agent spending policy update
revoke_agent_permissionDraft-onlyDraft a permission revocation
verify_receiptLive-readVerify receipt/status of a live transaction
rate_vendorDraft-onlyDraft a reputation update

Runbook JSON examples live in:

runbooks/

The MCP exposes those files through a local canonical registry. runbook_list returns stable sha256: content hashes, and runbook_verify can compare a runbook against an expected hash. This is a release-local integrity layer; the future target is signed SDK/protocol registry metadata.

draft_runbook, validate_runbook, and prepare_wallet_request attach canonical metadata when a bundled runbook exists. Drafts include the runbook id, version, content hash, required fields, optional fields, and missing required fields. Validation fails if a canonical required field is absent.

Asset Registry And Privacy Guardrails

By default, the MCP loads asset_registry.example.json. This is local planning metadata with explicit TODO(mainnet) notes; it is not a replacement for signed/on-chain asset metadata.

The asset registry labels:

  • native public LYTH;
  • private-denominated LYTH;
  • wrapped bridge assets such as mUSDC and mBTC;
  • issuer-native draft assets such as USDC;
  • demo MRC assets.

asset_risk_label and asset_route_labels are wallet-facing helpers. They return labels such as native_asset, wrapped_asset, bridge_dependency, issuer_supported, and privacy_cordon.

privacy_policy_check enforces the private-denomination cordon. Known private assets, such as pLYTH, are refused for commerce, service payments, escrow, bridges, staking, contracts, markets, discovery, and issuer registration. The same local policy is enforced by order creation, order payment preparation, booking creation, and bridge quotes.

Use contract_path_guidance when a user asks to deploy Solidity or EVM bytecode. It returns the explicit no-EVM answer and points to the future Rust/RISC-V MRV contract path.

Commerce Safety And Risk Summaries

commerce_safety_check applies a local client-side safety policy before vendor discovery, provider onboarding, orders, and bookings. It blocks obvious illicit-commerce requests and warns on restricted categories such as travel, gift cards, legal, medical, and regulated finance. This is not a protocol validity rule; it is a wallet/MCP guardrail so assistants do not help source illegal goods or services.

risk_explain renders policy inputs into a Markdown summary with the operation, amount, counterparty, decision, violations, warnings, assumptions, receipt path, and retry path. The same renderer is now attached to bridge quotes, merchant checks, order quotes, order creation, order payment preparation, booking creation, and provider onboarding drafts.

tx_error_explain turns raw failures into assistant-readable recovery guidance. It recognizes mempool encrypted-envelope failures, disabled broadcast, RPC outages, insufficient funds, nonce/duplicate payloads, privacy-denomination violations, commerce-safety refusals, merchant-policy blocks, bridge-route failures, and generic contract reverts. Failed wallet_build_transfer, agent_wallet_drain, submit_signed_transaction, and tx_outbox_retry responses include this explanation automatically.

ask_chain is a lightweight natural-language router. It maps common questions to typed MCP surfaces such as chain_status, account_overview, tx_lookup, tx_error_explain, vendor_search, asset_search, bridge_routes, bridge_quote, markets, or search_chain, and returns the source RPC methods or local registry hashes it used.

provider_onboarding_draft builds draft-only metadata for a future provider listing: local vendor registry record, merchant policy, availability placeholder, and optional webhook connector shape. It does not publish anything on-chain and includes TODO(mainnet) notes for real signed discovery metadata and provider verification.

Security And Readiness Dashboards

Use security_status for a compact threat posture summary. It checks local RPC/write readiness, bridge verifier posture, bridge route posture, oracle service metadata, RISC-V VM gate status, local hot-wallet pressure, and signed outbox pressure.

Use emergency_state_watch when something looks wrong. It surfaces no-write RPC state, paused bridge routes, stale signed payloads, repeated failed broadcasts, and the current TODO(mainnet) gap for G3/PQ emergency declarations.

Use bridge_blast_radius before enabling or reopening any bridge route. It joins local route alerts with bridge/swap receipts and signed bridge-like outbox payloads. The current MCP does not build live bridge transactions yet, so in-flight detection is local-store based until core/indexer settlement state exists.

Use readiness_check to show the MCP's mainnet-readiness gates:

GateCurrent MCP role
no_evmno-EVM guidance and Rust/RISC-V direction
mrcasset labels and privacy policy only
agent_commercelocal vendors, orders, bookings, invoices, policies, connectors
bridgeroute metadata, cooldowns, quotes, circuit-breaker watch
walletexplicit capped agent wallets, preflight, outbox, receipts, safety profile
runbooklocal canonical runbooks and validation
securitylocal dashboard, emergency watcher, recovery drafts
docsREADME plus focused docs under docs/
testssmoke tests plus golden failure fixtures

This dashboard is intentionally conservative. Mainnet readiness still depends on core, SDK, indexer, wallet handoff, audits, and live testnet evidence.

Bridge Route Registry

By default, the MCP loads bridge_routes.example.json. These routes are planning/preflight metadata unless a route is explicitly marked active.

The registry lets an assistant answer:

  • which USDC/ETH/BTC routes exist;
  • whether the route is zk-light-client, trusted, issuer-native, or manual;
  • cooldown by source chain and trust model;
  • route fees, limits, drain caps, circuit-breaker status, finality threshold, and trust assumptions.

Use bridge_quote to check a specific amount before a future bridge transaction builder exists. Draft routes intentionally return executable: false so the assistant can explain the path without pretending a live bridge transfer can be sent.

Use bridge_circuit_breaker_watch to surface route pauses, non-active routes, trusted/transitional risk, missing audit/insurance metadata, and low drain-cap remaining. In this example registry it intentionally returns critical alerts because all routes are draft or paused.

The bundled cooldown posture is:

Route familySuggested cooldown
Ethereum finalized events1 epoch after zk/light-client verification
Solana1-2 epochs depending on finality confidence
Bitcoin2 epochs or value-tiered limits
Trusted/transitional bridgeLonger cooldown, e.g. 7 days, until zk/light-client path replaces it

Cluster And Operator Registry

By default, the MCP loads clusters.example.json. This is local planning metadata for operator UX, cluster discovery, delegation decisions, and service-tier routing. It is not a live validator registry.

The local registry lets an assistant answer:

  • which clusters exist by region, jurisdiction, status, and open operator seats;
  • which clusters are Foundation-controlled;
  • which clusters expose RPC, archive, GPU prover, or oracle services;
  • which clusters are better candidates for max-decentralization delegation;
  • which operators have draft reputation, cluster membership, and attestation status.

Use cluster_search, cluster_reputation, cluster_foundation_flag, and cluster_sunset_status for delegation explanations. Use delegation_cap_explain for phase-level staking policy: per-cluster cap, minimum diversification, over-cap grace period, and tapered reward assumptions.

stake_status, delegate_draft, rebalance_draft, undelegate_draft, and autovote_simulate are local planning shims for future staking UX. They rank clusters and produce unsigned plans, but they do not build or submit staking transactions.

Use monarch_operator_assistant for node-operator planning: cluster health, 7-of-10 quorum, update status, open seats, resource pressure, and service ROI. It is intentionally node-ops only and should not be mixed into consumer wallet/payment flows.

By default, node-level tools load nodes.example.json. Use node_attestation_get, node_pcr_explain, node_diversity_score, and node_hosting_class to explain TPM/PCR posture, measured-boot mismatches, ASN/provider/country diversity, and hosting risk. These tools only inspect local placeholder metadata; they do not verify TPM quote signatures.

Use prover_service_search, rpc_service_search, archive_service_search, and oracle_service_search for service-tier routing. Use gpu_proof_market_assistant when an assistant needs to route a bridge, zkML, or generic proof request to a prover service with fee/latency assumptions. ask_chain routes questions such as "Show EU clusters with GPU prover service" and "Which clusters maximize decentralization for my stake?" into these typed tools and returns the local registry hash it used.

Unlike the cluster/operator/node planning tools above (which read bundled metadata), the service-reward tools read the live chain through @monolythium/core-sdk. Use service_score_per_cluster for the "rewards = proved service" view (Component A, Law §7): the settled per-cluster ServiceScore plus the base/availability term (cluster status), the diversity term (ASN/geo/hosting spread), and the archive/prover/rpc/indexer service terms. Use charter_read to read a cluster's active + pending economics charter (Component H, Law §6.8) — per-operator member shares, the delegator share, and the pending amendment's effective epoch. Use update_charter_draft to build and validate an updateCharter amendment offline (it enforces Σ member shares = 10000 bps and the 2000 bps delegator floor, returns the 30-byte charter payload plus the per-signer ML-DSA-65 consent digest, and never assembles submittable calldata or broadcasts).

Every cluster/operator/node response includes TODO(mainnet) assumptions. Production needs signed cluster metadata, live quorum/uptime/slashing feeds, TPM/PCR attestation, service-capacity feeds, and delegation cap checks from core/indexer.

Wallet Setup

For an explicit agent operating wallet, use agent_wallet_create. This records the wallet purpose and local caps, then returns a funding address:

{
  "name": "pizza-agent",
  "purpose": "Small food-ordering demos on testnet",
  "confirm": "CREATE_AGENT_WALLET",
  "maxBalance": "25",
  "lowValueMaxAmount": "10",
  "lowValueDailyLimit": "50",
  "allowedCategories": ["food"]
}

The agent can then request funding:

{
  "name": "pizza-agent",
  "amount": "20",
  "asset": "LYTH",
  "purpose": "Pizza demo operating budget"
}

For the fastest testnet demo, ask for a funding address. The MCP creates or returns a local-machine protected wallet named agent-main and enables capped no-passphrase signing:

{
  "name": "agent-main",
  "lowValueMaxAmount": "10",
  "lowValueDailyLimit": "50"
}

The response includes fundingAddress. Send only testnet or capped agent funds there.

Create a local agent wallet with passphrase protection:

{
  "name": "agent-main",
  "passphrase": "use-a-real-long-passphrase",
  "revealMnemonic": false
}

For testing small autonomous spends, the user can enable capped no-passphrase signing at setup. If passphrase is omitted, the MCP uses a local machine key and defaults low-value mode on:

{
  "name": "agent-main",
  "lowValueNoPassphrase": true,
  "lowValueMaxAmount": "10",
  "lowValueDailyLimit": "50"
}

Then the assistant can build and sign a small transfer without asking for the passphrase again:

{
  "walletName": "agent-main",
  "to": "mono1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg357f9at",
  "amount": "9",
  "sign": true,
  "allowLowValueSigning": true,
  "broadcast": false
}

Named contacts can be stored in the local addressbook and then used directly as recipients:

{
  "name": "Neo",
  "address": "mono192nzzjdv8flex940av5eh0gh5nwtku9k5kehrm",
  "tags": ["team"]
}
{
  "walletName": "agent-main",
  "to": "Neo",
  "amount": "0.1",
  "sign": true,
  "allowLowValueSigning": true,
  "broadcast": true
}

Amounts above the low-value cap are blocked unless the wallet was passphrase-protected and the passphrase is supplied. Low-value accounting is reserved when the MCP creates a signed payload, not when final settlement is observed, because a signed payload can be submitted later. Broadcast acceptance moves the amount from reserved to submitted; tx_status_summary or tx_watch moves it to confirmed or failed once a receipt is observed. If broadcast fails, retry the returned outbox entry; do not rebuild the transfer unless you intentionally want a new signed payload and a new low-value reservation.

Signed payloads receive a local expiry timestamp, default 24 hours. Expiry only releases the MCP allowance reservation; it cannot invalidate a signed payload that was copied elsewhere. Use tx_outbox_expire_stale to list expired candidates, then call it with release=true and confirm: "EXPIRE_STALE_RESERVATIONS" to move eligible reservations to the expired bucket. Use tx_outbox_release for one entry.

Signed payloads are now also written to the local outbox. Prefer retrying with tx_outbox_retry:

{
  "id": "outbox_..."
}

Use mcp_dashboard when you want a Claude Code-friendly Markdown view of wallets, outbox entries, receipts, connectors, orders, bookings, invoices, and merchant policies.

Before signing a payment, the MCP now runs transfer preflight checks. You can call the same checks directly:

{
  "walletName": "pizza-agent",
  "to": "Neo",
  "amount": "0.1",
  "sign": true,
  "allowLowValueSigning": true
}

Use rpc_health to see which RPC endpoint will be preferred for writes.

For display-only approval text without signing, call:

{
  "walletName": "pizza-agent",
  "to": "Neo",
  "amount": "0.1"
}

Example: Pizza Payment Runbook

User:

Hey assistant, I'm hungry.

Assistant:

I can order your usual pizza for 10 LYTH.
Delivery should arrive within 30 minutes. Approve spend?

The assistant drafts:

{
  "runbook": "pay_vendor",
  "fields": {
    "recipient": "mono1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg357f9at",
    "vendorId": "pizza-demo",
    "amount": "10",
    "asset": "LYTH",
    "category": "food",
    "memo": "usual pizza, no pineapple, add 1 LYTH tip"
  },
  "policy": {
    "maxAmount": "15",
    "assetAllowlist": ["LYTH"],
    "vendorAllowlist": ["pizza-demo"],
    "categoryAllowlist": ["food"],
    "requireHumanApproval": true
  }
}

Then it calls validate_runbook.

If valid, it calls prepare_wallet_request with the user's from address:

{
  "runbook": "pay_vendor",
  "from": "mono142424242424242424242424242424242ga9n5c",
  "fields": {
    "recipient": "mono1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg357f9at",
    "vendorId": "pizza-demo",
    "amount": "10",
    "asset": "LYTH",
    "category": "food"
  },
  "policy": {
    "maxAmount": "15",
    "assetAllowlist": ["LYTH"],
    "vendorAllowlist": ["pizza-demo"],
    "categoryAllowlist": ["food"],
    "requireHumanApproval": true
  }
}

The MCP returns a wallet request:

{
  "method": "eth_sendTransaction",
  "params": [
    {
      "from": "mono142424242424242424242424242424242ga9n5c",
      "to": "mono1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg357f9at",
      "value": "0x8ac7230489e80000",
      "data": "0x",
      "chainId": "0x10f2c"
    }
  ]
}

The wallet must render that request and the user must approve it.

Example: Agent Wallet Funding Request

{
  "runbook": "request_funds",
  "fields": {
    "agentAddress": "mono1hwamhwamhwamhwamhwamhwamhwamhwam6rjwp2",
    "amount": "50",
    "asset": "LYTH",
    "purpose": "Legal review agent budget"
  },
  "policy": {
    "maxAmount": "50",
    "assetAllowlist": ["LYTH"],
    "requireHumanApproval": true
  }
}

This runbook produces a funding request. Use wallet_setup separately when the user wants the MCP to create a local encrypted agent wallet.

Vendor Registry

By default, the MCP loads the bundled vendors.example.json demo registry. Set LYTH_MCP_VENDOR_REGISTRY only when you want to override it with another JSON file:

LYTH_MCP_VENDOR_REGISTRY=./vendors.example.json npm start

Shape:

{
  "schemaVersion": 1,
  "network": "testnet-69420",
  "vendors": [
    {
      "id": "pizza-demo",
      "displayName": "Pizza Demo Vendor",
      "category": "food",
      "address": "mono1zyg3zyg3zyg3zyg3zyg3zyg3zyg3zyg357f9at",
      "acceptedAssets": ["LYTH"],
      "maxOrderAmount": "25",
      "serviceTags": ["pizza", "delivery"],
      "catalog": [
        {
          "id": "margherita",
          "name": "Margherita",
          "price": "9",
          "asset": "LYTH"
        }
      ]
    }
  ]
}

The included vendors.example.json contains demo vendors for:

Vendor IDCategoryPurpose
pizza-demofood10 pizza SKUs for payment/runbook testing
flight-tickets-demotravelFake flight booking requests
plumber-demohome_servicesFake plumber/service-call booking
coinsbee-giftcards-demogift_cardsUnofficial sandbox gift-card metadata; no real Coinsbee API calls
legal-review-demoprofessional_servicesExisting professional-services demo

This local registry is only an MVP discovery layer. A production vendor registry should be on-chain or backed by signed vendor metadata, real vendor verification, and fulfillment webhooks/API credentials.

The MCP now computes registry hashes and can verify optional ed25519 signature metadata when present:

{
  "signature": {
    "algorithm": "ed25519",
    "publicKeyPem": "-----BEGIN PUBLIC KEY-----...",
    "signatureBase64": "..."
  }
}

Signature verification covers the canonical registry payload excluding signature and signatures.

Demo Orders

Local orders are for MCP flow testing. They do not contact real vendors or deliver real goods.

Typical flow:

  1. order_quote
  2. order_create
  3. order_pay
  4. order_mark_paid with an observed tx hash, or continue as payment-prepared in a dry run
  5. order_fulfill_dry_run for a demo, order_fulfill_webhook for a configured vendor connector, or order_fulfill_manual with a vendor confirmation/reference
  6. order_receipt

Quotes and order creation include local merchant-risk, asset/privacy, commerce-safety, and plain-English risk summaries. If a vendor is denylisted, exceeds a configured cap, uses a blocked asset, falls outside an allowed category, or matches blocked commerce policy, order_quote, order_create, and order_pay refuse the flow.

Fulfillment Connectors

Connectors are local webhook/API-key records for vendor integrations. Secrets are encrypted at rest with LYTH_MCP_CONNECTOR_KEY and never returned by list/get tools.

Example:

{
  "id": "pizza-demo-webhook",
  "vendorId": "pizza-demo",
  "endpoint": "https://vendor.example/orders",
  "authMode": "hmac_sha256",
  "secret": "vendor-shared-secret",
  "confirm": "STORE_CONNECTOR"
}

Use connector_test_webhook without send=true to preview the payload hash and endpoint before sending. order_fulfill_webhook and booking_send_webhook require explicit confirmation and record receipts/events. A successful webhook means the external service accepted the request; it is not final proof that goods or services were delivered.

Demo Connector Templates

demo_connector_templates, demo_connector_get, and demo_connector_draft provide clearly marked TODO/demo stubs for product-specific integrations:

  • Stripe checkout;
  • Coinsbee-style gift cards;
  • travel booking;
  • food delivery;
  • service providers;
  • Agent Commerce Protocol;
  • Universal Commerce Protocol.

Generated drafts are disabled by default and include TODO notes. Do not enable a real connector until provider terms, credentials, webhook verification, refund/dispute handling, and merchant policy are reviewed.

Merchant Risk Controls

Merchant policies are local MCP controls for agent-commerce safety. They do not modify the vendor registry or on-chain state.

Example:

{
  "vendorId": "pizza-demo",
  "allowlisted": true,
  "maxOrderAmount": "15",
  "allowedAssets": ["LYTH"],
  "allowedCategories": ["food"],
  "refundPolicy": "Demo refunds are manual.",
  "fulfillmentSla": "30 minutes in demo text only."
}

Use merchant_risk_check before creating an order or booking when an assistant wants to explain policy basis, caps, notes, commerce-safety status, and refusal reasons in plain language.

Service Bookings

Bookings model the service side of agent commerce: a plumber request, travel request, legal review, food delivery request, or similar external service. They are local workflow records until real vendor connectors and escrow modules exist.

Typical flow:

  1. booking_request_create
  2. booking_send_webhook for a configured provider, or booking_accept_demo for local demos
  3. booking_prepare_escrow when the service needs deliverable-based payment
  4. booking_mark_paid with an observed payment or escrow tx hash
  5. booking_complete_dry_run, booking_dispute_demo, or booking_cancel

booking_request_create attaches a canonical book_service runbook draft. booking_prepare_escrow attaches a canonical open_escrow draft. Booking creation enforces the same local merchant, asset/privacy, commerce-safety, and risk-summary checks as orders.

Invoices And Funding Requests

invoice_create and funding_request_create create local payment requests with a monolythium://send URI and a canonical request_funds runbook draft. They do not watch for payment automatically yet; use invoice_mark_paid with an observed tx hash.

Broadcasting Signed Payloads

By default, submit_signed_transaction and wallet_build_transfer refuse to broadcast.

To enable broadcast of signed payloads:

LYTH_MCP_ENABLE_SUBMIT=1 npm start

Supported broadcast modes:

KindRPC method
eth_raweth_sendRawTransaction
lyth_encryptedlyth_submitEncrypted

submit_signed_transaction only submits a payload that was signed elsewhere. wallet_build_transfer can sign from a local encrypted MCP wallet, but it still will not broadcast unless LYTH_MCP_ENABLE_SUBMIT=1.

When wallet_build_transfer signs and broadcast fails, it returns broadcastError plus a retry object. Retry the exact same payloadHex with submit_signed_transaction. Rebuilding a transfer signs a fresh payload and reserves low-value allowance again.

Production Notes

Before treating this as a public product, the next pieces should be added:

  • wallet extension handoff for approval requests;
  • mono1-to-0x address resolution through the SDK;
  • MRC token payment builders;
  • signed/on-chain asset registry and privacy event metadata;
  • on-chain or signed vendor registry with verified fulfillment connectors;
  • escrow module integration;
  • spot-market order transaction builder;
  • spending-policy transaction builder;
  • receipt matching against expected sender, recipient, asset, and amount;
  • runbook signature format so agents and wallets can attest to the exact approved workflow.

Development

Type-check:

npm run typecheck

Build:

npm run build

Smoke test built package output:

npm test

Run:

npm start

External Commerce (NOWPayments, ChangeNow, Travala, Coinsbee, Duffel)

An optional surface lets the agent reach mainstream crypto-commerce vendors through hosted payment processors and travel connectors. There is no EVM hot wallet, x402, or ERC-8004 agent-identity surface — Monolythium is a no-EVM chain (see contract_path_guidance / readiness_check gate=no_evm). Payment connectors are sandbox-first: settlement runs through the vendor's own processor, and lyth_mcp builds, signs, and tracks locally rather than custodying funds.

Quick map (every tool listed below is registered by the server):

NeedTools
NOWPayments (crypto checkout)nowpayments_configure, nowpayments_config_redacted, nowpayments_status, nowpayments_currencies, nowpayments_merchant_coins, nowpayments_estimate, nowpayments_payment_create, nowpayments_invoice_create, nowpayments_payment_status, nowpayments_payment_list, nowpayments_refund_draft, nowpayments_ipn_verify
ChangeNow (swap / fiat)changenow_configure, changenow_config_redacted, changenow_status, changenow_currencies, changenow_min_amount, changenow_estimate, changenow_swap_create, changenow_swap_status, changenow_swap_list, changenow_fiat_estimate, changenow_fiat_sell_draft
Travala (hosted MCP proxy)travala_info, travala_proxy_call, travala_book_recover, travala_flight_capability_probe
Coinsbee (interim NOWPayments path)coinsbee_guide, coinsbee_via_nowpayments_track
Secure traveler profiles (encrypted PII)profile_create, profile_update, profile_list, profile_get, profile_reveal, profile_delete, profile_store_info
Flights via Duffel (real catalog)duffel_configure, duffel_config_redacted, flight_search, flight_offer_get, flight_seat_maps, flight_order_create_hold, flight_order_create_instant, flight_order_pay, flight_order_get, flight_order_list, flight_order_cancel, flight_order_cancel_confirm
Flights via crypto OTA + NOWPaymentsflight_ota_nowpayments_track
Readinessreadiness_check gate=external_commerce

Additional Docs

Focused docs live in:

docs/CLAUDE_CODE_EXAMPLES.md
docs/OPERATOR_GUIDE.md
docs/VENDOR_REGISTRY.md
docs/RUNBOOK_GUIDE.md
docs/EXTERNAL_COMMERCE.md
Ver o original no GitHub

Bom para

Relacionados