Skip to main content
Glama
mcp-server-usdd

mcp-server-usdd

Official

mcp-server-usdd

License: MIT Networks TypeScript MCP USDD

An MCP server for the USDD protocol across TRON, Ethereum, and BNB Smart Chain (plus internal testnets). Covers Vault/CDP, PSM, USDD Savings, token transfers, and protocol analytics.

Scope

Current implementation covers:

  • Vault lifecycle: open, deposit collateral, mint USDD, repay, withdraw, close

  • PSM lifecycle: inspect fees and routes, swap into USDD, swap out of USDD

  • Savings lifecycle: inspect USDD Savings, deposit, withdraw

  • Risk and monitoring for vaults: summaries, oracle status, collateral buffers

  • Token preflight checks: balances, allowances, approvals

  • Token transfers: two-step preview → confirm flow for TRX, TRC20, and EVM native/ERC20

  • Protocol analytics: chain metrics, collateral prices, PSM route metrics, treasury, Smart Allocator, proof of reserve

Related MCP server: USDD Analytics MCP

Supported Networks

Network

Key

Notes

TRON

tron

TRON-native vault and PSM support

Ethereum

eth

Vault, PSM, USDD Savings

BNB Smart Chain

bsc

Mirrors ETH deployment structure

TRON Nile

tron_nile

Internal testnet deployment

Ethereum Sepolia

eth_sepolia

Internal testnet deployment

BSC Testnet

bsc_testnet

Internal testnet deployment

Prerequisites

  • Node.js 24.22.1 LTS is required exactly for development and deployment (nvm use reads the repository's .nvmrc)

    • Every other Node.js version is rejected so the tested runtime and the 2026-10-21 security fixes remain consistent across environments

  • Optional but recommended:

    • TRONGRID_API_KEY for more reliable TRON access

    • dedicated TRON_FULL_NODE and TRON_NILE_FULL_NODE

    • dedicated ETH_RPC_URL

    • dedicated BSC_RPC_URL

    • dedicated ETH_SEPOLIA_RPC_URL and BSC_TESTNET_RPC_URL

Developer

Installation

git clone https://github.com/decentralized-usd/mcp-server-usdd
cd mcp-server-usdd
nvm install
nvm use
npm ci

Usage

npm start
npm run start:http
npm run dev

Configuration

Wallet Modes

The server supports two signing modes:

  • Browser mode (recommended): connect a TronLink-compatible browser wallet and sign in browser.

  • Agent mode: use encrypted local private keys stored in ~/.agent-wallet/.

For TRON writes, each Claude session shows a one-time signing-mode confirmation reminder before the first write.

You can also manage wallets via CLI or MCP tools:

CLI (agent-wallet)

The server uses @bankofai/agent-wallet for encrypted local wallet storage. On first startup it will automatically initialize ~/.agent-wallet/ and create a default wallet if none exists.

# Import an existing private key or mnemonic
npx agent-wallet add

# Generate a new wallet
npx agent-wallet generate

# List all wallets
npx agent-wallet list

# Switch active wallet
npx agent-wallet activate <wallet-id>

MCP Tools (runtime)

Tool

Description

get_wallet_address

Shows current address

connect_browser_wallet

Connect TronLink / browser wallet for signing

set_wallet_mode

Switch between browser and agent signing

get_wallet_mode

Show current signing mode and addresses

list_wallets

List wallets with per-family active status (tron and evm)

set_active_wallet

Switch active wallet by ID, optionally scoped by walletType (tron/evm)

Client Configuration

Claude Desktop

Add the following config to:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mcp-server-usdd": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@usdd/mcp-server-usdd"],
      "env": {
        "TRONGRID_API_KEY": "your_trongrid_api_key"
      }
    }
  }
}

Claude Code

Create .mcp.json in the project root directory:

{
  "mcpServers": {
    "mcp-server-usdd": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@usdd/mcp-server-usdd"],
      "env": {
        "TRONGRID_API_KEY": "your_trongrid_api_key"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "mcp-server-usdd": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@usdd/mcp-server-usdd"],
      "env": {
        "TRONGRID_API_KEY": "your_trongrid_api_key"
      }
    }
  }
}

