Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

MCP Server

What It Is

The USDD MCP Server is a Model Context Protocol implementation that allows AI agents to interact with the USDD decentralized stablecoin protocol across TRON, Ethereum, and BNB Smart Chain. The server enables both core protocol operations — Vault/CDP, PSM, and Savings — and general-purpose chain utilities such as token balance queries and allowance management.

GitHub: https://github.com/decentralized-usd/mcp-server-usdd

Key Capabilities

USDD Protocol

  • Vault / CDP: Full vault lifecycle management — open vaults, deposit collateral, mint USDD, repay debt, withdraw, and close. Includes real-time oracle and liquidation configuration per collateral type.

  • Vault Risk Monitoring: AI-guided risk assessment with collateral ratio checks, liquidation threshold warnings, and vault health summaries.

  • PSM (Peg Stability Module): Real-time fee and enablement status for each PSM. Swap supported stablecoins into USDD or redeem USDD back to the underlying gem.

  • USDD Savings: Inspect current savings rate, sUSDD metrics, and wallet share positions. Deposit and withdraw USDD through the savings module.

  • Token Approvals: Check allowances and approve token spending for USDD protocol interactions.

General Chain

  • Balances: Native (TRX / ETH / BNB) and ERC20 / TRC20 token balances across TRON, Ethereum, and BNB Smart Chain (plus internal testnets).

  • Allowances & Approvals: Read token allowance for any spender, compare against a required amount, and approve token spending for USDD protocol interactions.

  • Protocol Discovery: Configured contract addresses, collateral types (ilks), PSM joins, and debt ceilings per network.

  • Networks: Supported network list with chain keys (tron, eth, bsc + internal testnets); per-family default network selection with aliases (mainnet, nile).

  • Wallet: Signing-address resolution per network, dual signing modes (browser / agent), and wallet management — connect browser wallet, list / switch / import wallets.

  • Token Transfers: Two-step preview → confirm flow for safe asset transfers across TRX, TRC20, ETH / BNB native, and ERC20. The AI must present transfer details and wait for explicit user confirmation; pending previews expire after 10 minutes.

Protocol Analytics

  • Protocol & Chain Metrics: Aggregated USDD protocol metrics and per-chain metrics (collateral breakdown, USDD supply, utilization) from mainnet data feeds.

  • Collateral Prices: Latest highest-price data per collateral type from the website API.

  • Treasury: Latest USDD treasury report summary and JST buyback & burn statistics.

  • Smart Allocator: Investment overview (debt, invested amount, earnings, APY), asset breakdown by protocol / network / asset, proof-of-reserve platform details, and debt overview grouped by network vault.

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 20+

  • Optional but recommended:

    • TRONGRID_API_KEY for more reliable TRON access

    • dedicated ETH_RPC_URL

    • dedicated BSC_RPC_URL

Developer

Installation

Usage

Configuration

Wallet Modes

Mode
When to use
Key storage

Browser (TronLink-compatible)

Sign in a browser extension (TronLink)

Wallet extension

Agent

Automation / CI / headless; required for EVM signing

Encrypted local file under ~/.agent-wallet/, never exported

Private keys are never returned by any MCP tool.

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.

Wallet management MCP tools(runtime)

get_wallet_address

Shows current address (auto-generates wallet if needed)

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)

Environment Variables

Client Configuration

Claude Desktop

Add the following config to:

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

Claude Code

Create .mcp.json in the project root directory:

Cursor

Add to .cursor/mcp.json:

Tools

Side-Effect & Risk Classification

All tools are classified by side-effect level. Hosts MUST surface remote-write and destructive operations to the user before execution.

Level
Definition
Tools

safe

Pure local read, no network

get_supported_networks,

get_network,

get_wallet_mode,

get_wallet_address,

list_wallets

network-read

Read-only on-chain or HTTP query

get_protocol_overview,

get_supported_ilks,

get_native_balance,

get_token_balance,

check_allowance,

get_oracle_status,

get_user_vaults,

get_vault_summary,

analyze_vault_risk,

get_psm_status,

get_savings_status,

get_protocol_metrics,

get_chain_metrics,

get_collateral_prices,

get_psm_metrics,

get_treasury_summary, get_jst_buyback_stats,

get_smart_allocator_overview,

get_assets_breakdown,

get_proof_of_reserve,

get_debt_overview

local-write

Modifies local config / wallet store

set_network,

set_wallet_mode,

set_active_wallet,

import_wallet,

connect_browser_wallet

remote-write

Broadcasts a tx, costs gas, HITL required

approve_token,

open_vault,

deposit_and_mint,

mint_usdd,

repay_usdd,

withdraw_collateral,

psm_swap_to_usdd,

psm_swap_from_usdd,

deposit_savings,

withdraw_savings,

prepare_token_transfer,

confirm_token_transfer,

close_vault

Safe to retry: safe, network-read, and all prepare_* previews. NOT safe to retry: every remote-write tool — a duplicate call may broadcast a second tx.

Wallet & Network

Tool
Description
Write?
Input schema

get_supported_networks

List supported networks

No

—

set_network

Set the default network for a family (tron/eth/bsc); accepts mainnet / nile aliases

Yes

Required: network: string (key or alias) · Optional: family: "tron" \| "eth" \| "bsc"

get_network

Show per-family default networks

No

—

get_wallet_mode

Show current signing mode and addresses

No

Optional: network

set_wallet_mode

Switch signing mode: agent / browser

Yes

Required: mode: "browser" \| "agent" · Optional: network

connect_browser_wallet

Connect a browser wallet and activate browser mode

Yes

Optional: network, address: string

get_wallet_address

Show the current address for the target network

No

Optional: network

list_wallets

List wallets with tron and evm active pointers

No

—

set_active_wallet

Switch active wallet by ID (optional walletType: tron/evm)

Yes

Required: walletId: string · Optional: walletType: "tron" \| "evm"

import_wallet

Import a private key / mnemonic into the encrypted keystore

Yes

Required: walletType: "tron" \| "evm", secretType: "private_key" \| "mnemonic", secret: string · Optional: index: int ≥ 0 (mnemonic derivation index, default 0)

Common

Tool
Description
Write?
Input schema

get_protocol_overview

Protocol addresses, ilks, PSMs, debt ceilings

No

Optional: network

get_supported_ilks

Configured collateral types and PSM joins

No

Optional: network

get_native_balance

Read TRX / ETH / BNB balance

No

Optional: owner: string (defaults to active wallet), network

get_token_balance

Read ERC20 / TRC20 balance

No

Required: token: string (contract) · Optional: owner: string, decimals: int > 0, network

check_allowance

Read allowance, optionally compare against an amount

No

Required: token: string, spender: string · Optional: owner: string, amount: string (human-readable), decimals: int > 0, network

approve_token

Approve a token allowance

Yes

Required: token: string, spender: string, amount: string (human-readable or "max") · Optional: decimals: int > 0, network

Vault

Tool
Description
Write?
Input schema

get_oracle_status

Inspect oracle and liquidation configuration for an ilk

No

Required: ilk: string (e.g. TRX-A, WBTC-A, USDT-A, PSM-USDT) · Optional: network

get_user_vaults

List vault IDs for a wallet

No

Optional: address: string, network

get_vault_summary

Collateral, debt, and liquidation metrics

No

Required: cdpId: string · Optional: network

analyze_vault_risk

Risk summary with warnings

No

Required: cdpId: string · Optional: network

open_vault

Open a new vault via DSProxy

Yes

Required: ilk: string · Optional: network

deposit_and_mint

Open-and-mint, or add collateral and mint (idempotent: reuses an existing vault for the same ilk)

Yes

Required: ilk: string, collateralAmount: string, drawAmount: string · Optional: cdpId: string (reuses if omitted), transferFrom: boolean (default true), network

mint_usdd

Draw more USDD from a vault

Yes

Required: cdpId: string, amount: string · Optional: network

repay_usdd

Repay vault debt

Yes

Required: cdpId: string, amount: string · Optional: network

withdraw_collateral

Withdraw collateral from a vault

Yes

Required: cdpId: string, ilk: string, amount: string · Optional: network

close_vault

Wipe all debt and free all collateral

Yes

Required: cdpId: string, ilk: string, amountToFree: string · Optional: network

PSM

Tool
Description
Write?
Input schema

get_psm_status

PSM fees and enablement

No

Required: market: string (e.g. PSM-USDT) · Optional: network

get_psm_metrics

PSM route metrics (from / to / available / fee)

No

Required: market: string · Optional: network

psm_swap_to_usdd

Swap gem into USDD

Yes

Required: market: string, amount: string · Optional: network

psm_swap_from_usdd

Swap USDD into gem

Yes

Required: market: string, amount: string · Optional: network

USDD Savings

Tool
Description
Write?
Input schema

get_savings_status

USDD Savings metrics

No

Optional: network

deposit_savings

Deposit USDD to receive sUSDD

Yes

Required: amount: string · Optional: network

withdraw_savings

Redeem USDD from sUSDD

Yes

Required: amount: string · Optional: network

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.

Supports: TRX, TRC20, ETH / BNB, ERC20. Pending confirmations expire after 10 minutes

Tool
Description
Write?
Input schema

prepare_token_transfer