For live RPC reads, the server also accepts TRON_FULL_NODE, TRON_NILE_FULL_NODE, ETH_RPC_URL, ETH_SEPOLIA_RPC_URL, BSC_RPC_URL, and BSC_TESTNET_RPC_URL. Protocol address lookup is Chainlog-backed: get_protocol_addresses uses a local Chainlog cache when fresh, refreshes from the on-chain Chainlog when needed, and falls back to a complete cache if live RPC is rate-limited. Chainlog root defaults are included for all supported networks and can be overridden with TRON_CHAINLOG_ADDRESS, TRON_NILE_CHAINLOG_ADDRESS, ETH_CHAINLOG_ADDRESS, ETH_SEPOLIA_CHAINLOG_ADDRESS, BSC_CHAINLOG_ADDRESS, and BSC_TESTNET_CHAINLOG_ADDRESS.

Tools

Wallet & Network

Tool

Description

Write?

get_supported_networks

List supported networks

No

set_network

Set default network for one family (tron/eth/bsc), supports aliases like mainnet, nile

Yes

get_network

Get per-family default networks

No

get_wallet_mode

Get active wallet signing mode (agent/browser)

No

set_wallet_mode

Switch active signing mode

Yes

connect_browser_wallet

Connect a browser wallet and activate browser mode

Yes

get_wallet_address

Show current address for the target network

No

list_wallets

List wallets and per-family active pointers (tron/evm)

No

set_active_wallet

Switch active wallet by ID (supports optional walletType)

Yes

import_wallet

Import private key/mnemonic into encrypted local store

Yes

Common

Tool

Description

Write?

get_protocol_addresses

Show Chainlog-backed protocol addresses, configured ilks, and PSM markets

No

get_chainlog_address

Resolve one Chainlog key such as MCD_USDD or MCD_JOIN_ETH_A

No

get_protocol_overview

Show live protocol ceilings and debt metrics alongside configured deployments

No

get_supported_ilks

List configured collateral types and PSM joins

No

get_native_balance

Read native balance (TRX / ETH / BNB)

No

get_token_balance

Read ERC20/TRC20 balance

No

check_allowance

Read ERC20/TRC20 allowance and compare against an optional amount

No

approve_token

Approve token allowance

Yes

Vault

Tool

Description

Write?

get_oracle_status

Inspect oracle and liquidation configuration for an ilk

No

get_user_vaults

List vault IDs for a wallet

No

get_vault_summary

Show collateral, debt, and liquidation metrics

No

analyze_vault_risk

Summarize risk with warnings

No

open_vault

Open a new vault via DSProxy

Yes

deposit_and_mint

Open-and-mint or add collateral and mint

Yes

mint_usdd

Draw more USDD from a vault

Yes

repay_usdd

Repay vault debt

Yes

withdraw_collateral

Withdraw collateral from a vault

Yes

close_vault

Wipe all debt and free collateral

Yes

PSM

Tool

Description

Write?

get_psm_status

Inspect PSM fees and enablement

No

get_psm_metrics

Get PSM swap metrics by route (fromToken/toToken/available/fee)

No

psm_swap_to_usdd

Swap gem into USDD

Yes

psm_swap_from_usdd

Swap USDD into gem

Yes

USDD Savings

Tool

Description

Write?

get_savings_status

Show USDD Savings metrics

No

deposit_savings

Deposit USDD into sUSDD

Yes

withdraw_savings

Withdraw USDD from sUSDD

Yes

Token Transfers

Two-step preview → confirm flow for safe asset transfers. The AI must present the transfer details to the user and wait for explicit confirmation before executing.

Tool

Description

Write?

prepare_token_transfer

Preview a native or token transfer; returns a confirmationId and transfer details for user review

No

confirm_token_transfer

Execute a previously prepared transfer after user has explicitly confirmed

Yes

Supports:

  • TRX (TRON native)

  • TRC20 tokens (USDD, USDT, WBTC, etc.)

  • ETH / BNB (EVM native)

  • ERC20 tokens on Ethereum and BSC

Protocol Metrics

Read-only analytics from mainnet data feeds.

Tool

Description

Write?

get_protocol_metrics

Aggregated USDD protocol metrics (mainnet)

No

get_chain_metrics

Chain-level metrics for tron, eth, or bsc

No

get_collateral_prices

Latest collateral highest-price data from website API

No

get_psm_metrics

PSM route metrics: fromToken, toToken, available liquidity, fees

No

Treasury

Tool

Description

Write?

get_treasury_summary

Latest USDD treasury report summary (mainnet)

No

get_jst_buyback_stats

JST buyback and burn statistics from treasury data

No

Smart Allocator

Tool

Description

Write?

get_smart_allocator_overview

Smart Allocator overview: debt, invested amount, earnings, APY

No

get_assets_breakdown

Invested-asset breakdown by protocol, network, or asset

No

get_proof_of_reserve

Proof-of-reserve style platform investment details

No

get_debt_overview

Debt overview grouped by network vault

No

Prompts

Prompt

Description

open_usdd_vault

Open a vault and verify post-trade risk

manage_vault_lifecycle

Run full vault lifecycle flows

use_psm

Use PSM with fee checks

use_savings

Use USDD Savings with inspection and verification

review_vault_risk

Explain risk for a vault

repay_and_close_vault

Repay and close with verification

Architecture

mcp-server-usdd/
├── src/
│   ├── core/
│   │   ├── chains.ts
│   │   ├── abis.ts
│   │   ├── tools.ts
│   │   ├── prompts.ts
│   │   ├── resources.ts
│   │   ├── browser-signer.ts
│   │   └── services/
│   │       ├── clients.ts
│   │       ├── contracts.ts
│   │       ├── protocol.ts
│   │       ├── vault.ts
│   │       ├── psm.ts
│   │       ├── savings.ts
│   │       ├── tokens.ts
│   │       ├── transfer.ts        ← token/native transfer (prepare + confirm)
│   │       ├── treasury.ts        ← treasury report and JST buyback stats
│   │       ├── smart-allocator.ts ← Smart Allocator analytics
│   │       ├── website-metrics.ts ← protocol metrics, chain metrics, collateral prices
│   │       ├── wallet.ts
│   │       └── utils.ts
│   ├── index.ts
│   └── server/
│       ├── server.ts
│       └── http-server.ts
└── build/

Notes

  • Vault writes assume the configured wallet can sign on the target chain.

  • Chain-dependent tools require an explicit network argument. If the user has not named a chain, ask which network to use before calling any chain-dependent tool; do not infer TRON or use set_network defaults as an implicit choice.

  • ERC20/TRC20 flows often require approve_token first.

  • Browser mode now supports real transaction signing on TRON networks (tron, tron_nile) via tronlink-signer (TronLink/TIP-6963 flow). EVM networks currently continue to use agent-wallet signing.

  • deposit_and_mint is idempotent with respect to vault creation: it checks for an existing vault for the given ilk before opening a new one. If no vault exists, it submits two separate transactions — open then lockGemAndDraw — to avoid combined-tx reliability issues on TRON.

  • Token transfers use a two-step flow: prepare_token_transfer returns a preview and confirmationId; confirm_token_transfer executes only after the user explicitly approves. Pending confirmations expire after 10 minutes.

  • Protocol analytics tools (get_protocol_metrics, get_chain_metrics, get_collateral_prices, etc.) read from mainnet data feeds only — they do not reflect testnet state.

  • TRON, ETH, BSC, and internal testnet deployments have similar protocol structure but different addresses and token decimals.

  • This version intentionally excludes migration and auction actions so we can iterate the Vault + PSM + USDD Savings core first.