Preview a transfer; returns a confirmationId and details

No

Required: to: string, amount: string (human-readable) · Optional: tokenAddress: string (omit for native), decimals: int > 0, network

confirm_token_transfer

Execute the previewed transfer after user confirmation

Yes

Required: confirmationId: string, confirm: boolean (pass false to cancel)

Protocol Metrics

Tool
Description
Write?
Input schema

get_protocol_metrics

Aggregated USDD protocol metrics

No

—

get_chain_metrics

Chain-level metrics for tron / eth / bsc

No

Required: chain: "tron" \| "eth" \| "bsc"

get_collateral_prices

Latest highest-price data per collateral

No

—

get_psm_metrics

PSM route metrics (from / to / available / fee) — also listed under §8.4 PSM

No

Required: market: string · Optional: network

Treasury

Tool
Description
Write?
Input schema

get_treasury_summary

Latest USDD treasury report summary

No

—

get_jst_buyback_stats

JST buyback and burn statistics

No

—

Smart Allocator

Tool
Description
Write?
Input schema

get_smart_allocator_overview

Overview: debt, invested amount, earnings, APY

No

—

get_assets_breakdown

Breakdown by protocol / network / asset

No

Required: dimension: "protocol" \| "network" \| "asset"

get_proof_of_reserve

Proof-of-reserve style platform investment details

No

—

get_debt_overview

Debt overview grouped by vault per network

No

—

Output Contract

Every tool returns the standard MCP content envelope. The text field is a JSON string (utils.formatJson(...)) of the payload below.

Success — read tools

Success — write tools (remote-write ) — always includes the broadcast result + a human-readable message:

confirm_token_transfer wraps this as { confirmationId, status: "success" | "cancelled", result }.

Representative read payloads :

  • get_vault_summary → { cdpId, owner, proxyAddress, ilk, collateralAmount, collateralAmountRaw, normalizedDebt, debtAmount, walletUsddBalance, debtCeiling, ... }

  • approve_token → { token, spender, amount, amountRaw, message }

  • get_user_vaults → { network, address, vaultIds: string[] }

Error envelope: { "content": [ { "type": "text", "text": "Error: <message>" } ], "isError": true }

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

prepare_token_transfer

Transfer tokens with two-step preview and explicit confirmation

Notes

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

  • All tools default to the family-specific defaults set by set_network; if network is omitted, tron-family default is used unless the tool call explicitly passes network.

  • 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 Model

Wallet & keys

  • 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.

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

HITL boundary

Only one HITL boundary is enforced by the server: confirm_token_transfer requires a confirmationId previously issued by prepare_token_transfer, which expires after 10 minutes.

The server also enforces one session-level prompt: before the first TRON write in any Claude session, the user must confirm the signing mode (wallet.ts:465).

For all other write tools (approve_token, every vault write, PSM swaps, savings deposit/withdraw), HITL is enforced by the MCP host’s confirmation dialog — the server does not intercept the call. Documentation should recommend that hosts confirm every tool marked Write? = Yes by default.

Operational risk

  • Treat write operations as state-changing actions and review them carefully.

  • 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.

Troubleshooting

Health check

MCP Inspector

Common errors

Symptom / error message
Source
Fix

Unsupported network: …

chains.ts

Use a key from §3 (note underscores)

Insufficient … balance.

transfer.ts

Check on-chain balance

Unable to detect token decimals …

transfer.ts

Pass decimals explicitly to prepare_token_transfer

Unknown confirmationId …

tools.ts

Already consumed or server restarted; call prepare again

This confirmation has expired.

tools.ts

Over 10 minutes; call prepare again

STOP — TRON wallet signing mode has not been confirmed …

wallet.ts

Call set_wallet_mode or confirm the default mode

Browser wallet signing is only supported for TRON networks …

wallet.ts

Use agent mode for EVM writes

Versioning & Compatibility

Field
Value
Source

Package name

@usdd/mcp-server-usdd

package.json

Package version

1.0.3

package.json

MCP SDK

@modelcontextprotocol/sdk@1.27.1

package.json

Node.js

>= 20.0.0

package.json#engines

TypeScript

5.9.3

devDependencies

License

MIT (SPDX: MIT), Copyright © 2026 USDD

LICENSE

Repository

https://github.com/decentralized-usd/mcp-server-usdd

package.json

Transports:

Transport
Command
Status

stdio

npm start / npx -y @usdd/mcp-server-usdd

Production-ready

HTTP

npm run start:http

Currently exposes only /health; no MCP transport mounted. Use for liveness probes only.

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_overview to identify the USDD token address, 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.

Architecture

PreviousUSDD Public APINextUSDD Skills

Last updated