Security Considerations

  • Private keys are encrypted and stored locally in ~/.agent-wallet/.

  • Private keys are never returned by MCP tools.

  • The optional AGENT_WALLET_PASSWORD is intended for automation and CI environments.

  • Write operations should be treated as state-changing actions and reviewed carefully before execution.

  • Vault prompts include risk-review steps so borrowing decisions are checked against current collateral health.

  • Test on a safe environment or with small amounts before using mainnet-sized positions.

  • Be cautious with large or unlimited token approvals when using approve_token.

  • Never share local MCP client configuration files if they contain private keys or sensitive RPC credentials.

Example Conversations

Vault

  • "What vault types are available on Ethereum?" → AI calls get_supported_ilks with network=eth and summarizes the supported vault collateral types.

  • "Open a TRX-A/USDT-A/WBTC-A vault on Tron and mint 500 USDD" → AI uses open_usdd_vault: checks wallet, reviews oracle status, executes deposit_and_mint (auto-opens a new vault if none exists for that ilk), then verifies the new vault risk.

  • "Am I close to liquidation on vault 123?" → AI calls get_vault_summary and analyze_vault_risk, then explains the health factor and collateral buffer.

  • "Repay part of my vault debt on BSC" → AI uses manage_vault_lifecycle with action=repay: checks USDD balance and allowance, calls repay_usdd, then verifies the updated vault state.

  • "Close my vault and withdraw the collateral" → AI uses repay_and_close_vault: checks debt, balance, allowance, calls close_vault, then confirms the vault state after repayment.

PSM

  • "What are the current PSM fees on Ethereum?" → AI calls get_psm_status with network=eth and reports fee-in, fee-out, and whether swaps are enabled.

  • "Show me available PSM liquidity for USDT on TRON" → AI calls get_psm_metrics with the PSM-USDT market and reports available amounts and fees for both directions.

  • "Swap 10,000 USDT into USDD through the PSM" → AI uses use_psm: checks PSM status, then calls psm_swap_to_usdd and reports the transaction result.

  • "Swap 5,000 USDD back to USDC on BSC" → AI calls get_psm_status, then executes psm_swap_from_usdd and reminds the user to re-check balances.

Token & Balances

  • "What is my USDD balance on Tron?" → AI calls get_protocol_addresses to identify the USDD token address from Chainlog/cache, then calls get_token_balance.

  • "Do I have enough allowance for the USDT PSM?" → AI calls check_allowance with the token and PSM spender, then suggests approve_token only if needed.

  • "Send 100 USDD to TXxxx... on Tron" → AI calls prepare_token_transfer and displays the transfer preview (from, to, amount, balance). After the user confirms, AI calls confirm_token_transfer to execute.

  • "Transfer 0.5 ETH to 0xabc..." → AI calls prepare_token_transfer for native ETH, presents the details, then waits for user approval before executing.

USDD Savings

  • "What is the current USDD Savings status on Ethereum?" → AI calls get_savings_status and summarizes total assets, savings rate, and wallet shares.

  • "Deposit 2,000 USDD into sUSDD" → AI uses use_savings: checks savings status, calls deposit_savings, then re-checks savings metrics.

  • "Withdraw 500 USDD from sUSDD on BSC" → AI calls get_savings_status, executes withdraw_savings, and confirms the updated share balance.

Protocol Analytics

  • "What are the overall USDD protocol metrics?" → AI calls get_protocol_metrics and reports total collateral, debt ceiling, and utilization.

  • "Show me TRON chain metrics" → AI calls get_chain_metrics with chain=tron and summarizes collateral breakdown and USDD supply on TRON.

  • "What are the latest collateral prices?" → AI calls get_collateral_prices and lists each collateral type with its current highest price.

Treasury & Smart Allocator

  • "Show me the USDD treasury summary" → AI calls get_treasury_summary and reports reserve breakdown, collateral ratio, and recent changes.

  • "How much JST has been bought back and burned?" → AI calls get_jst_buyback_stats and summarizes cumulative JST buyback volume and burn totals.

  • "What is the Smart Allocator overview?" → AI calls get_smart_allocator_overview and reports total debt allocated, current invested amount, accumulated earnings, and APY.

  • "Break down Smart Allocator investments by protocol" → AI calls get_assets_breakdown with dimension=protocol and lists each DeFi protocol with its allocated amount.

  • "Show me the Smart Allocator proof of reserve" → AI calls get_proof_of_reserve and details each platform investment with amounts and verification status.

  • "What does the Smart Allocator debt look like by network?" → AI calls get_debt_overview and summarizes debt positions grouped by TRON/ETH/BSC vaults.

License

MIT License Copyright (c) 2026 USDD

Available Tools

44 tools
analyze_vault_riskB

Get risk analysis for one vault with warnings.

Inputs: cdpId (required), network.

approve_tokenA

Approve an ERC20/TRC20 token spender. Use before ERC20 collateral or PSM writes when needed.

Inputs: token (required), spender (required), amount (required), decimals, +1 more.

check_allowanceA

Check ERC20/TRC20 allowance for a spender, optionally against a required amount.

Inputs: token (required), spender (required), owner, amount, +2 more.

close_vaultC

Repay all debt and free collateral using wipeAllAndFree* proxy actions.

Inputs: cdpId (required), ilk (required), amountToFree (required), network.

confirm_token_transferA

Execute a previously prepared transfer. IMPORTANT: MUST ONLY be called after the human user has explicitly reviewed the prepare_token_transfer output and verbally confirmed they want to proceed (e.g. 'yes', 'confirm', 'go ahead'). Never call this automatically right after prepare_token_transfer — always wait for the user's explicit approval first.

Inputs: confirmationId (required), confirm (required).

connect_browser_walletB

Connect a browser wallet (TronLink-compatible) and switch to browser mode.

Inputs: network, address.

deposit_and_mintA

Deposit collateral and mint USDD. If cdpId is omitted, reuses an existing vault for the ilk if one exists; otherwise opens a new vault and funds it in one transaction.

Inputs: ilk (required), collateralAmount (required), drawAmount (required), cdpId, +2 more.

deposit_savingsC

Deposit USDD into sUSDD where supported.

Inputs: amount (required), network.

get_assets_breakdownA

Get Smart Allocator invested-asset breakdown by protocol, network, or asset.

Inputs: dimension (required).

get_chain_metricsC

Get chain-level core metrics from website data (mainnet).

Inputs: chain (required).

get_collateral_pricesA

Get latest collateral highest-price data from website API (mainnet).

Inputs: no named parameters.

get_debt_overviewA

Get Smart Allocator debt overview grouped by network vault.

Inputs: no named parameters.

get_jst_buyback_statsA

Get JST buyback/burn statistics from treasury report data (mainnet data).

Inputs: no named parameters.

get_native_balanceA

Get native token balance (TRX/ETH/BNB) for the configured wallet or a specified owner.

Inputs: owner, network.

get_networkB

Get per-family default networks.

Inputs: no named parameters.

get_oracle_statusB

Inspect liquidation ratio, penalty, and oracle status for a collateral type.

Inputs: ilk (required), network.

get_proof_of_reserveB

Get Smart Allocator proof-of-reserve style platform investment details.

Inputs: no named parameters.

get_protocol_metricsB

Get aggregated protocol metrics from website data (mainnet).

Inputs: no named parameters.

get_protocol_overviewB

Get protocol addresses, ceilings, configured ilks, and PSM markets for USDD.

Inputs: network.

get_psm_metricsA

Get PSM swap metrics by route, including fromToken/toToken/available/fee.

Inputs: market (required), network.

get_psm_statusC

Inspect PSM fees and enablement state.

Inputs: market (required), network.

get_savings_statusB

Inspect USDD Savings metrics where supported.

Inputs: network.

get_smart_allocator_overviewA

Get Smart Allocator overview (debt, invested amount, earnings, APY).

Inputs: no named parameters.

get_supported_ilksB

List configured collateral types and PSM joins for a network.

Inputs: network.

get_supported_networksB

List supported USDD networks.

Inputs: no named parameters.

get_token_balanceA

Get ERC20/TRC20 token balance for the configured wallet or a specified owner.

Inputs: token (required), owner, decimals, network.

get_treasury_summaryA

Get latest USDD treasury report summary (mainnet data).

Inputs: no named parameters.

get_user_vaultsA

List all vault IDs for the configured wallet or a given address.

Inputs: address, network.

get_vault_summaryB

Get collateral, debt, and liquidation metrics for one vault.

Inputs: cdpId (required), network.

get_wallet_addressC

Get wallet status and active address for a network.

Inputs: network.

get_wallet_modeB

Get current signing mode (browser / agent) and active address.

Inputs: network.

import_walletA

Import a private key or mnemonic into the encrypted local wallet store.

Inputs: walletType (required), secretType (required), secret (required), index.

list_walletsA

List encrypted wallets stored in ~/.agent-wallet and show which ones are active.

Inputs: no named parameters.

mint_usddC

Draw additional USDD debt from an existing vault.

Inputs: cdpId (required), amount (required), network.

open_vaultA

Open a vault/CDP via DSProxy. Idempotent: if a vault for the given ilk already exists, returns the existing CDP id without submitting a transaction.

Inputs: ilk (required), network.

prepare_token_transferA

Prepare a native/token transfer and return a preview for user review. After calling this tool, you MUST present the transfer details to the user and wait for their explicit confirmation before calling confirm_token_transfer. Do NOT proceed automatically.

Inputs: to (required), amount (required), tokenAddress, decimals, +1 more.

psm_swap_from_usddC

Swap USDD into the PSM gem asset.

Inputs: market (required), amount (required), network.

psm_swap_to_usddC

Swap gem collateral into USDD through the PSM.

Inputs: market (required), amount (required), network.

repay_usddC

Repay USDD debt for an existing vault.

Inputs: cdpId (required), amount (required), network.

set_active_walletA

Set the active encrypted wallet by ID. Active wallet selection is tracked separately for tron and evm.

Inputs: walletId (required), walletType.

set_networkA

Set default network for one family. Supports aliases (tron_mainnet, tron_nile, eth_mainnet, eth_sepolia, bsc_mainnet, bsc_testnet) or explicit network keys.

Inputs: network (required), family.

set_wallet_modeB

Switch signing mode between browser and agent.

Inputs: mode (required), network.

withdraw_collateralC

Withdraw collateral from an existing vault.

Inputs: cdpId (required), ilk (required), amount (required), network.

withdraw_savingsC

Withdraw USDD from sUSDD where supported.

Inputs: amount (required), network.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 44 tools

    Disambiguation2/5

    Most write/management tools are distinct, but the read-only side has several clusters with fuzzy boundaries: get_protocol_overview duplicates much of get_supported_ilks/get_psm_status, get_chain_metrics vs get_protocol_metrics are hard to distinguish, and the Smart Allocator tools (overview, proof_of_reserve, debt_overview, assets_breakdown) overlap heavily. Wallet status is also split across get_wallet_mode, get_wallet_address, and list_wallets, so misselection is plausible.

    Naming Consistency4/5

    Names are consistently snake_case and almost always begin with a verb such as get, set, list, import, check, prepare, confirm, approve, open, mint, repay, withdraw, or close. A few compound names like deposit_and_mint and psm_swap_to_usdd are minor deviations, but the overall convention is predictable.

    Tool Count2/5

    At 44 tools, the surface exceeds the comfortable range for a single MCP server. Even though the domain spans wallets, vaults, PSM, savings, and analytics, many tools are read-only report variants that add bulk and could be consolidated.

    Completeness4/5

    The vault lifecycle is covered end-to-end with open, mint, repay, withdraw, and close, and PSM swaps, savings, approvals, transfers, and wallet management are all represented. No obvious dead-end prevents core operations, though a few reporting endpoints feel redundant and there is no transaction-status/receipt tool, so minor gaps exist.

    Related MCP Connectors

    Related MCP Servers